Hugo Configuration

Relevant source files

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

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

The Docker documentation website is a static site built using the Hugo static site generator. The configuration defines the site's structure, build process, content aggregation from multiple sources, and metadata generation. The primary configuration is managed in hugo.yaml, which works in concert with front matter in content files and custom layouts to produce the final HTML output.

This system is designed to automatically vendor documentation from upstream repositories, ensuring that reference materials for tools like the Docker CLI, Buildx, and Compose are kept up-to-date with their respective source projects.

Core Configuration

The main configuration file hugo.yaml defines global settings, content processing rules, build behaviors, and menus.

Sources: hugo.yaml

Global Settings

Key global settings establish the site's identity and behavior.

Parameter	Value	Description
title	Docker Docs	The title of the website.
baseURL	https://docs.docker.com	The absolute base URL for the production site.
enableGitInfo	true	Enables Hugo to access Git history for features like Lastmod dates.
disablePathToLower	true	Prevents Hugo from converting URL paths to lowercase.
refLinksErrorLevel	ERROR	Causes the build to fail on broken reference links.

Sources: hugo.yaml:1-6

Permalinks and Markup

The configuration customizes URL structures and how Markdown is rendered.

Permalinks
A custom permalink rule is defined for content in the manuals section to remove the /manuals prefix from the published URL.

permalinks:
  page:
    manuals: /:sections[1:]/:slugorcontentbasename/
  section:
    manuals: /:sections[1:]/

Sources: hugo.yaml:12-17

Markup (Goldmark)
The Goldmark Markdown renderer is configured to allow inline HTML and attributes on block-level elements, while disabling the typographer extension which can interfere with code snippets.

markup:
  goldmark:
    renderer:
      # Allow inline HTML
      unsafe: true

Sources: hugo.yaml:19-29

Custom Output Formats

The project defines several custom output formats beyond HTML to support site features like search and redirects.

Format	baseName	Media Type	Description
redirects	redirects	application/json	Generates a JSON file containing all page redirects.
metadata	metadata	application/json	Creates a metadata file used by the global search functionality.
llms	llms	text/plain	Generates a plain text file, likely for consumption by Large Language Models.

These formats are enabled on the homepage to be generated once per build.
Sources: hugo.yaml:43-69

Content Aggregation via Hugo Modules

A key feature of the build system is its use of Hugo Modules to vendor documentation from external repositories. This ensures that reference documentation is sourced directly from the projects it describes. The hugo.yaml file defines which repositories to import and how to mount their content into the local file system.

Sources: hugo.yaml:195-269, agent.yml:41-47, CONTRIBUTING.md:73-81

The following diagram illustrates the content vendoring flow.

Module Import Example

This snippet from hugo.yaml shows how the Dockerfile reference is imported from the moby/buildkit repository.

  imports:
    # BuildKit
    - path: github.com/moby/buildkit
      mounts:
        - source: frontend/dockerfile/docs/reference.md
          target: content/reference/dockerfile.md

Sources: hugo.yaml:212-216

Content vendored this way is considered read-only within the docker-docs repository. Any changes must be made in the upstream source repository.

Sources: agent.yml:41-47, CONTRIBUTING.md:73-81

Content Front Matter

Every Markdown page requires a YAML front matter block at the top to provide essential metadata. This metadata is used for generating HTML tags, controlling page layout, and populating search indexes.

Sources: content/contribute/file-conventions.md:12-42, content/contribute/guides.md:29-52

Key	Required	Description
title	Yes	The page title, rendered as an <h1> tag.
description	Yes	A sentence describing the page, used in HTML metadata.
keywords	Yes	A comma-separated list of keywords for HTML metadata.
aliases	No	A list of old URLs that should redirect to this page.
notoc	No	If true, the in-page Table of Contents is not generated.
toc_min / toc_max	No	Sets the minimum and maximum heading levels for the in-page TOC.
sitemap	No	If false, excludes the page from sitemap.xml and adds a noindex meta tag.
sidebar.goto	No	Overrides the sidebar link to point to a different URL.
params.time	No	Estimated completion time for guides (e.g., "30 minutes").

Front Matter Example

---
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:44-58

Layouts and Schema Generation

Hugo uses layouts in the layouts/ directory to render content into HTML. Partials like layouts/partials/schema.html are used to generate specific parts of a page, such as structured data for search engines.

The schema.html partial constructs a TechArticle and BreadcrumbList JSON-LD schema. It dynamically pulls data from the page's front matter (e.g., title, description, keywords, params.time) and Git information (PublishDate, Lastmod).

Sources: layouts/partials/schema.html

This sequence diagram shows how the schema is generated during page rendering.

Build and Development

The contribution guide outlines the process for building the site locally and running validation tests. This workflow relies on Docker Compose and is configured to watch for file changes.

Sources: CONTRIBUTING.md:46-71

1. Local Development: The docker compose watch command starts a local development server at http://localhost:1313. It uses file watching to automatically rebuild the site on changes. This requires Docker Desktop 4.24+ or Docker Compose 2.22+.
2. Validation: Before submitting a pull request, contributors must run docker buildx bake validate. This command executes a series of local tests, including checks for broken links and malformed markup, ensuring content quality.

The build process is defined in hugo.yaml under the build key, which configures cache-busting for assets and enables buildStats for use with Tailwind CSS.

Sources: hugo.yaml:31-41

Summary

The Hugo configuration for the Docker documentation project is a sophisticated system that automates content aggregation from multiple upstream sources via Hugo Modules. It enforces content structure through required front matter and provides a robust local development and validation workflow using Docker. Key files like hugo.yaml, content/contribute/file-conventions.md, and CONTRIBUTING.md define the architecture, content standards, and contribution process for the entire documentation site.