docs: fix broken links and improve link resolution

Update the formatting of links and add a Markdown render hook for
handling relative internal links. Cross-references between markdown
files are now resolved the same way in both GitHub and Hugo.

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

.github/workflows/docs.yml

@@ -38,8 +38,6 @@ jobs:
           set: |
             *.cache-from=type=gha,scope=docs
             *.cache-to=type=gha,scope=docs,mode=max
-        env:
-          DOCS_BASEURL: ${{ steps.pages.outputs.base_path }}
       - name: Fix permissions
         run: |
           chmod -c -R +rX "./build/docs" | while read line; do

docker-bake.hcl

@@ -91,15 +91,8 @@ target "image-all" {
   ]
 }
 
-variable "DOCS_BASEURL" {
-  default = null
-}
-
 target "_common_docs" {
   dockerfile = "./dockerfiles/docs.Dockerfile"
-  args = {
-    DOCS_BASEURL = DOCS_BASEURL
-  }
 }
 
 target "docs-export" {

dockerfiles/docs.Dockerfile

@@ -16,9 +16,8 @@ COPY --from=hugo $GOPATH/bin/hugo /bin/hugo
 WORKDIR /src
 
 FROM build-base AS build
-ARG DOCS_BASEURL=/
 RUN --mount=type=bind,rw,source=docs,target=. \
-    hugo --gc --minify --destination /out -b $DOCS_BASEURL
+    hugo --gc --minify --destination /out
 
 FROM build-base AS server
 COPY docs .
@@ -29,8 +28,12 @@ FROM scratch AS out
 COPY --from=build /out /
 
 FROM wjdp/htmltest:v0.17.0 AS test
+# Copy the site to a public/distribution subdirectory
+# This is a workaround for a limitation in htmltest, see:
+# https://github.com/wjdp/htmltest/issues/45
+WORKDIR /test/public/distribution
+COPY --from=build /out .
 WORKDIR /test
-COPY --from=build /out ./public
 ADD docs/.htmltest.yml .htmltest.yml
 RUN --mount=type=cache,target=tmp/.htmltest \
     htmltest

docs/content/about/configuration.md

@@ -434,17 +434,17 @@ The `storage` option is **required** and defines which storage backend is in
 use. You must configure exactly one backend. If you configure more, the registry
 returns an error. You can choose any of these backend storage drivers:
 
-| Storage driver      | Description                                                                                                                                                                                                                                                                              |
-|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `filesystem`        | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](/storage-drivers/filesystem). |
-| `azure`             | Uses Microsoft Azure Blob Storage. See the [driver's reference documentation](/storage-drivers/azure).                                                                                                               |
-| `gcs`               | Uses Google Cloud Storage. See the [driver's reference documentation](/storage-drivers/gcs).                                                                                                                           |
-| `s3`                | Uses Amazon Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](/storage-drivers/s3).                                                                            |
+| Storage driver | Description                                                                                                                                                                                                                 |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `filesystem`   | Uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications. See the [driver's reference documentation](../storage-drivers/filesystem.md). |
+| `azure`        | Uses Microsoft Azure Blob Storage. See the [driver's reference documentation](../storage-drivers/azure.md).                                                                                                                 |
+| `gcs`          | Uses Google Cloud Storage. See the [driver's reference documentation](../storage-drivers/gcs.md).                                                                                                                           |
+| `s3`           | Uses Amazon Simple Storage Service (S3) and compatible Storage Services. See the [driver's reference documentation](../storage-drivers/s3.md).                                                                              |
 
 For testing only, you can use the [`inmemory` storage
-driver](/storage-drivers/inmemory).
+driver](../storage-drivers/inmemory.md).
 If you would like to run a registry from volatile memory, use the
-[`filesystem` driver](/storage-drivers/filesystem)
+[`filesystem` driver](../storage-drivers/filesystem.md)
 on a ramdisk.
 
 If you are deploying a registry on Windows, a Windows volume mounted from the
@@ -593,7 +593,7 @@ security.
 
 
 For more information about Token based authentication configuration, see the
-[specification](/spec/auth/token).
+[specification](../spec/auth/token.md).
 
 ### `htpasswd`
 
@@ -1100,7 +1100,7 @@ proxy:
 
 The `proxy` structure allows a registry to be configured as a pull-through cache
 to Docker Hub. See
-[mirror](/recipes/mirror)
+[mirror](../recipes/mirror.md)
 for more information. Pushing to a registry configured as a pull-through cache
 is unsupported.
 

docs/content/about/deploying.md

@@ -9,7 +9,7 @@ A registry is an instance of the `registry` image, and runs within Docker.
 
 This topic provides basic information about deploying and configuring a
 registry. For an exhaustive list of configuration options, see the
-[configuration reference](../configuration).
+[configuration reference](configuration.md).
 
 If you have an air-gapped datacenter, see
 [Considerations for air-gapped registries](#considerations-for-air-gapped-registries).
@@ -27,7 +27,7 @@ The registry is now ready to use.
 > **Warning**: These first few examples show registry configurations that are
 > only appropriate for testing. A production-ready registry must be protected by
 > TLS and should ideally use an access-control mechanism. Keep reading and then
-> continue to the [configuration guide](../configuration) to deploy a
+> continue to the [configuration guide](configuration.md) to deploy a
 > production-ready registry.
 
 ## Copy an image from Docker Hub to your registry
@@ -94,7 +94,7 @@ To configure the container, you can pass additional or modified options to the
 `docker run` command.
 
 The following sections provide basic guidelines for configuring your registry.
-For more details, see the [registry configuration reference](../configuration).
+For more details, see the [registry configuration reference](configuration.md).
 
 ### Start the registry automatically
 
@@ -166,8 +166,8 @@ $ docker run -d \
 By default, the registry stores its data on the local filesystem, whether you
 use a bind mount or a volume. You can store the registry data in an Amazon S3
 bucket, Google Cloud Platform, or on another storage back-end by using
-[storage drivers](/storage-drivers). For more information, see
-[storage configuration options](../configuration#storage).
+[storage drivers](../storage-drivers/_index.md). For more information, see
+[storage configuration options](configuration.md#storage).
 
 ## Run an externally-accessible registry
 
@@ -252,13 +252,13 @@ The registry supports using Let's Encrypt to automatically obtain a
 browser-trusted certificate. For more information on Let's Encrypt, see
 [https://letsencrypt.org/how-it-works/](https://letsencrypt.org/how-it-works/)
 and the relevant section of the
-[registry configuration](../configuration#letsencrypt).
+[registry configuration](configuration.md#letsencrypt).
 
 ### Use an insecure registry (testing only)
 
 It is possible to use a self-signed certificate, or to use our registry
 insecurely. Unless you have set up verification for your self-signed
-certificate, this is for testing only. See [run an insecure registry](../insecure).
+certificate, this is for testing only. See [run an insecure registry](insecure.md).
 
 ## Run the registry as a service
 
@@ -462,20 +462,20 @@ using htpasswd, all authentication attempts will fail.
 {{< hint type=note title="X509 errors" >}}
 X509 errors usually indicate that you are attempting to use
 a self-signed certificate without configuring the Docker daemon correctly.
-See [run an insecure registry](../insecure).
+See [run an insecure registry](insecure.md).
 {{< /hint >}}
 
 ### More advanced authentication
 
 You may want to leverage more advanced basic auth implementations by using a
-proxy in front of the registry. See the [recipes list](/recipes/).
+proxy in front of the registry. See the [recipes list](../recipes/_index.md).
 
 The registry also supports delegated authentication which redirects users to a
 specific trusted token server. This approach is more complicated to set up, and
 only makes sense if you need to fully configure ACLs and need more control over
 the registry's integration into your global authorization and authentication
-systems. Refer to the following [background information](/spec/auth/token) and
-[configuration information here](../configuration#auth).
+systems. Refer to the following [background information](../spec/auth/token.md) and
+[configuration information here](configuration.md#auth).
 
 This approach requires you to implement your own authentication system or
 leverage a third-party implementation.
@@ -572,9 +572,9 @@ artifacts.
 
 More specific and advanced information is available in the following sections:
 
-- [Configuration reference](../configuration)
-- [Working with notifications](../notifications)
-- [Advanced "recipes"](/recipes)
-- [Registry API](/spec/api)
-- [Storage driver model](/storage-drivers)
-- [Token authentication](/spec/auth/token)
+- [Configuration reference](configuration.md)
+- [Working with notifications](notifications.md)
+- [Advanced "recipes"](../recipes/_index.md)
+- [Registry API](../spec/api.md)
+- [Storage driver model](../storage-drivers/_index.md)
+- [Token authentication](../spec/auth/token.md)

docs/content/about/garbage-collection.md

@@ -21,15 +21,15 @@ that certain layers no longer exist on the filesystem.
 
 Filesystem layers are stored by their content address in the Registry. This
 has many advantages, one of which is that data is stored once and referred to by manifests.
-See [here](../compatibility#content-addressable-storage-cas) for more details.
+See [here](compatibility.md#content-addressable-storage-cas) for more details.
 
 Layers are therefore shared amongst manifests; each manifest maintains a reference
 to the layer. As long as a layer is referenced by one manifest, it cannot be garbage
 collected.
 
 Manifests and layers can be `deleted` with the registry API (refer to the API
-documentation [here](/spec/api#deleting-a-layer) and
-[here](/spec/api#deleting-an-image) for details). This API removes references
+documentation [here](../spec/api.md#deleting-a-layer) and
+[here](../spec/api.md#deleting-an-image) for details). This API removes references
 to the target and makes them eligible for garbage collection. It also makes them
 unable to be read via the API.
 

docs/content/about/insecure.md

@@ -72,7 +72,7 @@ This is more secure than the insecure registry solution.
 
    Be sure to use the name `myregistry.domain.com` as a CN.
 
-2. Use the result to [start your registry with TLS enabled](../deploying#get-a-certificate).
+2. Use the result to [start your registry with TLS enabled](deploying.md#get-a-certificate).
 
 3. Instruct every Docker daemon to trust that certificate. The way to do this
    depends on your OS.

docs/content/about/notifications.md

@@ -10,7 +10,7 @@ pushes and pulls and layer pushes and pulls. These actions are serialized into
 events. The events are queued into a registry-internal broadcast system which
 queues and dispatches events to [_Endpoints_](#endpoints).
 
-![Workflow of registry notifications](../../images/notifications.png)
+![Workflow of registry notifications](/distribution/images/notifications.png)
 
 ## Endpoints
 
@@ -45,7 +45,7 @@ The above would configure the registry with an endpoint to send events to
 5 failures happen consecutively, the registry backs off for 1 second before
 trying again.
 
-For details on the fields, see the [configuration documentation](../configuration/#notifications).
+For details on the fields, see the [configuration documentation](configuration.md#notifications).
 
 A properly configured endpoint should lead to a log message from the registry
 upon startup:

docs/content/recipes/apache.md

@@ -12,7 +12,7 @@ Usually, that includes enterprise setups using LDAP/AD on the backend and a SSO
 
 ### Alternatives
 
-If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](/about/deploying#native-basic-auth).
+If you just want authentication for your registry, and are happy maintaining users access separately, you should really consider sticking with the native [basic auth registry feature](../about/deploying.md#native-basic-auth).
 
 ### Solution
 

docs/content/recipes/mirror.md

@@ -107,7 +107,7 @@ proxy:
 
 > **Warning**: For the scheduler to clean up old entries, `delete` must
 > be enabled in the registry configuration. See
-> [Registry Configuration](/about/configuration) for more details.
+> [Registry Configuration](../about/configuration.md) for more details.
 
 ### Configure the Docker daemon
 

docs/content/recipes/nginx.md

@@ -17,7 +17,7 @@ mechanism fronting their internal http portal.
 
 If you just want authentication for your registry, and are happy maintaining
 users access separately, you should really consider sticking with the native
-[basic auth registry feature](/about/deploying#native-basic-auth).
+[basic auth registry feature](../about/deploying.md#native-basic-auth).
 
 ### Solution
 

docs/content/spec/_index.md

@@ -6,7 +6,7 @@ keywords: registry, service, images, repository,  json
 
 # Docker Registry Reference
 
-* [HTTP API V2](api)
-* [Storage Driver](/storage-drivers/)
-* [Token Authentication Specification](auth/token)
-* [Token Authentication Implementation](auth/jwt)
+* [HTTP API V2](api.md)
+* [Storage Driver](../storage-drivers/_index.md)
+* [Token Authentication Specification](auth/token.md)
+* [Token Authentication Implementation](auth/jwt.md)

docs/content/spec/api.md

@@ -416,7 +416,7 @@ reference may include a tag or digest.
 
 The client should include an Accept header indicating which manifest content
 types it supports. For more details on the manifest format and content types,
-see [Image Manifest Version 2, Schema 2](../manifest-v2-2).
+see [Image Manifest Version 2, Schema 2](manifest-v2-2.md).
 In a successful response, the Content-Type header will indicate which manifest type is being returned.
 
 A `404 Not Found` response will be returned if the image is unknown to the
@@ -840,7 +840,7 @@ Content-Type: <manifest media type>
 The `name` and `reference` fields of the response body must match those
 specified in the URL. The `reference` field may be a "tag" or a "digest". The
 content type should match the type of the manifest being uploaded, as specified
-in [Image Manifest Version 2, Schema 2](../manifest-v2-2).
+in [Image Manifest Version 2, Schema 2](manifest-v2-2.md).
 
 If there is a problem with pushing the manifest, a relevant 4xx response will
 be returned with a JSON error message. Please see the
@@ -1088,7 +1088,7 @@ response will be issued instead.
 
     Accept: application/vnd.docker.distribution.manifest.v2+json
 
-> for more details, see: [compatibility](/about/compatibility#content-addressable-storage-cas)
+> for more details, see: [compatibility](../about/compatibility.md#content-addressable-storage-cas)
 
 ## Detail
 

docs/content/spec/auth/oauth.md

@@ -12,7 +12,7 @@ reference for the protocol and HTTP endpoints described here.
 
 **Note**: Not all token servers implement oauth2. If the request to the endpoint
 returns `404` using the HTTP `POST` method, refer to
-[Token Documentation](../token) for using the HTTP `GET` method supported by all
+[Token Documentation](token.md) for using the HTTP `GET` method supported by all
 token servers.
 
 ## Refresh token format

docs/content/spec/auth/scope.md

@@ -144,7 +144,7 @@ Each JWT access token may only have a single subject and audience but multiple
 resource scopes. The subject and audience are put into standard JWT fields
 `sub` and `aud`. The resource scope is put into the `access` field. The
 structure of the access field can be seen in the
-[jwt documentation](../jwt).
+[jwt documentation](jwt.md).
 
 ## Refresh Tokens
 

docs/content/spec/auth/token.md

@@ -8,7 +8,7 @@ keywords: registry, on-prem, images, tags, repository, distribution, Bearer auth
 
 This document outlines the v2 Distribution registry authentication scheme:
 
-![v2 registry auth](../../../images/v2-registry-auth.png)
+![v2 registry auth](/distribution/images/v2-registry-auth.png)
 
 1. Attempt to begin a push/pull operation with the registry.
 2. If the registry requires authorization it will return a `401 Unauthorized`
@@ -188,7 +188,7 @@ https://auth.docker.io/token?service=registry.docker.io&scope=repository:samalba
 
 The token server should first attempt to authenticate the client using any
 authentication credentials provided with the request. From Docker 1.11 the
-Docker engine supports both Basic Authentication and [OAuth2](../oauth) for
+Docker engine supports both Basic Authentication and [OAuth2](oauth.md) for
 getting tokens. Docker 1.10 and before, the registry client in the Docker Engine
 only supports Basic Authentication. If an attempt to authenticate to the token
 server fails, the token server should return a `401 Unauthorized` response

docs/content/spec/manifest-v2-2.md

@@ -71,7 +71,7 @@ image manifest based on the Content-Type returned in the HTTP response.
     - **`digest`** *string*
 
         The digest of the content, as defined by the
-        [Registry V2 HTTP API Specificiation](../api#digest-parameter).
+        [Registry V2 HTTP API Specification](api.md#digest-parameter).
 
     - **`platform`** *object*
 
@@ -187,7 +187,7 @@ image. It's the direct replacement for the schema-1 manifest.
     - **`digest`** *string*
 
         The digest of the content, as defined by the
-        [Registry V2 HTTP API Specificiation](../api#digest-parameter).
+        [Registry V2 HTTP API Specification](api.md#digest-parameter).
 
 - **`layers`** *array*
 
@@ -213,7 +213,7 @@ image. It's the direct replacement for the schema-1 manifest.
     - **`digest`** *string*
 
         The digest of the content, as defined by the
-        [Registry V2 HTTP API Specificiation](../api#digest-parameter).
+        [Registry V2 HTTP API Specification](api.md#digest-parameter).
 
     - **`urls`** *array*
 

docs/content/storage-drivers/inmemory.md

@@ -7,7 +7,7 @@ title: In-memory storage driver (testing only)
 For purely tests purposes, you can use the `inmemory` storage driver. This
 driver is an implementation of the `storagedriver.StorageDriver` interface which
 uses local memory for object storage. If you would like to run a registry from
-volatile memory, use the [`filesystem` driver](../filesystem) on a ramdisk.
+volatile memory, use the [`filesystem` driver](filesystem.md) on a ramdisk.
 
 {{< hint type=important >}}
 This storage driver *does not* persist data across runs. This is why it is only suitable for testing. *Never* use this driver in production.

docs/hugo.yaml

@@ -1,4 +1,4 @@
-baseURL: /
+baseURL: https://distribution.github.io/distribution
 languageCode: en-us
 title: CNCF Distribution
 theme: hugo-geekdoc
@@ -22,3 +22,4 @@ disablePathToLower: true
 params:
   geekdocRepo: "https://github.com/distribution/distribution"
   geekdocEditPath: edit/main/docs
+  geekdocOverwriteHTMLBase: true

docs/layouts/_default/_markup/render-link.html

@@ -0,0 +1,5 @@
+{{- if (strings.HasPrefix .Destination "http") -}}
+  <a href="{{ safe.URL .Destination }}" target="_blank">{{ safe.HTML .Text }}</a>
+{{- else -}}
+  <a href="{{ ref .Page .Destination | safe.URL }}">{{ safe.HTML .Text }}</a>
+{{- end -}}