Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page: - [hugo.yaml](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/hugo.yaml) - [CONTRIBUTING.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/CONTRIBUTING.md) - [agent.yml](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/agent.yml) - [content/contribute/file-conventions.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/file-conventions.md) - [layouts/partials/schema.html](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/layouts/partials/schema.html) - [content/reference/cli/docker/README.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/reference/cli/docker/README.md)

The Docker Docs project is a comprehensive documentation website built using the Hugo static site generator. Its architecture is designed to aggregate content from multiple upstream repositories, ensuring that documentation for various Docker tools (like the CLI, Buildx, and Compose) remains consistent with their source code. The system leverages Docker for local development environments and employs a sophisticated, agent-based workflow for automating content creation and maintenance.

This architecture centralizes documentation contribution and publishing while keeping the content itself decentralized and version-controlled within its respective project. Key aspects include a modular content sourcing mechanism via Hugo Modules, a containerized local development and testing setup, and automated checks to maintain quality and style.

Sources: CONTRIBUTING.md:10-12, hugo.yaml:1, 222-225, agent.yml:1-6

Core Technology Stack

The project is built upon a foundation of open-source tools to manage content, build the site, and provide a consistent development experience.

• Hugo: The core of the website is the Hugo static site generator. It is responsible for parsing Markdown content, applying layouts, and generating the final HTML, CSS, and JS files. The primary configuration for Hugo is located in hugo.yaml.
  Sources: CONTRIBUTING.md:10, hugo.yaml:1
• Docker & Docker Compose: The local development environment is fully containerized using Docker. Contributors use docker compose watch to run a local server that automatically rebuilds the site on file changes. This ensures a consistent environment for all contributors, regardless of their host OS. Docker is also used for running validation tests.
  Sources: CONTRIBUTING.md:37-56
• Hugo Modules: To manage documentation sourced from external repositories, the project uses Hugo Modules. This allows vendoring content directly from upstream projects like moby/moby, docker/cli, and docker/compose.
  Sources: hugo.yaml:222-225, agent.yml:25-32

Content Sourcing and Management

A key architectural feature is its hybrid approach to content management, combining locally managed articles with content vendored from external sources. This ensures that reference documentation is always synchronized with the source code it describes.

Vendored Content

Much of the reference documentation is not written directly in this repository. Instead, it is pulled from upstream repositories using Hugo Modules, as defined in hugo.yaml. This content is treated as read-only within the docker-docs project.

The diagram below illustrates the flow of content from upstream repositories into the Hugo build process.

The following table details the upstream sources and the content they provide.

Content Area	Upstream Repository	Source Path in Repo	Target in docker-docs
Docker CLI Reference	docker/cli	docs/reference/run.md, etc.	content/manuals/engine/containers/run.md
Buildx Reference	docker/buildx	docs/bake-reference.md	content/manuals/build/bake/reference.md
Compose CLI Reference	docker/compose/v5	docs/reference/*.yaml	data/compose-cli/
Dockerfile Reference	moby/buildkit	frontend/dockerfile/docs/reference.md	content/reference/dockerfile.md
Engine API Reference	moby/moby/api	docs/*.yaml	content/reference/api/engine/version/
Model Runner CLI	docker/model-runner	cmd/cli/docs/reference/*.yaml	data/model-cli/

Sources: hugo.yaml:232-299, CONTRIBUTING.md:73-81, agent.yml:82-88, content/reference/cli/docker/README.md:9-16

Local Content

Guides, tutorials, conceptual articles, and contribution guidelines are managed directly within the docker/docs repository, primarily under the content/ directory. These are standard Markdown files with YAML front matter for metadata.

Sources: CONTRIBUTING.md:11, content/contribute/file-conventions.md:9-15

Build, Test, and Deployment

The project has a well-defined workflow for local development, testing, and eventual deployment.

Local Development Workflow

Contributors use a Docker-based environment for local development. The docker compose watch command starts a development server and watches for file changes, providing live reloads.

Validation and Testing

Before submitting a pull request, contributors are expected to run local validation tests using the command docker buildx bake validate. This command executes a series of checks, including:

• Markdown linting
• HTML validation
• Link checking

This pre-flight check helps catch common errors early and ensures a higher quality of contributions.

Sources: CONTRIBUTING.md:65-69, agent.yml:195-197

Automated Documentation Workflow

The agent.yml file defines a sophisticated, multi-agent system for coordinating documentation work. This system automates the process of analyzing requests, delegating tasks to specialized agents, and validating the output.

Agent Roles

The system consists of three main agents: root, writer, and editor.

Agent	Role	Key Responsibilities
root	Coordinator	Analyzes requests, discovers existing content, scopes work, and delegates to writer and editor. Orchestrates the entire workflow.
writer	Content Creator	Writes new documentation or updates existing content based on instructions from the root agent. Focuses on content quality and clarity.
editor	Polisher & Validator	Fixes formatting, enforces style guides, removes "AI-isms", ensures Hugo syntax is correct, and runs validation checks.

Sources: agent.yml:2-200

Workflow Sequence

The agents interact in a specific sequence to process a documentation request, from initial analysis to final validation.

Site Structure and SEO

The project includes specific configurations and templates to optimize content structure and search engine visibility.

Front Matter

All content pages require YAML front matter to define metadata. This is crucial for Hugo's build process and for SEO.

Key	Required	Description
title	Yes	The page title, used as the <h1>.
description	Yes	A sentence describing the page for HTML metadata.
keywords	Yes	A comma-separated list of keywords for HTML metadata.
aliases	No	A list of URLs that should redirect to this page.
toc_max	No	The maximum heading level to include in the in-page Table of Contents.

Sources: content/contribute/file-conventions.md:9-29

Schema.org and SEO Metadata

The site automatically generates structured data in JSON-LD format for better search engine understanding. The layouts/partials/schema.html template is responsible for creating TechArticle and BreadcrumbList schemas.

This process involves:

1. Extracting metadata like title, description, keywords, PublishDate, and Lastmod from the page.
2. Constructing a TechArticle schema object.
3. Generating a BreadcrumbList schema based on the page's ancestors in the site hierarchy.
4. Embedding this structured data as a <script type="application/ld+json"> tag in the page's HTML <head>.

Sources: layouts/partials/schema.html:1-94, layouts/partials/meta.html:1-42

Conclusion

The architecture of the Docker Documentation repository is a robust and scalable system designed for maintaining a large, complex documentation site. By leveraging Hugo's modularity for content sourcing, Docker for a consistent development environment, and a custom agent-based system for workflow automation, the project effectively manages contributions and ensures content quality. The clear separation between locally managed content and vendored reference documentation allows for both flexibility in creating narrative guides and strict synchronization with the underlying source code of Docker's products.