docker-agent: single-source docs via Hugo module mount#25480
Conversation
Mounts the docker/docker-agent docs, converted to portable Markdown and prepared for the mount upstream (docker/docker-agent#3413 and docker/docker-agent#3414, released in v1.96.0), onto content/manuals/ai/docker-agent. This replaces the hand-authored pages that drifted from the product repo (docker/docker-agent#3371). - go.mod: pin github.com/docker/docker-agent v1.96.0 - hugo.yaml: mount the eight docs sections and demo.gif - replace the 16 hand-authored pages; URLs are preserved via aliases carried by the mounted pages, and _index.md keeps aliases for the removed section indexes - sync-docker-agent-docs.yml: daily poll that vendors the latest docker-agent release and opens a bot PR, modeled on sync-cli-docs
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
github-actions
Bot
added
area/release
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟢 APPROVE
This PR correctly single-sources the Docker Agent documentation via Hugo module mount, following the established pattern used by CLI, Buildx, Compose, BuildKit, Model Runner, and the Moby API.
Reviewed:
.github/workflows/sync-docker-agent-docs.yml— daily sync workflow structure looks correct, mirrorssync-cli-docs.ymlpatterngo.mod/hugo.yaml— module mount configuration appears well-formedcontent/manuals/ai/docker-agent/_index.md— retained hand-authored landing page with updated links- Redirect coverage — removed pages carry aliases in the upstream vendored files per the PR description, and
_index.mdretains aliases for removed section indexes - 99 vendored files under
_vendor/— upstream-sourced, not reviewed for style (by design)
No issues found in the hand-authored or infrastructure files introduced by this PR.
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟢 APPROVE
This PR correctly single-sources Docker Agent documentation via a Hugo module mount, following the established pattern used by CLI, Buildx, Compose, BuildKit, Model Runner, and the Moby API.
Redirect coverage: All 16 removed pages have URL aliases properly set — either in the vendored replacement files (e.g., quickstart/index.md → /ai/docker-agent/tutorial/, guides/tips/index.md → /ai/docker-agent/best-practices/, etc.) or in the hand-authored _index.md (section indexes: integrations/, reference/, reference/examples/). No broken redirects found.
Hugo module mounts: All 8 sections plus demo.gif are mounted correctly in hugo.yaml. The mount targets match the expected URL structure.
Sync workflow: .github/workflows/sync-docker-agent-docs.yml is correctly modeled on sync-cli-docs.yml, with daily schedule, version comparison, bake-based vendoring, and idempotent PR creation/update logic.
Front matter: All vendored files carry valid title, description, keywords, linkTitle, and weight fields. No build-breaking front matter issues found.
No issues to report.
aheritier
left a comment
aheritier
left a comment
There was a problem hiding this comment.
it looks good @Sayt-0 with one remark: top level section pages are empty
https://deploy-preview-25480--docsdocker.netlify.app/ai/docker-agent/getting-started/
https://deploy-preview-25480--docsdocker.netlify.app/ai/docker-agent/concepts/
Not sure how we could handle them cc @dvdksn
The mounted section _index.md files are navigation stubs (title, description, weight) and rendered as empty pages. Cascade build.render: never so the sections keep their sidebar children without producing empty pages, matching the pattern used by gordon/concepts and other render:never section indexes.
| require ( | ||
| charm.land/bubbles/v2 v2.1.0 // indirect |
There was a problem hiding this comment.
It should not be necessary to pull in indirects - how did you vendor this?
There was a problem hiding this comment.
Right, I initially vendored with hugo mod get, which records the module's full transitive graph as indirects. Since only the mounted docs are consumed, I fixed it in 2ac618f: I added the pin directly to the require block and ran plain hugo mod vendor. The diff is now +8/-2 with no indirects. The docker/cli v29.6.1 bump remains because docker-agent requires it (MVS). I applied the same fix to the sync workflow (go mod edit -require instead of hugo mod get).
The initial vendoring used hugo mod get, which records the module's full dependency graph as indirect requires in go.mod. Only the mounted docs are consumed, so the pin is now added directly to the require block and hugo mod vendor resolves it on its own, keeping go.mod and go.sum minimal (docker/cli moves to v29.6.1+incompatible via minimal version selection because docker-agent requires it). The sync workflow gets the same treatment: go mod edit -require instead of passing MODULE to hugo mod get during vendoring.
| name: Update pin | ||
| if: steps.get-version.outputs.version != steps.get-version.outputs.current | ||
| run: | | ||
| go mod edit -require "${MODULE_NAME}@${{ steps.get-version.outputs.version }}" |
There was a problem hiding this comment.
We have a makefile target for this;
https://github.com/docker/docs/blob/bf9c27bca2a08e1419200a99ec5546c091505f7f/Makefile
https://github.com/docker/docs/blob/bf9c27bca2a08e1419200a99ec5546c091505f7f/hack/vendor
usage:
VENDOR_MODULE=github.com/docker/xxx@v1.2.3 make vendor
| mounts: | ||
| - source: docs/getting-started | ||
| target: content/manuals/ai/docker-agent/getting-started | ||
| - source: docs/concepts | ||
| target: content/manuals/ai/docker-agent/concepts | ||
| - source: docs/configuration | ||
| target: content/manuals/ai/docker-agent/configuration | ||
| - source: docs/tools | ||
| target: content/manuals/ai/docker-agent/tools | ||
| - source: docs/providers | ||
| target: content/manuals/ai/docker-agent/providers | ||
| - source: docs/features | ||
| target: content/manuals/ai/docker-agent/features | ||
| - source: docs/guides | ||
| target: content/manuals/ai/docker-agent/guides | ||
| - source: docs/community | ||
| target: content/manuals/ai/docker-agent/community | ||
| - source: docs/demo.gif | ||
| target: content/manuals/ai/docker-agent/demo.gif |
There was a problem hiding this comment.
Given that all the seem to be a 1:1 mapping; wondering if it would work to use a single mount (docs/ -> content/manuals/ai/docker-agent/)?
There was a problem hiding this comment.
Updated! A bare single mount pulled in the upstream Jekyll site files (docs/ also hosts the github.io site), so the single mount filters them out with negated files globs
Replaces the direct bake-action call with the repo's canonical make vendor flow. The version is set with go mod edit first instead of passing VENDOR_MODULE, because hugo mod get records docker-agent's full transitive graph as indirect requires in go.mod.
The docs/ tree maps 1:1 onto content/manuals/ai/docker-agent/, so the nine per-section mounts are replaced by a single docs mount. Upstream docs/ also hosts the Jekyll site for github.io, so its infrastructure files are filtered out with negated files globs. New upstream sections now flow in without a hugo.yaml change, which refLinksErrorLevel ERROR would otherwise turn into a broken sync PR. Rendered output is byte-identical to the previous config. Suggested-by: Sebastiaan van Stijn <github@gone.nl>
Resolve conflicts in go.mod and _vendor/modules.txt. Keep docker/cli v29.6.1+incompatible (required transitively by docker-agent v1.96.0 via minimal version selection) and the docker-agent v1.96.0 module from this branch; take docker/compose/v5 v5.3.0 from upstream. Regenerated _vendor, go.mod, and go.sum with make vendor.
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟢 APPROVE
The PR correctly single-sources Docker Agent documentation from the upstream product repo via a Hugo module mount, following the established pattern used by CLI, Buildx, Compose, BuildKit, Model Runner, and the Moby API.
Reviewed areas:
- ✅
go.mod/go.sum— module addition looks correct - ✅
hugo.yaml— mount configuration filters out Jekyll infrastructure files appropriately - ✅
.github/workflows/sync-docker-agent-docs.yml— mirrors thesync-cli-docs.ymlpattern; version comparison,go mod edit+make vendor, PR create/update logic all look sound - ✅
content/manuals/ai/docker-agent/_index.md— hand-authored landing page is clean; no AI-isms, correct front matter, aliases preserved for all removed section indexes - ✅ Redirects — all removed pages have
aliasesfront matter in the mounted upstream pages, and the landing page preserves section-index aliases (integrations/,reference/,reference/examples/) - ✅ Deleted image (
cagent-acp-zed.avif) — confirmed no surviving content references it - ✅
_vendor/— machine-generated content from the module, not manually edited
No actionable issues found in the changed code.
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟢 APPROVE
This PR correctly implements the Hugo module mount pattern, matching how CLI, Buildx, Compose, BuildKit, Model Runner, and Moby API docs are single-sourced. All validation targets pass (test, lint, unused-media, test-go-redirects, validate-vendor, dockerfile-lint).
Reviewed areas:
- Vendored files: All
_vendor/github.com/docker/docker-agent/docs/additions arenew file mode— no pre-existing vendored file is being edited. ✅ - Redirect coverage: The PR description lists every removed URL and its redirect destination. The
_index.mdcarries aliases for the removed section indexes; upstream pages carry aliases for the removed leaf pages (added in docker/docker-agent#3414). ✅ - Hugo mount configuration (
hugo.yaml): Thefiles:exclusion list correctly filters out Jekyll-specific infrastructure (_*,assets/,css/,js/,recordings/,404.md,Dockerfile,Gemfile,STYLE.md,index.md) — keeping only portable Markdown content. Thejs/app.jsJekyll asset is vendored but never served by Hugo (correctly excluded). ✅ - Sync workflow (
.github/workflows/sync-docker-agent-docs.yml): Structure mirrorssync-cli-docs.yml. Usesdocker/setup-buildx-actionbecausemake vendorrunsdocker buildx bake vendor. Skip-if-unchanged logic, force-push on existing branch, and closed-PR deduplication all look correct. ✅ - Hand-authored
_index.md: Front matter is complete (title,description,keywords,aliases). No AI-isms, hedge words, or style violations detected. ✅ go.mod:github.com/docker/docker-agent v1.96.0added correctly underrequireandtool. ✅
No issues found.
dvdksn
left a comment
dvdksn
left a comment
There was a problem hiding this comment.
it looks like the changed mount path in 8574f48 caused a lot of jekyll cruft to be re-vendored here. I'd prefer if we keep that out of the docker/docs repository and only mount the needed content files - either by reverting and making the mount paths explicitly content paths, or by moving the jekyll site scaffolding out of the mounted docs directory upstream
…ount" This reverts commit 8574f48. hugo mod vendor copies the whole mount source directory and ignores the files filters, so the single docs mount vendored the upstream Jekyll site files into _vendor. Mount explicit content paths instead to keep them out of the repository.
|
Reverted to the per-section content mounts, the Jekyll files are gone from |
5 participants
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
go.modgithub.com/docker/docker-agent v1.96.0added torequireandtoolhugo.yamlmodule.importsmounts the eight docs sections anddemo.gifontocontent/manuals/ai/docker-agent/_index.mdstays hand-authored (landing page), with links rewritten to the mounted pages_vendor/.github/workflows/sync-docker-agent-docs.ymlsync-cli-docs.ymlURL preservation
Every removed page keeps its URL: the mounted pages carry
aliasesfront matter (added upstream in docker/docker-agent#3414), and_index.mdkeeps aliases for the removed section indexes (integrations/,reference/,reference/examples/)./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: ERRORmakes 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, mirrorssync-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 runsvalidate-upstream.ymlon 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 validatepasses on this branch:actionlintpasses on the new workflow.