From 5e75227fb213162564bab74b146300ffed9f0bbd Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 9 Jan 2024 20:10:18 +0100 Subject: [PATCH] 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 | 2 -- docker-bake.hcl | 7 ---- dockerfiles/docs.Dockerfile | 9 +++-- docs/content/about/configuration.md | 20 +++++------ docs/content/about/deploying.md | 34 +++++++++---------- docs/content/about/garbage-collection.md | 6 ++-- docs/content/about/insecure.md | 2 +- docs/content/about/notifications.md | 4 +-- docs/content/recipes/apache.md | 2 +- docs/content/recipes/mirror.md | 2 +- docs/content/recipes/nginx.md | 2 +- docs/content/spec/_index.md | 8 ++--- docs/content/spec/api.md | 6 ++-- docs/content/spec/auth/oauth.md | 2 +- docs/content/spec/auth/scope.md | 2 +- docs/content/spec/auth/token.md | 4 +-- docs/content/spec/manifest-v2-2.md | 6 ++-- docs/content/storage-drivers/inmemory.md | 2 +- docs/hugo.yaml | 3 +- .../layouts/_default/_markup/render-link.html | 5 +++ 20 files changed, 64 insertions(+), 64 deletions(-) create mode 100644 docs/layouts/_default/_markup/render-link.html diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 4bac52ced..1be0a888a 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/docker-bake.hcl b/docker-bake.hcl index 540e4be41..9512b17f7 100644 --- a/docker-bake.hcl +++ b/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" { diff --git a/dockerfiles/docs.Dockerfile b/dockerfiles/docs.Dockerfile index f54afdc7f..f29122e11 100644 --- a/dockerfiles/docs.Dockerfile +++ b/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 diff --git a/docs/content/about/configuration.md b/docs/content/about/configuration.md index 4107c0b3a..41519e05e 100644 --- a/docs/content/about/configuration.md +++ b/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. diff --git a/docs/content/about/deploying.md b/docs/content/about/deploying.md index 1c022bc2e..bfa35955c 100644 --- a/docs/content/about/deploying.md +++ b/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) diff --git a/docs/content/about/garbage-collection.md b/docs/content/about/garbage-collection.md index dd1768d60..ee2d2fb2e 100644 --- a/docs/content/about/garbage-collection.md +++ b/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. diff --git a/docs/content/about/insecure.md b/docs/content/about/insecure.md index e9f55f15d..c848f869f 100644 --- a/docs/content/about/insecure.md +++ b/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. diff --git a/docs/content/about/notifications.md b/docs/content/about/notifications.md index d5b11d5d4..8e2b642e6 100644 --- a/docs/content/about/notifications.md +++ b/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: diff --git a/docs/content/recipes/apache.md b/docs/content/recipes/apache.md index 846392753..d118c5fe4 100644 --- a/docs/content/recipes/apache.md +++ b/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 diff --git a/docs/content/recipes/mirror.md b/docs/content/recipes/mirror.md index f11f9cba7..d5ec06a54 100644 --- a/docs/content/recipes/mirror.md +++ b/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 diff --git a/docs/content/recipes/nginx.md b/docs/content/recipes/nginx.md index d2c4ff35d..8db6e4f1f 100644 --- a/docs/content/recipes/nginx.md +++ b/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 diff --git a/docs/content/spec/_index.md b/docs/content/spec/_index.md index 5e9729b8d..4f2d0e93f 100644 --- a/docs/content/spec/_index.md +++ b/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) diff --git a/docs/content/spec/api.md b/docs/content/spec/api.md index 45d6c0d06..2bab67d36 100644 --- a/docs/content/spec/api.md +++ b/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: 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 diff --git a/docs/content/spec/auth/oauth.md b/docs/content/spec/auth/oauth.md index ca61d2edd..8e5f759d8 100644 --- a/docs/content/spec/auth/oauth.md +++ b/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 diff --git a/docs/content/spec/auth/scope.md b/docs/content/spec/auth/scope.md index a2236bb75..1f2059add 100644 --- a/docs/content/spec/auth/scope.md +++ b/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 diff --git a/docs/content/spec/auth/token.md b/docs/content/spec/auth/token.md index cc9d940e8..a878b3281 100644 --- a/docs/content/spec/auth/token.md +++ b/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 diff --git a/docs/content/spec/manifest-v2-2.md b/docs/content/spec/manifest-v2-2.md index 1e85fad73..a4c7e9298 100644 --- a/docs/content/spec/manifest-v2-2.md +++ b/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* diff --git a/docs/content/storage-drivers/inmemory.md b/docs/content/storage-drivers/inmemory.md index ba9cd93e9..81c49dfcc 100644 --- a/docs/content/storage-drivers/inmemory.md +++ b/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. diff --git a/docs/hugo.yaml b/docs/hugo.yaml index 4d5c75c97..b98cdd153 100644 --- a/docs/hugo.yaml +++ b/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 diff --git a/docs/layouts/_default/_markup/render-link.html b/docs/layouts/_default/_markup/render-link.html new file mode 100644 index 000000000..01ef350c8 --- /dev/null +++ b/docs/layouts/_default/_markup/render-link.html @@ -0,0 +1,5 @@ +{{- if (strings.HasPrefix .Destination "http") -}} + {{ safe.HTML .Text }} +{{- else -}} + {{ safe.HTML .Text }} +{{- end -}}