github: Add checker for docs links

.github/workflows/check-docs-links.yml

@@ -0,0 +1,46 @@
+
+# Test docs/ links are valid.
+# 
+# htmltest https://github.com/wjdp/htmltest-action/
+# hugo https://github.com/peaceiris/actions-hugo
+# upload test results https://github.com/actions/upload-artifact
+
+name: check-doc-links
+
+on: pull_request
+jobs:
+  htmltest:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive # Fetch Hugo themes
+          fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
+
+      - uses: actions/checkout@v4
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Set up Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: '0.117.0'
+          extended: true
+
+      - name: Build Hugo
+        run: hugo -s docs -d $GITHUB_WORKSPACE/dist
+
+      - name: Run htmltest
+        uses: wjdp/htmltest-action@master
+        with:
+          path: dist
+          config: docs/.htmltest.yml
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: htmltest-output
+          path: dist

cmd/porter/mixins.go

@@ -164,7 +164,7 @@ bin/
     ├── mymixin-linux-amd64
     └── mymixin-windows-amd64.exe
 
-See https://porter.sh/mixin-dev-guide/distribution more details.
+See https://porter.sh/docs/development/dist-a-mixin/ more details.
 `,
 		Example: `  porter mixin feed generate
   porter mixin feed generate --dir bin --file bin/atom.xml --template porter-atom-template.xml`,

docs/.htmltest.yml

@@ -0,0 +1,14 @@
+IgnoreURLs:
+  - ^/forum$
+  - ^/zoom/dev/$
+  - ^/dev-meeting$
+  - ^/calendar/$
+  - ^/find-issue/$
+  - ^/board/
+  - ^/roadmap
+  - ^/src
+  - ^/examples
+  - ^/forum
+  - ^/docker-mixin/src
+IgnoreAltMissing: true
+IgnoreInternalEmptyHash: true

docs/content/architecture-buildtime.md

@@ -19,22 +19,22 @@ Porter does not support specifying which version of a mixin to use in a bundle y
 You can follow the [Mixins are Bundles proposal](https://github.com/getporter/proposals/blob/main/pep/005-mixins-are-bundles.md) to keep track of that feature's progress.
 
 When the bundle author runs `porter build`, Porter first generates a Dockerfile to create an image for the bundle (known as the invocation image or installer).
-You can define your own [custom Dockerfile](/bundle/custom-dockerfile/) to customize and optimize the image.
+You can define your own [custom Dockerfile](/docs/bundle/custom-dockerfile/) to customize and optimize the image.
 The Dockerfile contains the following: a base image (debian), additional customizations generated by the mixins, and a COPY statement to include the files contained in the bundle directory where the porter.yaml file is located.
 A copy of the Porter runtime, the mixin runtimes and the porter.yaml file are copied into the bundle.
 After the image is built, Porter then generates a CNAB-compliant bundle.json file that defines the bundle's metadata.
 
 # See Also
 
-* [Create a bundle](/bundle/create/)
-* [Use a custom Dockerfile](/bundle/custom-dockerfile/)
-* [Mixin Architecture](/how-to-guides/work-with-mixins)
-* [Distribute a bundle](/distribute-bundles/)
+* [Create a bundle](/docs/getting-started/create-bundle/)
+* [Use a custom Dockerfile](/docs/bundle/custom-dockerfile/)
+* [Mixin Architecture](/docs/how-to-guides/work-with-mixins/)
+* [Distribute a bundle](/distributing-bundles/)
 * [Porter Runtime](/architecture-runtime/)
 
-[manifest]: /bundle/manifest/
-[Parameters]: /parameters/
-[Credentials]: /credentials/
-[Outputs]: /bundle/manifest/#outputs
+[manifest]: /docs/bundle/manifest/
+[Parameters]: /docs/introduction/concepts-and-components/intro-parameters/
+[Credentials]: /docs/introduction/concepts-and-components/intro-credentials/
+[Outputs]: /docs/bundle/manifest/#outputs
 [Mixins]: /mixins/
-[Actions]: /bundle/manifest/#bundle-actions
+[Actions]: /docs/bundle/manifest/#bundle-actions

docs/content/architecture.md

@@ -22,7 +22,7 @@ The bundle author then builds the bundle into an OCI artifact which includes a d
 Once a bundle is built, it can be distributed using Docker / OCI registries.
 This allows you to use existing tools and infrastructure to share your application with other teams, customers, and end-users.
 
-Because the bundle contains everything you need to deploy, included referenced images, you can even [move a bundle into a disconnected or airgapped environment](/administration/move-bundles-airgapped/).
+Because the bundle contains everything you need to deploy, included referenced images, you can even [move a bundle into a disconnected or airgapped environment](/docs/administration/move-bundles-airgapped/).
 When written with airgap deployments in mind, a bundle can be deployed anywhere without requiring access to the original network or the internet.
 
 Learn more about [how Porter works at buildtime](/architecture-buildtime/).
@@ -44,8 +44,8 @@ Learn more about [how Porter works at runtime](/architecture-runtime/).
 ## See Also
 
 * [Security Features](/security-features/)
-* [Create a Bundle](/getting-started/create-bundle/)
-* [Distribute Bundles](/development/authoring-a-bundle/distribute-bundles//)
-* [Airgapped Deployments](/administration/move-bundles-airgapped/)
+* [Create a Bundle](/docs/getting-started/create-bundle/)
+* [Distribute Bundles](/docs/development/authoring-a-bundle/distribute-bundles/)
+* [Airgapped Deployments](/docs/administration/move-bundles-airgapped/)
 
 [mixins]: /mixins/

docs/content/archive-bundles.md

@@ -3,7 +3,7 @@ title: Archiving Bundles
 description: Archiving Bundles with Porter
 ---
 
-Porter allows you to share bundles by [publishing](/distribute-bundles) them to an OCI registry. Porter also allows you to copy a bundle from one registry to another. Using these commands, bundle users have flexibility in how they leverage published bundles. What if you want to use a published bundle on a disconnected or edge network that has limited connectivity? The `porter archive` command and the `porter publish` commands allow you to take the bundle from a registry on one network, move it to the network or location, and republish it into another registry for use within that environment. The generated bundle archive contains the CNAB `bundle.json`, along with an OCI [image layout](https://github.com/opencontainers/image-spec/blob/master/image-layout.md) containing the invocation image and any images declared in the `images` section of the `bundle.json`. This enables the entire bundle to be easily moved into a private data center or across an air-gapped network, and republished within that environment.
+Porter allows you to share bundles by [publishing](/distributing-bundles/) them to an OCI registry. Porter also allows you to copy a bundle from one registry to another. Using these commands, bundle users have flexibility in how they leverage published bundles. What if you want to use a published bundle on a disconnected or edge network that has limited connectivity? The `porter archive` command and the `porter publish` commands allow you to take the bundle from a registry on one network, move it to the network or location, and republish it into another registry for use within that environment. The generated bundle archive contains the CNAB `bundle.json`, along with an OCI [image layout](https://github.com/opencontainers/image-spec/blob/master/image-layout.md) containing the invocation image and any images declared in the `images` section of the `bundle.json`. This enables the entire bundle to be easily moved into a private data center or across an air-gapped network, and republished within that environment.
 
 For a working example of how to move a bundle across an airgap, read [Example: Airgapped Environments](/examples/airgap/).
 

docs/content/blog/2023-roadmap.md

@@ -21,7 +21,7 @@ You can find a review of 2022 and our high level plans for 2023 in our [Porter A
 
 ### Porter Operator
 
-The [Porter Operator](/operator/) is a Kubernetes operator that runs bundles on your cluster. With the operator you can:
+The [Porter Operator](/docs/operator/) is a Kubernetes operator that runs bundles on your cluster. With the operator you can:
 
 * Automate running bundles on Kubernetes
 * Upgrade to new versions of bundles when they are released
@@ -31,11 +31,11 @@ Many users, especially adopters with large-scale Porter deployments, are eagerly
 We made great progress on the operator last year and our [v1 milestone](https://github.com/getporter/operator/milestone/1) outlines the remaining work necessary for a stable release.
 
 The operator is ready to try out and we would love your feedback!
-We have a [quickstart](/operator/quickstart/) that walks you through installing the operator and running a bundle. Give it a shot and let us know what you think.
+We have a [quickstart](/docs/operator/quickstart/) that walks you through installing the operator and running a bundle. Give it a shot and let us know what you think.
 
 ### Advanced Dependencies
 
-Porter plans to support advanced workflows and dependency scenarios ([PEP003](https://github.com/getporter/proposals/blob/main/pep/003-dependency-namespaces-and-labels.md)), where users can define bundles that have a complex dependency graph.
+Porter plans to support advanced workflows and dependency scenarios ([PEP003](https://github.com/getporter/proposals/blob/main/pep/003-advanced-dependencies.md)), where users can define bundles that have a complex dependency graph.
 Dependencies may be an interface such as requiring a MySQL database whether it came from a dedicated server, a Helm chart, or a database as a service from a cloud provider.
 Dependencies may also be resolved to existing installations of bundles, such as a shared dev database or a redis instance for the staging environment.
 

docs/content/blog/install-multiple-plugins.md

@@ -40,7 +40,7 @@ installed azure plugin v1.0.1 (e361abc)
 installed kubernetes plugin v1.0.1 (f01c944)
 ```
 
-Make sure to update your current plugins schema file to the [latest format](/reference/file-formats/#plugins) 
+Make sure to update your current plugins schema file to the [latest format](/docs/references/file-formats/plugins/) 
 Please [let us know][contact] how the change went (good or bad), and we are happy to help if you have questions, or you would like help with your migration.
 
 [announced]: https://github.com/docker/roadmap/issues/209

docs/content/blog/migrate-from-docker-app.md

@@ -32,9 +32,52 @@ We will use the [docker-compose mixin] to migrate an existing Docker App to Port
 1. Create a porter.yaml file in the same directory as your docker app next to the docker-compose.yaml.
     Copy into porter.yaml the contents below.
 
-    <script src="https://gist-it.appspot.com/https://github.com/getporter/porter/blob/main/examples/dockerapp/porter.yaml"></script>
+    ```yaml
+    schemaVersion: 1.0.0-alpha.1
+    name: examples/dockerapp
+    version: 0.2.0
+    description: "An example bundle that demonstrates how to move from Docker App to Porter"
+    registry: ghcr.io/getporter
+
+    required:
+    - docker:
+        privileged: false # Change to true if you need privileged containers
+
+    parameters:
+    - name: hello_text
+      type: string
+      env: hello_text
+      default: hello from porter
+    - name: hello_port
+      type: integer
+      env: hello_port
+      default: 8080
+    - name: context
+      type: string
+      default: default
+
+    mixins:
+    - docker-compose
+
+    install:
+    - docker-compose:
+        arguments:
+        - up
+        - -d
+
+    upgrade:
+    - docker-compose:
+        arguments:
+        - up
+        - -d
+
+    uninstall:
+    - docker-compose:
+        arguments:
+        - down
+    ```
 
-1. Open metadata.yaml from your docker app.
+2. Open metadata.yaml from your docker app.
 
     ```yaml
     version: 0.1.0
@@ -45,7 +88,7 @@ We will use the [docker-compose mixin] to migrate an existing Docker App to Port
         email: [email protected]
     ```
 
-1. Open porter.yaml and copy the version, name, and description values into porter.yaml into the corresponding fields.
+3. Open porter.yaml and copy the version, name, and description values into porter.yaml into the corresponding fields.
     Porter doesn't have a field for maintainers, so that doesn't need to be migrated.
 
     ```yaml
@@ -54,7 +97,7 @@ We will use the [docker-compose mixin] to migrate an existing Docker App to Port
     description: My amazing docker app
     ```
 
-1. Open your parameters.yaml. Add each parameter to porter's parameters field.
+4. Open your parameters.yaml. Add each parameter to porter's parameters field.
     If your parameter used a period or other characters that are not allowed in an environment variable name, replace that character with an acceptable substitute such as underscore _.
     Update your docker-compose.yaml to use any of the newly renamed parameters.
 
@@ -78,7 +121,7 @@ We will use the [docker-compose mixin] to migrate an existing Docker App to Port
       default: 8080
     ```
 
-1. Install the bundle with `porter install --allow-docker-host-access`.
+5. Install the bundle with `porter install --allow-docker-host-access`.
    The `--allow-docker-host-access` flag is required so that the bundle can communicate with the docker host.
 
     Porter supports the [DOCKER_HOST and DOCKER_CONTEXT environment variables](https://www.docker.com/blog/how-to-deploy-on-remote-docker-hosts-with-docker-compose/).
@@ -94,23 +137,23 @@ We will use the [docker-compose mixin] to migrate an existing Docker App to Port
     execution completed successfully!
     ```
 
-1. Confirm that your application was deploy with `docker ps`.
+6. Confirm that your application was deploy with `docker ps`.
 
     ```console
     $ docker ps
     CONTAINER ID   IMAGE                 COMMAND                  CREATED          STATUS          PORTS                                       NAMES
     c5428e359333   hashicorp/http-echo   "/http-echo -text 'h…"   27 minutes ago   Up 27 minutes   0.0.0.0:8080->5678/tcp, :::8080->5678/tcp   app_hello_1
     ```
 
-1. You can view your installations with `porter list`:
+7. You can view your installations with `porter list`:
 
     ```console
     $ porter list
     NAME                 CREATED          MODIFIED         LAST ACTION   LAST STATUS
     my-docker-app        28 minutes ago   28 minutes ago   install       succeeded
     ```
 
-1. Let's look at the details of your migrated application with `porter show`.
+8. Let's look at the details of your migrated application with `porter show`.
     The output tells us that it was installed successfully and shows the history of changes made to the installation.
 
     ```console
@@ -133,11 +176,11 @@ We will use the [docker-compose mixin] to migrate an existing Docker App to Port
       01F4YMH7AETP2P38Y81YVQ5TJS  install  28 minutes ago  succeeded  true
     ```
 
-1. So far we have been working inside the "developer iteration loop", where you can edit the bundle on your local filesystem and deploy it to your developer environment to test it.
+9. So far we have been working inside the "developer iteration loop", where you can edit the bundle on your local filesystem and deploy it to your developer environment to test it.
     Once the bundle is stable, the next step is to publish it to an OCI registry so that others can install your bundle using its reference.
     All of the porter commands accept a flag, \--reference, for example `porter install --reference ghcr.io/getporter/examples/porter-hello:v0.2` so that you do not need to distribute the bundle files themselves.
 
-1. When you are ready to share your bundle with others, select which OCI registry where you will host the bundle, for example, `ghcr.io/getporter` or on Docker Hub under your username `carolynvs`.
+10. When you are ready to share your bundle with others, select which OCI registry where you will host the bundle, for example, `ghcr.io/getporter` or on Docker Hub under your username `carolynvs`.
     Edit your porter.yaml and set the registry field to the destination registry.
 
     ```yaml
@@ -147,7 +190,7 @@ We will use the [docker-compose mixin] to migrate an existing Docker App to Port
     registry: carolynvs
     ```
 
-1. Publish your bundle to the destination registry with `porter publish`.
+11. Publish your bundle to the destination registry with `porter publish`.
 
     ```console
     $ porter publish
@@ -180,7 +223,7 @@ We will use the [docker-compose mixin] to migrate an existing Docker App to Port
     The last line of the output prints the full reference to the published bundle, in this case `docker.io/carolynvs/my-docker-app:v0.1.0`.
     You can use or omit the docker.io registry depending on your preference.
 
-1. Now that your bundle is published, let's install it.
+12. Now that your bundle is published, let's install it.
     First change your current directory in your terminal to leave the directory containing your bundle's source code.
     We are going to install the bundle again, this time using the published bundle.
 
@@ -196,21 +239,21 @@ We will use the [docker-compose mixin] to migrate an existing Docker App to Port
     $ porter install my-app --reference carolynvs/my-docker-app:v0.1.0
     ```
 
-1. Oops! You made a mistake in your original bundle and need to fix it.
+13. Oops! You made a mistake in your original bundle and need to fix it.
     Open your porter.yaml file and increase the version number.
 
     ```
     version: 0.1.1
     ```
 
-1. Rebuild the bundle and publish the new version.
+14. Rebuild the bundle and publish the new version.
 
     ```
     porter build
     porter publish
     ```
 
-1. You can use `porter upgrade` to upgrade the installation to the latest version, specifying the newly published version of your bundle.
+15. You can use `porter upgrade` to upgrade the installation to the latest version, specifying the newly published version of your bundle.
 
     ```
     $ porter upgrade my-app --reference YOUR_UPDATED_BUNDLE_REFERENCE --allow-docker-host-access
@@ -223,7 +266,7 @@ We will use the [docker-compose mixin] to migrate an existing Docker App to Port
 
     You can configure Porter to always [allow Docker host access] so that you do not need to set it with a flag on every command.
 
-1. Once you are done, uninstall the bundle with `porter uninstall`.
+16. Once you are done, uninstall the bundle with `porter uninstall`.
 
     ```
     porter uninstall my-app
@@ -236,5 +279,5 @@ Please [let us know][contact] how the migration went (good or bad), and we are h
 [announced]: https://github.com/docker/roadmap/issues/209
 [Install Porter]: /install/
 [docker-compose mixin]: /mixins/docker-compose/
-[allow Docker host access]: /configuration/#allow-docker-host-access
+[allow Docker host access]: /docs/configuration/configuration/#allow-docker-host-access
 [contact]: /community/

docs/content/blog/persist-sensitive-data-safely.md

@@ -19,7 +19,7 @@ Now Porter requires users to configure a secret store to hold any data that has
 
 Let's walk through how to utilize this new feature by updating your Porter configuration file and selecting an appropriate secret plugin. 
 
-First, [install the latest Porter v1 prerelease](/install/#prerelease).
+First, [install the latest Porter v1 prerelease](/docs/getting-started/install-porter/#canary).
 
 Next, let's install a bundle that handles sensitive data using just the default Porter configuration.
 

docs/content/blog/porter-package-search.md

@@ -55,7 +55,7 @@ installed terraform mixin v0.5.1-beta.1 (597a442)
 ```
 
 
-The [Terraform mixin](/mixins/terraform) is now available for use in our next Porter bundle.
+The [Terraform mixin](/mixins/terraform/) is now available for use in our next Porter bundle.
 To peruse the full list of mixins, simply issue `porter mixin search` without
 any query.