Data-Driven Documentation
Relevant source files
The following files were used as context for generating this wiki page:The Docker documentation project employs a data-driven approach for generating certain sections of the website, particularly for Command Line Interface (CLI) references. Instead of maintaining these pages as static Markdown files, the system uses structured YAML data files as the single source of truth. These data files are processed by the Hugo static site generator during the build process to render consistent and accurate documentation pages.
This methodology ensures that the CLI documentation stays in sync with the source code from which it's derived. The data files themselves are generated from upstream repositories (e.g., docker/cli, docker/compose), making the documentation a direct reflection of the tool's capabilities. This approach separates content from presentation, allowing for flexible rendering and automated updates.
Sources: content/reference/cli/docker/README.md, CONTRIBUTING.md:49-55
Architecture and Flow
The generation of data-driven documentation follows a clear path from upstream code repositories to the final published HTML on docs.docker.com. The process involves vendoring content and data via Hugo Modules, which are then used by custom Hugo layouts to build the pages.
This diagram illustrates the end-to-end workflow for generating CLI reference documentation.
Components
The system is composed of three main parts: the upstream data sources, the Hugo build configuration that imports them, and the templates that render the final HTML.
Data Sources: YAML Files
The core of this system is the set of YAML files located in the data/ directory. These files contain structured information about CLI commands, including their descriptions, usage, flags, and examples. These files are not manually created but are generated from the source code of the respective upstream repositories.
For example, data/engine-cli/docker_build.yaml defines the structure for the docker build command.
name: docker build
description: Build an image from a Dockerfile
usage: docker build [OPTIONS] PATH | URL | -
extended_description: |-
The `docker build` command builds Docker images from a Dockerfile and a "context".
A build's context is the set of files located in the specified `PATH` or `URL`.
The build process can refer to any of the files in the context. For example,
your build can use a `COPY` instruction to reference a file in the context.
...
options:
- name: add-host
description: Add a custom host-to-IP mapping (host:ip)
shorthand: ""
value_type: list
...
Source: data/engine-cli/docker_build.yaml:1-14
The content for the extended_description and examples sections is pulled from Markdown files within the upstream repositories, such as those in docker/cli/docs/reference/commandline.
Source: content/reference/cli/docker/README.md:14-19
Upstream Content Management
The documentation repository uses Hugo Modules to vendor content and data from various upstream Docker projects. This is configured in the hugo.yaml file. This mechanism ensures that the documentation is built against specific, versioned sources of truth.
The following table maps documentation sections to their upstream source repositories, as defined in the configuration.
| Documentation Section | Upstream Repository | Configuration Location |
|---|---|---|
| Docker Engine API | github.com/moby/moby/api | hugo.yaml:205-211 |
| Dockerfile Reference | github.com/moby/buildkit | hugo.yaml:213-225 |
| Buildx CLI Plugin | github.com/docker/buildx | hugo.yaml:227-232 |
| Docker CLI | github.com/docker/cli | hugo.yaml:234-246 |
| Docker Compose CLI | github.com/docker/compose/v5 | hugo.yaml:248-252 |
| Model Runner CLI | github.com/docker/model-runner/cmd/cli | hugo.yaml:254-258 |
| MCP Gateway CLI | github.com/docker/mcp-gateway | hugo.yaml:260-264 |
This configuration means that content in these sections is read-only within the docker/docs repository. Any changes must be made in the corresponding upstream project.
Sources: hugo.yaml:202-264, CONTRIBUTING.md:49-55, agent.yml:34-40
Rendering Logic: Hugo Templates
The Hugo static site generator uses templates to transform the YAML data into HTML pages. The primary template for rendering CLI commands is layouts/_default/cli.html. This template is a stub that includes a partial, _includes/cli.md, which contains the core rendering logic.
While the exact content of _includes/cli.md is not provided, the content/reference/cli/docker/README.md file explains that it is responsible for parsing the YAML files. The layouts/_default/cli.html file itself is very simple, indicating a modular design where the main logic is abstracted away into includes or partials.
The process can be visualized as a sequence:
This diagram shows how the Hugo build process uses the cli.html template to read from YAML data files and generate the final HTML output.
Sources: layouts/_default/cli.html, content/reference/cli/docker/README.md:4-7
Conclusion
The data-driven documentation system is a robust solution for maintaining accurate and up-to-date CLI references. By sourcing content directly from upstream repositories and using a structured data format (YAML), the project minimizes manual effort and reduces the risk of documentation drift. The use of Hugo Modules and templating provides a clear separation of concerns, making the system both scalable and maintainable. Developers wishing to correct or update CLI documentation must do so in the respective upstream projects, ensuring changes are made at the true source.
Sources: CONTRIBUTING.md:49-65, agent.yml:34-51