Markdown Front Matter
Relevant source files
The following files were used as context for generating this wiki page:
Front matter is a block of YAML content at the top of a Markdown file, enclosed by three hyphens (---). It serves as a metadata provider for the Hugo static site generator, which builds the Docker documentation website. This metadata controls various aspects of a page, including its title, SEO attributes like description and keywords, navigation behavior, table of contents generation, and structured data for search engines.
All content pages require front matter, with title, description, and keywords being mandatory fields. The system also supports specialized front matter for different content types, such as guides, and allows for external metadata definition for files that cannot be directly edited.
Sources: content/contribute/file-conventions.md:13-16, agent.yml:100-101
Structure and Processing
Front matter is processed by the Hugo build system to generate the final HTML pages. The metadata within the YAML block is used by various templates and shortcodes to render content correctly and enrich the page with additional features.
The following diagram illustrates the basic flow from a Markdown file to a rendered HTML page.
Example
Here is an example of a valid front matter block. The order of the keys is not important.
---
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:52-69
Core Metadata Fields
These are the primary front matter keys supported across most content pages.
| Key | Required | Description |
|---|---|---|
title | Yes | The page title. This is added to the HTML as an <h1> header. |
linkTitle | No | A shorter title used for the sidebar navigation. If not defined, title is used. |
description | Yes | A sentence describing the page contents, added to HTML metadata for SEO. It is not rendered on the page. |
keywords | Yes | A comma-separated list of keywords added to HTML metadata for SEO. |
aliases | No | A YAML list of pages that should perform a 302 redirect to the current page. |
weight | No | A number that influences the sorting order of pages within a section. |
notoc | No | If true, no in-page Table of Contents (TOC) is generated. Defaults to false. |
toc_min | No | The minimum heading level (e.g., 2 for <h2>) to include in the in-page TOC. Defaults to 2. |
toc_max | No | The maximum heading level (e.g., 3 for <h3>) to include in the in-page TOC. Defaults to 3. |
sitemap | No | If false, the page is excluded from sitemap.xml and a noindex meta tag is added. |
build | No | An object to control build behavior. For example, render: never prevents a page from being rendered. |
Sources: content/contribute/file-conventions.md:18-47, CONTRIBUTING.md:26-29, content/reference/cli/docker/README.md:2-5
Guide-Specific Metadata
Pages under content/guides/ have additional metadata fields to support filtering and provide more context on the guides landing page.
| Key | Required | Description |
|---|---|---|
summary | Yes | A brief overview of the guide's content. |
tags | Optional | A list of domains or subject areas covered (e.g., machine-learning). At least one tags or languages entry should be present. |
languages | Optional | A list of programming languages used in the guide (e.g., python). |
params.time | Optional | Estimated completion time, e.g., "30 minutes". This is converted to ISO 8601 duration for schema. |
Sources: content/contribute/guides.md:29-47, layouts/partials/schema.html:40-51
Example Guide Front Matter
---
title: Generate Docker Compose Files with Claude Code and Docker MCP Toolkit
summary: |
This guide shows how to wire Claude Code to the Docker MCP Toolkit so it can search Docker Hub images and generate complete Docker Compose stacks from natural language.
You’ll enable the Docker Hub MCP server, connect Claude Code, verify MCP access, and create a Node.js + PostgreSQL stack with a conversational prompt.
tags: [ai]
aliases:
- /guides/use-case/genai-claude-code-mcp/
params:
time: 15 minutes
---
Sources: content/guides/genai-claude-code-mcp/claude-code-mcp-guide.md:1-12
Sidebar Configuration
Front matter can be used to customize how a page's entry appears in the sidebar navigation.
| Key | Description |
|---|---|
sidebar.reverse | For section pages, this reverses the sort order of child pages in the sidebar. |
sidebar.goto | Changes the URL that the sidebar entry points to. Useful for creating a sidebar entry that links to an external or different internal page. |
sidebar.badge | Adds a badge to the sidebar entry. This is an object with text and color fields. |
Sources: content/contribute/file-conventions.md:42-47, content/contribute/components/badges.md:28-34
Sidebar Badge Example
To add a "Deprecated" badge to a page's sidebar entry, you would use the following front matter:
---
title: Page title
params:
sidebar:
badge:
color: gray
text: Deprecated
---
Sources: content/contribute/components/badges.md:28-34
Schema.org Integration
The Hugo template at layouts/partials/schema.html consumes front matter to generate TechArticle and BreadcrumbList JSON-LD structured data. This enhances how pages are represented in search engine results.
The diagram below shows how front matter fields are mapped to the TechArticle schema.
This diagram shows the transformation of front matter data into a TechArticle JSON-LD schema by the Hugo template.
Sources: layouts/partials/schema.html:5-39
The template specifically processes params.time from a human-readable string (e.g., "20 minutes") into an ISO 8601 duration format (e.g., "PT20M").
{{- with .Params.time -}}
{{- /* Convert "20 minutes" to ISO 8601 duration "PT20M" */ -}}
{{- $duration := . -}}
{{- $isoDuration := "" -}}
{{- if findRE `(\d+)\s*minutes?` $duration -}}
{{- $mins := index (findRE `\d+` $duration) 0 -}}
{{- $isoDuration = printf "PT%sM" $mins -}}
{{- end -}}
...
{{- with $isoDuration -}}
{{- $schema = merge $schema (dict "timeRequired" .) -}}
{{- end -}}
{{- end -}}
Sources: layouts/partials/schema.html:40-51
External Front Matter
For content that is vendored from upstream repositories or otherwise cannot have front matter added directly to the Markdown file, the data/frontmatter.yaml file provides an alternative. This file allows you to define description and keywords for pages by mapping them to the file path relative to the content directory.
# this file lets you add descriptions and keywords
# to files without modifying the file.
#
# Useful for upstream pages where we don't want to
# or can't add front matter to the source!
build/attestations/attestation-storage.md:
description: |
How SBOM and provenance attestations are stored for images.
keywords: |
build, attestations, sbom, provenance, storage, manifest
reference/dockerfile.md:
description: |
Find all the available commands you can use in a Dockerfile
and learn how to use them, including COPY, ARG, ENTRYPOINT, and more.
keywords: |
dockerfile, docker file, docker copy, dockerfile exec, docker entrypoint,
dockerfile entrypoint, dockerfile arg, docker args, entrypoint, shell dockerfile
Sources: data/frontmatter.yaml:1-29, content/reference/cli/docker/README.md:1-5
Summary
Markdown front matter is a critical component of the Docker documentation content strategy. It provides a powerful and flexible way to manage page metadata, control rendering and navigation, and improve SEO through structured data. By adhering to the defined front matter conventions, contributors ensure that content is consistent, discoverable, and well-integrated into the documentation website.
Sources: content/contribute/file-conventions.md, agent.yml:40-43