docs: prepare pages for the docs.docker.com module mount#3414
Merged
Conversation
Companion change for the Hugo module mount in docker/docs (#3371, phase 2.1). Mounted pages must match docs.docker.com conventions: - drop the body H1: both layouts now render the front matter title (the Jekyll layout prints it like docs.docker.com does; the homepage keeps its hero) - add weight front matter derived from the _data/nav.yml order so the docs.docker.com sidebar matches the github.io navigation - add linkTitle where the nav label differs from the page title - add section _index.md files with title, description, and weight; Jekyll ignores underscore-prefixed files so github.io is unaffected - add aliases mapping the docs.docker.com URLs of the hand-authored pages being replaced (tutorial, best-practices, evals, local-models, model-providers, rag, sharing-agents, integrations/*, reference/*) onto their mounted equivalents so no URL breaks
The nav.yml title was already quoted, producing invalid front matter that fails the Hugo build on docs.docker.com.
The directory-style relative link resolves on Jekyll but fails the docs.docker.com Hugo ref lookup; the .md form works on both.
aheritier
added
area/docs
dgageot
approved these changes
Jul 2, 2026
dvdksn
pushed a commit
to docker/docs
that referenced
this pull request
Jul 3, 2026
Single-sources the Docker Agent documentation from the product repo via a Hugo module mount, joining the pattern used by CLI, Buildx, Compose, BuildKit, Model Runner, and the Moby API. Closes the docs.docker.com side of docker/docker-agent#3371. ## Context The pages under `content/manuals/ai/docker-agent/` were hand-authored duplicates of the product repo docs and drifted on every upstream change. The source docs were converted to portable Hugo-clean Markdown and prepared for mounting in docker/docker-agent#3413 and docker/docker-agent#3414, released in docker-agent v1.96.0. ## What changed | Change | Detail | |---|---| | `go.mod` | `github.com/docker/docker-agent v1.96.0` added to `require` and `tool` | | `hugo.yaml` | `module.imports` mounts the eight docs sections and `demo.gif` onto `content/manuals/ai/docker-agent/` | | Content | The 16 hand-authored pages are removed; `_index.md` stays hand-authored (landing page), with links rewritten to the mounted pages | | `_vendor/` | 99 vendored files from the module | | `.github/workflows/sync-docker-agent-docs.yml` | Daily poll that vendors the latest docker-agent release and opens a bot PR, modeled on `sync-cli-docs.yml` | ## URL preservation Every removed page keeps its URL: the mounted pages carry `aliases` front matter (added upstream in docker/docker-agent#3414), and `_index.md` keeps aliases for the removed section indexes (`integrations/`, `reference/`, `reference/examples/`). | Old URL | Redirects to | |---|---| | `/ai/docker-agent/tutorial/` | `.../getting-started/quickstart/` | | `/ai/docker-agent/best-practices/` | `.../guides/tips/` | | `/ai/docker-agent/evals/` | `.../features/evaluation/` | | `/ai/docker-agent/local-models/` | `.../providers/local/` | | `/ai/docker-agent/model-providers/` | `.../providers/overview/` | | `/ai/docker-agent/rag/` | `.../tools/rag/` | | `/ai/docker-agent/sharing-agents/` | `.../concepts/distribution/` | | `/ai/docker-agent/integrations/{a2a,acp,mcp}/` | `.../features/a2a/`, `.../features/acp/`, `.../tools/mcp/` | | `/ai/docker-agent/reference/{cli,config,toolsets}/` | `.../features/cli/`, `.../configuration/overview/`, `.../configuration/tools/` | | `/ai/docker-agent/integrations/`, `/ai/docker-agent/reference/`, `/ai/docker-agent/reference/examples/` | `/ai/docker-agent/` | ## Mount scope All eight sections are mounted rather than a core subset: `refLinksErrorLevel: ERROR` makes partial mounts fail the build for any relative link into an unmounted page, and the link closure from the core sections already pulls in 68 of the 90 pages. Mounting everything keeps the build link-safe and removes all drift. ## Keeping the pin fresh On each docker-agent release, `sync-docker-agent-docs.yml` (daily poll, mirrors `sync-cli-docs.yml`) compares the latest release tag against the pinned version and opens a bot PR with the re-vendored module. docker/docker-agent also runs `validate-upstream.yml` on every docs PR, so upstream changes that would break this site fail CI before they merge (two source-side issues were caught exactly this way while preparing this change). ## Validation `docker buildx bake validate` passes on this branch: | Target | Result | |---|---| | test (Hugo build + htmltest) | pass (3196 pages, 1515 aliases, 3110 documents tested) | | lint | pass | | unused-media | pass | | test-go-redirects | pass | | validate-vendor | pass | | dockerfile-lint | pass | `actionlint` passes on the new workflow.
16 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion change for the docs.docker.com Hugo module mount (#3371, phase 2.1). Follows up on #3413 (merged).
Why
Pages mounted on docs.docker.com must match its conventions: the layout renders the front matter
titleas the page H1, sidebar order comes fromweight, and the replaced hand-authored URLs needaliases. Verified against the pages already mounted from docker/cli and moby/buildkit (none carry a body H1).What changed
<h1>{{ page.title }}</h1>like docs.docker.com does; the homepage keeps its heroweight:front matter_data/nav.ymlorder so the docs.docker.com sidebar matches github.io navigationlinkTitle:front matter_index.mdfiles (8)aliases:front matterAlias mapping (old docs.docker.com URL -> mounted page)
/ai/docker-agent/tutorial/getting-started/quickstart/ai/docker-agent/best-practices/guides/tips/ai/docker-agent/evals/features/evaluation/ai/docker-agent/local-models/providers/local/ai/docker-agent/model-providers/providers/overview/ai/docker-agent/rag/tools/rag/ai/docker-agent/sharing-agents/concepts/distribution/ai/docker-agent/integrations/a2a/features/a2a/ai/docker-agent/integrations/acp/features/acp/ai/docker-agent/integrations/mcp/tools/mcp/ai/docker-agent/reference/cli/features/cli/ai/docker-agent/reference/config/configuration/overview/ai/docker-agent/reference/toolsets/configuration/toolsSection indexes (
integrations/,reference/) andreference/examples/get aliases on the hand-authored_index.mdkept in docker/docs (part of the docker/docs PR).Validation
_index.mdfiles produce no outputPart of #3371; the docker/docs PR (go.mod pin + hugo.yaml mounts) follows.