$ show docker/docs
docker/docs is the source repository for Docker's official documentation website (docs.docker.com). It is a Hugo static-site project with 2,500+ Markdown pages spanning all Docker products — Engine, Compose, Desktop, Hub, Scout, Hardened Images, AI Sandboxes, Model Runner, Docker Agent, security, subscription/billing, and the Extensions SDK — plus generated CLI and API reference sections. The site ships two renderings from one source: conventional HTML/JS for browsers and a plain-Markdown variant (via llms.txt, llms-full.txt, and Accept-header content negotiation) designed for LLMs and AI agents. This dual-output design is the most distinctive architectural feature of the repository. Beneath the content layer sits real engineering. A custom Go module (hack/api-docs) validates multiple OpenAPI 3.2 specifications against a strict JSON Schema dialect, SHA-256-locks upstream spec resources, and emits a single data/api-reference.json model consumed by Hugo. A Hugo content adapter (content/reference/cli/_content.gotmpl) generates ~400 CLI reference pages from structured YAML command trees in data/cli and data/sbx_cli rather than hand-authored Markdown. Upstream project docs (docker/cli, compose, buildx, moby, buildkit, model-runner, docker-agent) are vendored as Go modules with automated sync workflows and PR review guardrails that reject direct edits to generated content. The front end uses Tailwind CSS 4, Alpine.js, Mermaid, Pagefind search, and a self-contained interactive SVG diagram renderer. Build, lint, test, and deploy are fully containerized via docker-bake.hcl, with CI covering link checks, Vale prose linting, rumdl Markdown linting, API-reference regeneration staleness, and Playwright browser checks. The repository is actively maintained: daily and scheduled GitHub Actions keep vendored docs synchronized, a nightly docs scan detects quality issues, Dependabot and stale-issue automation run, and an AI-agent PR review pipeline enforces style and vendoring rules. The main risks are structural rather than stagnation-related: the HTML/Markdown shortcode system must be maintained in two forms (some visual components silently disappear from the Markdown variant), the vendored surface spans six+ upstream repos and depends on disciplined sync, and the rapidly evolving AI product documentation (Sandboxes, Docker Agent, Model Runner, Gordon) creates constant churn. Legacy content such as 2017-era engine release notes and deprecated Compose standalone install pages is retained deliberately as archived history, not as evidence of drift.
The LLM identified 4 files worth highlighting for reuse:
Standalone Go pipeline that ingests OpenAPI 3.2 specs from multiple Docker API products, validates them against a strict JSON Schema dialect, and emits a single data/api-reference.json model consumed by Hugo. Uses SHA-256-locked resource manifests (lock.json) for reproducible builds, strict YAML parsing preserving timestamps, JSON Schema compilation, operation/parameter/variant modeling, and cURL example generation. The module is isolated (spec files in, JSON out) and safely extractable for any team generating API reference pages from OpenAPI specs without hand-maintaining markdown.
A Hugo content adapter that programmatically generates CLI reference pages from structured YAML command trees (data/cli and data/sbx_cli) instead of authoring hundreds of markdown files by hand. It filters hidden/experimental commands, applies aliases, and maps sidebar redirects. Demonstrates a generic and highly reusable pattern: render documentation pages from a machine-readable command schema, keeping docs in sync with the CLI surface without manual page maintenance.
Self-contained JavaScript renderer that turns YAML/JSON diagram definitions (sequence and topology types) into interactive SVG diagrams with animations, tooltips, and accessibility fallbacks. Uses WeakMap caching for sources, MutationObserver-driven theme redraws, and generation counters to prevent stale async renders, with progressive enhancement via an is-enhanced class. Could be lifted into any documentation or data-visualization project needing lightweight interactive diagrams without a heavy diagram-library dependency.
Post-build Node script that rewrites Markdown links and flattens index.md routes across the rendered plain-Markdown variant of the site, producing a clean standalone .md corpus that also powers llms.txt and markdown content negotiation. Demonstrates a reusable pattern for static-site repositories that want to expose LLM- and agent-friendly versions of documentation without maintaining a separate authoring format. It is paired with Node tests (hack/test/flatten-and-resolve.mjs) validating link rewriting and page flattening.