The include shortcode previously called readFile directly, which renders
nothing when the target is missing instead of failing. That let renamed
or deleted snippets linger as silent no-ops (for example the stale
scout-early-access.md and compose/develop.md references).
Check fileExists first and errorf with the shortcode position when the
target is missing, mirroring the file/files shortcodes. Verified against
Hugo 0.163.0: valid includes still render; a missing target now fails the
build with the offending file and line.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Align the experimental flag badges in the Docker CLI layout with the
violet color used by the sbx-cli layout, so experimental indicators are
consistent across both reference templates.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The sbx-cli layout had no handling for the experimental: true field
present in many data/sbx_cli/*.yaml files. Add visual indicators
matching the Docker CLI layout:
- Command-level (experimental: true at YAML root): magenta callout
block below the summary table
- Flag-level (experimental: true on an option): violet badge before
the flag description in Options and Global options tables
- Subcommands table: violet badge alongside the synopsis for
experimental child commands
The title heading stays plain, consistent with cli.html, which signals
experimental status only through the command-level callout.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
<!--Delete sections as needed -->
## Description
Updated Python guide
- Removed DOI in favor of DHI only. DHI Community is now free, so
there's no reason to keep the DOI fallback path.
- Removed the git clone sample-app pattern. Maintaining external sample
repos is a burden, and split source of truth between the docs and the
sample.
- New file browser / scaffolding component. Lets users copy individual
files or scaffold the whole project with one command. Replaces the role
the cloned sample repo used to play.
- New "Secure your supply chain" topic highlighting what DHI gives you
and how to attach matching attestations to your own image in CI.
- A bunch of smaller improvements: clearer intros for each topic,
progressively updating the same app in all topics, ran and fixed issues,
etc.
https://deploy-preview-25206--docsdocker.netlify.app/guides/python/
## Related issues or tickets
ENGDOCS-3308
## Reviews
<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->
- [ ] Technical review
- [ ] Editorial review
---------
Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
## Summary
The site fails to build on Hugo 0.162, which no longer allows
`templates.Defer` inside a `partialCached` partial. `head.html` called
`utils/css.html` (which defers with a global key) via `partialCached`.
This switches that call to `partial` — the global Defer key already
dedupes the work, so caching was redundant — and bumps the pinned Hugo
version in the `Dockerfile` and `netlify.toml` to 0.162.1.
Verified with a full local build on Hugo 0.162.1 extended (Node 24):
clean build, 3332 pages, no template errors.
## Learnings
- Hugo 0.162 enforces that `templates.Defer` cannot live inside a
`partialCached` partial; the build error points at the deferred
template, not the `partialCached` caller, so trace upward to the caching
call site.
Generated by Claude Code
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Hugo 0.162 disallows templates.Defer inside a partialCached partial.
The CSS partial uses templates.Defer with a global key, so switch its
caller in head.html from partialCached to partial (the global Defer key
already dedupes the work). Bump the pinned Hugo version in the Dockerfile
and netlify.toml.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## Summary
Restructures the Docker AI Governance documentation under
\`/ai/sandboxes/governance/\` and adds the supporting API reference.
Preview links:
-
https://deploy-preview-25162--docsdocker.netlify.app/ai/sandboxes/governance/
-
https://deploy-preview-25162--docsdocker.netlify.app/reference/api/ai-governance/
### Information architecture
The existing \`security/governance\` and \`security/policy\` pages are
merged into a new top-level \`governance\` section so local-policy and
org-policy sit side by side instead of being split across unrelated
parents:
- \`/ai/sandboxes/governance/\` — section landing; explains local + org
as layered enforcement
- \`/ai/sandboxes/governance/concepts/\` — resource model, rule syntax,
evaluation, precedence
- \`/ai/sandboxes/governance/local/\` — \`sbx policy\` CLI for
individual machines
- \`/ai/sandboxes/governance/org/\` — Admin Console flow (was
\`security/governance.md\`)
- \`/ai/sandboxes/governance/monitoring/\` — \`sbx policy ls\` / \`sbx
policy log\`
### API reference
\`/reference/api/ai-governance/\` renders the Governance OpenAPI spec
vendored at \`content/reference/api/ai-governance/api.yaml\` from
\`docker/governor-services\`. Operations, schemas, examples, and status
codes are fully driven by the spec — future updates land via re-vendor,
not in-repo edits. Anything wrong in the rendered reference should be
fixed upstream and re-vendored here.
The spec has been re-vendored to the latest upstream version, which
updated the server URL to \`hub.docker.com/v2\` and added the
\`/governance/\` prefix to all API paths.
### Review focus
1. The \`/ai/sandboxes/governance/\` landing — does the local + org
framing match how the product is positioned?
2. \`/reference/api/ai-governance/\` — does the rendered spec match the
source of truth, and is anything important missing?
Generated by Claude Code
---------
Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
The experimental notice on CLI reference pages was being produced by
running a Hugo shortcode through markdownify. The shortcode template
embeds the icon partial, and the recent migration to multi-line
Heroicons SVGs (commit ee71c80562) pushed the inner SVG path to a
4-space indent inside the expanded HTML. markdownify then re-parsed
that HTML as Markdown and treated the indented lines (the SVG path
plus the trailing </span> and <strong>Experimental</strong>) as a
fenced code block, which is what users see on docs.docker.com.
Replace the markdownify+shortcode round-trip with the rendered HTML
inline, matching the styling of the experimental shortcode but with
no Markdown re-parse.
Fixes#25215
Adds a Hugo codeblock render hook that turns ```mermaid fences into
<pre class="mermaid"> containers, plus a lazily-loaded mermaid bundle
that only ships on pages that actually contain a diagram. Mirrors the
existing YouTube embed pattern (Store flag + conditional script tag in
baseof) so the main scripts.js bundle stays unchanged.
Hugo's html/template JS-escapes string values inside <script> blocks.
Calling jsonify per-field produced quoted strings like "https://..."
which were then re-escaped, embedding literal quote characters in the
endpoint value passed to the SDK.
Fix by jsonifying the whole config dict at once and marking it safeJS
so html/template does not apply a second round of escaping.
Also extract the environment ternary out of the Marlin constructor call
for readability.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Introduces @docker/marlin-sdk-web-public for first-party pageview and
click analytics, bundled into scripts.js via Hugo's existing js.Build
pipeline. Config is emitted to window.__marlinConfig from head.html and
gated to prod/staging only.
Renames data-heap-id attributes on the markdown-dropdown buttons to
marlin-action so they are picked up by the SDK's auto-click tracking.
TODO: replace the REPLACE-ME endpoint placeholders in hugo.yaml with
the canonical Marlin ingestion URLs from the data-platform team.
TODO: heap.track() calls in youtube-script.html are left in place —
the public SDK exposes no equivalent track() method, so video
play/pause events cannot be migrated yet.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Replaces @material-symbols/svg-400 (5.5 MB) with heroicons (488 KB) — an
11x reduction in icon asset size. Heroicons uses a single consistent
distribution format (24px solid SVGs, fill="currentColor") eliminating
the need for the separate utils/svg.html partial, the icon-svg-stroke CSS
utility, and the dual-path resolution logic in icon.html.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Render the page actions (Ask Gordon, Copy Markdown, View Markdown) as
a horizontal row of icon links below the page title, separated from the
body by a divider — emulating the Stripe docs pattern. Drops the bordered
button + dropdown UI from md-dropdown.html and the Open in Claude entry.
Also clean up dead kapa.ai references: the "Ask Gordon" action now talks
to the Alpine gordon store directly instead of clicking the header
button via an open-kapa-widget class hook. The class, the unused
glossary link hook, and the dead params.kapa config block all go away.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Publish an MCP Server Card at /.well-known/mcp/server-card.json
pointing at https://mcp-docs.docker.com/mcp, so agents doing MCP
discovery can find the official Docker docs endpoint. Mirror the
serverInfo and capabilities reported by the server's initialize
response.
Also add a one-line pointer near the top of llms.txt so LLMs fetching
the index learn about the structured-access alternative.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Add Content-Signal directive opting in to AI training, search indexing,
and AI input (RAG/grounding). Docker's official docs benefit from wide
distribution through AI assistants, so permitting training and grounding
is aligned with the site's purpose.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
## Description
Modify the shortcode used to launch labs to add teardown instructions.
In order for the teardown instructions to work reliably (since there's
no guarantee the user will be in the same directory), the startup
command also adds a flag to specify the project name (`-p labspace`).
> 🤖 Generated with [Claude Code](https://claude.com/claude-code)
## Summary
`theme.js` unconditionally wrote the resolved preference to
`localStorage` on every page load, permanently locking in a concrete
`"light"` or `"dark"` value even for first-time visitors — making it
impossible to track OS preference changes after any site visit. Removed
the unconditional `localStorage.setItem` from `theme.js` so the early
script only reads (never writes); the Alpine.js toggle in `header.html`
now cycles through three states (light → dark → auto), with "auto"
removing the `theme-preference` key and resolving from
`prefers-color-scheme` with a live `matchMedia` change listener so the
theme updates immediately when the OS preference changes. A contrast
icon indicates auto mode; all three icon spans are driven by Alpine
`x-show` directives rather than pure CSS dark-mode classes.
**Verified:** logic matches the standard three-state pattern;
`prefers-color-scheme` media query and `matchMedia` change listener are
the canonical browser APIs for system-preference tracking.
**Checked:** no other files reference `theme-preference` or the theme
toggle; no CSS changes required.
Closes#23177
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Description
In order to better attribute upgrade sources, we are adding two params -
`ref` and `refAction` to the existing pricing url.
The `ref` will be "Docs" and the `refAction` will be the particular docs
page from where the pricing url click is originated.
## Related issues or tickets
https://docker.atlassian.net/browse/GRO-282
## Reviews
@akristen You should see the new url params when hovering over or
clicking any of the updated pricing urls
- [ ] Technical review
- [ ] Editorial review
- [ ] Product review
---------
Co-authored-by: Alexa Kristensen <81787716+akristen@users.noreply.github.com>
David Karlsson