docker-agent: single-source docs via Hugo module mount by Sayt-0 · Pull Request #25480 · docker/docs

Sayt-0 · 2026-07-02T13:18:35Z

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.

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

netlify · 2026-07-02T13:18:42Z

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	`196b7e5`
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/6a469243d175de000868371f
😎 Deploy Preview	https://deploy-preview-25480--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

docker-agent

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, mirrors sync-cli-docs.yml pattern
go.mod / hugo.yaml — module mount configuration appears well-formed
content/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.md retains 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

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

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.

dvdksn · 2026-07-02T13:45:22Z

+require (
+	charm.land/bubbles/v2 v2.1.0 // indirect


It should not be necessary to pull in indirects - how did you vendor this?

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.

dvdksn · 2026-07-02T14:57:06Z

+        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 }}"


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

thaJeztah · 2026-07-02T15:09:41Z

+      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


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/)?

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

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 the sync-cli-docs.yml pattern; 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 aliases front 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

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 are new 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.md carries 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): The files: 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. The js/app.js Jekyll asset is vendored but never served by Hugo (correctly excluded). ✅
Sync workflow (.github/workflows/sync-docker-agent-docs.yml): Structure mirrors sync-cli-docs.yml. Uses docker/setup-buildx-action because make vendor runs docker 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.0 added correctly under require and tool. ✅

No issues found.

Sayt-0 requested a review from dvdksn as a code owner July 2, 2026 13:18

github-actions Bot added area/release Relates to CI or deployment hugo Updates related to hugo dependencies Vendoring, packaging updates area/config area/ai ci ci updates labels Jul 2, 2026

docker-agent reviewed Jul 2, 2026

View reviewed changes

aheritier reviewed Jul 2, 2026

View reviewed changes

dvdksn reviewed Jul 2, 2026

View reviewed changes

thaJeztah reviewed Jul 2, 2026

View reviewed changes

aheritier approved these changes Jul 2, 2026

View reviewed changes

Sayt-0 added 2 commits July 2, 2026 17:47

Sayt-0 requested a review from aheritier July 2, 2026 16:31

docker-agent reviewed Jul 2, 2026

View reviewed changes

Sayt-0 requested a review from dvdksn July 2, 2026 16:40

docker-agent reviewed Jul 2, 2026

View reviewed changes

aheritier approved these changes Jul 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docker-agent: single-source docs via Hugo module mount#25480

docker-agent: single-source docs via Hugo module mount#25480
Sayt-0 wants to merge 6 commits into
docker:mainfrom
Sayt-0:docker-agent-module-mount

Sayt-0 commented Jul 2, 2026

Uh oh!

netlify Bot commented Jul 2, 2026 •

edited

Loading

Uh oh!

docker-agent left a comment

Uh oh!

docker-agent left a comment

Uh oh!

aheritier left a comment

Uh oh!

dvdksn Jul 2, 2026

Uh oh!

Sayt-0 Jul 2, 2026

Uh oh!

dvdksn Jul 2, 2026

Uh oh!

Sayt-0 Jul 2, 2026

Uh oh!

thaJeztah Jul 2, 2026

Uh oh!

Sayt-0 Jul 2, 2026 •

edited

Loading

Uh oh!

docker-agent left a comment

Uh oh!

docker-agent left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

Sayt-0 commented Jul 2, 2026

Context

What changed

URL preservation

Mount scope

Keeping the pin fresh

Validation

Uh oh!

netlify Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docsdocker ready!

Uh oh!

docker-agent left a comment

Choose a reason for hiding this comment

Assessment: 🟢 APPROVE

Uh oh!

docker-agent left a comment

Choose a reason for hiding this comment

Assessment: 🟢 APPROVE

Uh oh!

aheritier left a comment

Choose a reason for hiding this comment

Uh oh!

dvdksn Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

Sayt-0 Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

dvdksn Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

Sayt-0 Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

thaJeztah Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

Sayt-0 Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

docker-agent left a comment

Choose a reason for hiding this comment

Assessment: 🟢 APPROVE

Uh oh!

docker-agent left a comment

Choose a reason for hiding this comment

Assessment: 🟢 APPROVE

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

netlify Bot commented Jul 2, 2026 •

edited

Loading

Sayt-0 Jul 2, 2026 •

edited

Loading