Project Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• hugo.yaml
• CONTRIBUTING.md
• agent.yml
• content/contribute/file-conventions.md
• content/contribute/style/formatting.md
• layouts/partials/schema.html

The docker-docs repository contains the source code for Docker's official documentation, published at https://docs.docker.com/. The site is built using the Hugo static site generator, with content written primarily in Markdown. The project incorporates a sophisticated system for managing content, including a local development environment powered by Docker Compose, automated documentation workflows using AI agents, and a modular approach to include documentation from multiple upstream repositories.

The repository defines strict contribution guidelines, style guides, and file conventions to maintain consistency and quality. It also utilizes Hugo's features for templating, content organization, and managing vendored content from other Docker projects like the Docker CLI and BuildKit.

Architecture and Tooling

The project's architecture is centered around the Hugo static site generator, which processes Markdown content and layout files to produce the final HTML website. Docker is used extensively for local development and testing.

Sources: CONTRIBUTING.md, hugo.yaml

Static Site Generation

The core of the project is Hugo. The hugo.yaml file configures the site's behavior, including permalinks, output formats, and module imports.

The diagram below illustrates the high-level build process.

Local Development Environment

A local development environment can be set up using Docker Compose. The docker compose watch command starts a development server that automatically rebuilds the site on file changes, making it accessible at http://localhost:1313. This setup requires Docker Desktop 4.24+ or Docker Engine with Compose 2.22+.

The local development and testing workflow is as follows:

Automated Documentation Agents

The repository utilizes a system of AI agents to coordinate documentation work. This system, defined in agent.yml, consists of a root coordinator and specialized writer and editor agents.

Agent	Description	Key Responsibilities
root	Documentation coordinator for analysis and delegation.	Analyzes requests, discovers content, scopes work, and delegates to writer and editor agents.
writer	Technical writer for creating and editing documentation.	Writes clear, practical content following voice and tone guidelines. Focuses on content quality, not formatting.
editor	Editor that polishes, validates, and fixes documentation.	Fixes formatting (80-char wrap), runs Prettier, ensures Hugo syntax, removes AI-isms, and runs validation checks.

Sources: agent.yml:1-178

The agent workflow is designed to streamline the process from request to final validation.

Content Structure

All documentation content resides in the content/ directory. The structure of this directory defines the sidebar navigation on the website.

Sources: CONTRIBUTING.md:14-16, content/contribute/file-conventions.md

Front Matter

Every Markdown page must begin with a YAML front matter block, enclosed by ---. This metadata is crucial for page rendering, SEO, and navigation.

Key	Required	Description
title	Yes	The <h1> page title.
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 pages that should redirect to the current page.
notoc	No	If true, no in-page Table of Contents is generated.
toc_min	No	The minimum heading level (e.g., 2 for <h2>) to include in the TOC.
toc_max	No	The maximum heading level (e.g., 3 for <h3>) to include in the TOC.

Sources: content/contribute/file-conventions.md:10-27

An example of a valid front matter block:

---
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update
title: Install Docker Engine on Ubuntu
aliases:
- /ee/docker-ee/ubuntu/
- /engine/installation/linux/docker-ce/ubuntu/
toc_max: 4
---

Sources: content/contribute/file-conventions.md:39-48

Schema.org Integration

The project generates structured data (JSON-LD) for search engines using schema.org vocabulary. The layouts/partials/schema.html template builds TechArticle and BreadcrumbList schemas. This includes metadata like publication dates, author, publisher, keywords, and parent-child relationships for breadcrumbs.

For pages with a time parameter in the front matter (e.g., "30 minutes"), it's converted to an ISO 8601 duration format (PT30M) for the timeRequired property.

Sources: layouts/partials/schema.html:1-89

Vendored and Generated Content

A significant portion of the documentation, particularly CLI and API references, is not edited directly in this repository. Instead, it is "vendored" from upstream repositories using Hugo Modules. This ensures that the reference documentation is always in sync with the source code.

Sources: CONTRIBUTING.md:74-88, hugo.yaml:228-294, agent.yml:35-50

The diagram below shows the flow of content from upstream repositories to the final documentation site.

The hugo.yaml file defines these imports in the module.imports section.

Upstream Repository	Content Provided
moby/moby/api	Engine API reference
moby/buildkit	Dockerfile reference, buildkitd.toml config
docker/buildx	Buildx Bake reference
docker/cli	Docker CLI command reference (dockerd, run)
docker/compose/v5	Compose CLI reference
docker/model-runner/cmd/cli	Model CLI reference

Sources: hugo.yaml:240-294, CONTRIBUTING.md:77-88

Here is a snippet from hugo.yaml showing how BuildKit content is mounted:

    # BuildKit
    - path: github.com/moby/buildkit
      mounts:
        - source: frontend/dockerfile/docs/reference.md
          target: content/reference/dockerfile.md
        - source: frontend/dockerfile/docs/rules
          target: content/reference/build-checks
          includeFiles: "*.md"

Sources: hugo.yaml:246-253

Because this content is read-only within the docker-docs repository, any required changes must be made in the respective upstream project. The automated agent system is specifically designed to identify and flag issues that originate from this vendored content without blocking local changes.

Sources: CONTRIBUTING.md:74-76, agent.yml:52-87