docker-docs/COMPONENTS.md

Docker Documentation Components Guide

This guide explains how to use components, shortcodes, and special features when writing Docker documentation. For writing style and grammar, see STYLE.md.

Front matter

Every documentation page requires front matter at the top of the file.

Required fields

---
title: Install Docker Engine on Ubuntu
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu
---

Field	Description
title	Page title, used in <h1> and <title> tag
description	SEO description (150-160 characters), added to HTML metadata
keywords	Comma-separated keywords for SEO

Optional fields

Field	Description
linkTitle	Shorter title for navigation and sidebar (if different from title)
weight	Controls sort order in navigation (lower numbers appear first)
aliases	List of URLs that redirect to this page
toc_min	Minimum heading level in table of contents (default: 2)
toc_max	Maximum heading level in table of contents (default: 3)
notoc	Set to true to disable table of contents
sitemap	Set to false to exclude from search engine indexing
sidebar.badge	Add badge to sidebar (see Badges)
sidebar.reverse	Reverse sort order of pages in section
sidebar.goto	Override sidebar link URL

Example with optional fields

---
title: Install Docker Engine on Ubuntu
linkTitle: Install on Ubuntu
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu, install, uninstall
weight: 10
aliases:
  - /engine/installation/linux/ubuntu/
  - /install/linux/ubuntu/
toc_max: 4
params:
  sidebar:
    badge:
      color: blue
      text: Beta
---

Series (guide) pages

Section pages under content/guides/ automatically use the series layout (via a Hugo cascade in hugo.yaml). Series pages support additional front matter parameters for the metadata card:

---
title: Getting started
description: Learn the basics of Docker
summary: |
  A longer summary shown on the series landing page.
params:
  proficiencyLevel: Beginner
  time: 15 minutes
  prerequisites: None
---

Field	Description
summary	Extended description for the series page
proficiencyLevel	Skill level (Beginner, Intermediate)
time	Estimated time to complete
prerequisites	Prerequisites or "None"

Shortcodes

Shortcodes are reusable components that add rich functionality to your documentation.

Tabs

Use tabs for platform-specific instructions or content variations.

Example:

{{< tabs >}} {{< tab name="Linux" >}}

$ docker run hello-world

{{< /tab >}} {{< tab name="macOS" >}}

$ docker run hello-world

{{< /tab >}} {{< tab name="Windows" >}}

docker run hello-world

{{< /tab >}} {{< /tabs >}}

Syntax:

{{</* tabs */>}}
{{</* tab name="Linux" */>}}
Content for Linux
{{</* /tab */>}}
{{</* tab name="macOS" */>}}
Content for macOS
{{</* /tab */>}}
{{</* /tabs */>}}

Tab groups (synchronized selection):

Use the group attribute to synchronize tab selection across multiple tab sections:

{{</* tabs group="os" */>}}
{{</* tab name="Linux" */>}}
Linux content for first section
{{</* /tab */>}}
{{</* tab name="macOS" */>}}
macOS content for first section
{{</* /tab */>}}
{{</* /tabs */>}}

{{</* tabs group="os" */>}}
{{</* tab name="Linux" */>}}
Linux content for second section
{{</* /tab */>}}
{{</* tab name="macOS" */>}}
macOS content for second section
{{</* /tab */>}}
{{</* /tabs */>}}

When a user selects "Linux" in the first section, all tabs in the "os" group switch to "Linux".

Accordion

Use accordions for collapsible content like optional steps or advanced configuration.

Example:

{{< accordion title="Advanced configuration" >}}

version: "3.8"
services:
  web:
    build: .
    ports:
      - "8000:8000"

{{< /accordion >}}

Syntax:

{{</* accordion title="Advanced configuration" */>}}
Content inside the accordion
{{</* /accordion */>}}

Include

Reuse content across multiple pages using the include shortcode. Include files must be in the content/includes/ directory.

Syntax:

{{</* include "filename.md" */>}}

Example:

{{</* include "install-prerequisites.md" */>}}

Badges

Use badges to highlight new, beta, experimental, or deprecated content.

Example:

{{< badge color=blue text="Beta" >}} {{< badge color=violet text="Experimental" >}} {{< badge color=green text="New" >}} {{< badge color=gray text="Deprecated" >}}

Syntax:

Inline badge:

{{</* badge color=blue text="Beta" */>}}

Badge as link:

[{{</* badge color=blue text="Beta feature" */>}}](link-to-page.md)

Sidebar badge (in front matter):

---
title: Page title
params:
  sidebar:
    badge:
      color: violet
      text: Experimental
---

Color options:

• blue - Beta content
• violet - Experimental or early access
• green - New GA content
• amber - Warning or attention
• red - Critical
• gray - Deprecated

Usage guidelines:

• Use badges for no longer than 2 months post-release
• Use violet for experimental/early access features
• Use blue for beta features
• Use green for new GA features
• Use gray for deprecated features

Summary bars

Summary bars indicate subscription requirements, version requirements, or administrator-only features at the top of a page.

Example:

{{< summary-bar feature_name="Docker Scout" >}}

Setup:

1. Add feature to /data/summary.yaml:

features:
  Docker Scout:
    subscription: Business
    availability: GA
    requires: "Docker Desktop 4.17 or later"

2. Add shortcode to page:

{{</* summary-bar feature_name="Docker Scout" */>}}

Attributes in summary.yaml:

Attribute	Description	Values
subscription	Subscription tier required	All, Personal, Pro, Team, Business
availability	Product development stage	Experimental, Beta, Early Access, GA, Retired
requires	Minimum version requirement	String describing version (link to release notes)
for	Indicates administrator-only features	Administrators

Buttons

Create styled buttons for calls to action.

Syntax:

{{</* button text="Download Docker Desktop" url="/get-docker/" */>}}

Cards

Create card layouts for organizing content.

Syntax:

{{</* card
  title="Get started"
  description="Learn Docker basics"
  link="/get-started/"
*/>}}

Icons

Use Material Symbols icons in your content.

Syntax:

{{</* icon name="check_circle" */>}}

Browse available icons at Material Symbols.

Callouts

Use GitHub-style callouts to emphasize important information. Use sparingly - only when information truly deserves special emphasis.

Syntax:

> [!NOTE]
> This is a note with helpful context.

> [!TIP]
> This is a helpful suggestion or best practice.

> [!IMPORTANT]
> This is critical information users must understand.

> [!WARNING]
> This warns about potential issues or consequences.

> [!CAUTION]
> This is for dangerous operations requiring extreme care.

When to use each type:

Type	Use for	Color
Note	Information that may not apply to all readers or is tangential	Blue
Tip	Helpful suggestions or best practices	Green
Important	Issues of moderate magnitude	Yellow
Warning	Actions that may cause damage or data loss	Red
Caution	Serious risks	Red

Code blocks

Format code with syntax highlighting using triple backticks and language hints.

Language hints

Common language hints:

• console - Interactive shell with $ prompt
• bash - Bash scripts
• dockerfile - Dockerfiles
• yaml - YAML files
• json - JSON data
• go, python, javascript - Programming languages
• powershell - PowerShell commands

Interactive shell example:

```console
$ docker run hello-world
```

Bash script example:

```bash
#!/usr/bin/bash
echo "Hello from Docker"
```

Variables in code

Use <VARIABLE_NAME> format for placeholder values:

```console
$ docker tag <IMAGE_NAME> <REGISTRY>/<IMAGE_NAME>:<TAG>
```

This syntax renders variables in a special color and font style.

Highlighting lines

Highlight specific lines with hl_lines:

```go {hl_lines=[3,4]}
func main() {
    fmt.Println("Hello")
    fmt.Println("This line is highlighted")
    fmt.Println("This line is highlighted")
}
```

Collapsible code blocks

Make long code blocks collapsible:

```dockerfile {collapse=true}
# syntax=docker/dockerfile:1
FROM golang:1.21-alpine
RUN apk add --no-cache git
# ... more lines
```

Images

Add images using standard Markdown syntax with optional query parameters for sizing and borders.

Basic syntax:

![Alt text description](/assets/images/image.png)

With size parameters:

![Alt text](/assets/images/image.png?w=600&h=400)

With border:

![Alt text](/assets/images/image.png?border=true)

Combined parameters:

![Alt text](/assets/images/image.png?w=600&h=400&border=true)

Best practices:

• Store images in /static/assets/images/
• Use descriptive alt text for accessibility
• Compress images before adding to repository
• Capture only relevant UI, avoid unnecessary whitespace
• Use realistic text, not lorem ipsum
• Remove unused images from repository

Videos

Embed videos using HTML video tags or platform-specific embeds.

Local video:

<video controls width="100%">
  <source src="/assets/videos/demo.mp4" type="video/mp4" />
</video>

YouTube embed:

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  frameborder="0"
  allow="autoplay; encrypted-media"
  allowfullscreen
>
</iframe>

Links

Use standard Markdown link syntax. For internal links, use relative paths with source filenames.

External link:

[Docker Hub](https://hub.docker.com/)

Internal link (same section):

[Installation guide](install.md)

Internal link (different section):

[Get started](/get-started/overview.md)

Link to heading:

[Prerequisites](#prerequisites)

Best practices:

• Use descriptive link text (around 5 words)
• Front-load important terms
• Avoid generic text like "click here" or "learn more"
• Don't include end punctuation in link text
• Use relative paths for internal links

Lists

Unordered lists

- First item
- Second item
- Third item
  - Nested item
  - Another nested item

Ordered lists

1. First step
2. Second step
3. Third step
   1. Nested step
   2. Another nested step

Best practices

• Limit bulleted lists to 5 items when possible
• Don't add commas or semicolons to list item ends
• Capitalize list items for ease of scanning
• Make all list items parallel in structure
• For nested sequential lists, use lowercase letters (a, b, c)

Tables

Use standard Markdown table syntax with sentence case for headings.

Example:

| Feature        | Description                     | Availability |
| -------------- | ------------------------------- | ------------ |
| Docker Compose | Multi-container orchestration   | All          |
| Docker Scout   | Security vulnerability scanning | Business     |
| Build Cloud    | Remote build service            | Pro, Team    |

Best practices:

• Use sentence case for table headings
• Don't leave cells empty - use "N/A" or "None"
• Align decimals on the decimal point
• Keep tables scannable - avoid dense content

Quick reference

File structure

content/
├── manuals/              # Product documentation
│   ├── docker-desktop/
│   ├── docker-hub/
│   └── ...
├── guides/               # Learning guides
├── reference/            # API and CLI reference
└── includes/             # Reusable content snippets

Common patterns

Platform-specific instructions:

Use tabs with consistent names: Linux, macOS, Windows

Optional content:

Use accordions for advanced or optional information

Version/subscription indicators:

Use badges or summary bars

Important warnings:

Use callouts (NOTE, WARNING, CAUTION)

Code examples:

Use console for interactive shells, appropriate language hints for code