Glossary Management

Relevant source files

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

• data/glossary.yaml
• layouts/_default/glossary.html
• content/reference/glossary.md
• content/contribute/style/grammar.md
• content/contribute/style/recommended-words.md
• hugo.yaml

The Glossary Management system within the Docker documentation project provides a centralized and data-driven approach to defining and displaying technical terms. Its purpose is to ensure consistency and accuracy of terminology across the entire documentation site. The system decouples the glossary content from its presentation, allowing for easier updates and maintenance.

The core of the system is a single YAML data file that houses all terms and definitions. A dedicated Hugo layout then processes this file to dynamically generate the public-facing glossary page. This architecture simplifies the contribution process, as editors only need to modify the YAML file to add or update entries, without touching any layout or content files.

System Architecture

The glossary feature is built on the interaction between a Hugo content file, a data file, and a custom layout. This follows a standard Hugo pattern for rendering data-driven pages.

Data Flow

The process for rendering the glossary page involves several steps, from data definition to HTML generation.

The following diagram illustrates the data flow for the glossary page generation.

1. A user or the build process accesses the /glossary/ page.
2. Hugo identifies content/reference/glossary.md as the content file for this page.
3. The front matter in this file specifies layout: glossary.
4. Hugo selects layouts/_default/glossary.html to render the page.
5. The glossary.html template loads and ranges over the data from site.Data.glossary. This data is sourced from the data/glossary.yaml file.
6. The template generates the final HTML, which is then served to the user.

Sources: content/reference/glossary.md:6, layouts/_default/glossary.html:3-4, hugo.yaml:1

Components

Data Source: glossary.yaml

All glossary terms and their definitions are stored in data/glossary.yaml. This file is the single source of truth for glossary content. Contributions and edits to the glossary are made directly to this file.

Sources: content/reference/glossary.md:14-15

Data Structure

The YAML file is a list of objects, where each object represents a single glossary entry.

The diagram below shows the entity relationship for a glossary entry.

Each entry has two required fields:

| Field | Type | Description - term | String | The word or phrase being defined. - definition | String | The explanation of the term. This can include Markdown formatting. -

Source: data/glossary.yaml (structure inferred from layouts/_default/glossary.html)

Content Page: glossary.md

The file content/reference/glossary.md serves as the entry point for the glossary page. It contains front matter that configures the page's behavior and metadata.

---
title: Glossary
description: Glossary of terms used around Docker
keywords: glossary, docker, terms, definitions
notoc: true
layout: glossary
aliases:
- /engine/reference/glossary/
- /glossary/
---

Source: content/reference/glossary.md:1-9

Key front matter fields include:

Key	Value	Description
title	Glossary	Sets the main <h1> title of the page.
layout	glossary	Instructs Hugo to use the glossary.html layout for rendering, which is the key to this system.
notoc	true	Disables the in-page table of contents, as the alphabetical list of terms serves as the primary navigation.
aliases	list	Provides URL redirects from old paths to the current glossary page.

Sources: content/reference/glossary.md:1-9, content/contribute/file-conventions.md:13-31

Layout Template: glossary.html

The layouts/_default/glossary.html template is responsible for fetching the glossary data and rendering it into an HTML definition list (<dl>).

The core logic of the template is a loop that iterates through the sorted glossary data:

{{ define "main" }}
<div class="main-content">
  {{ range sort site.Data.glossary "term" }}
    <dl>
      <dt id="{{ .term | anchorize }}">{{ .term }}</dt>
      <dd>{{ .definition | markdownify }}</dd>
    </dl>
  {{ end }}
</div>
{{ end }}

Source: [layouts/_default/glossary.html:1-9]

Key operations in this template:

• range sort site.Data.glossary "term": This line retrieves all entries from data/glossary.yaml, sorts them alphabetically by the term field.
• <dt id="{{ .term | anchorize }}">: For each entry, it creates a definition term (<dt>) and uses the anchorize function to create a URL-friendly ID, allowing for direct linking to terms.
• <dd>{{ .definition | markdownify }}: It creates a definition description (<dd>) and processes the definition string through markdownify, which converts any Markdown syntax within the definition into HTML.

Source: layouts/_default/glossary.html:3-6

Contribution and Style Guidelines

The documentation provides clear guidance for how terms should be defined and formatted, ensuring consistency with the overall style of Docker's documentation.

Editing Process

Contributors are explicitly instructed not to edit the glossary.md page directly for content. Instead, a comment in the file directs them to the data/glossary.yaml file.

<!--
To edit/add/remove glossary entries, visit the YAML file at:
https://github.com/docker/docs/blob/main/data/glossary.yaml
-->

Source: content/reference/glossary.md:13-16

Terminology and Wording

The glossary must adhere to the project's recommended word list. For example, terms like sign in should be used instead of log in, and repository instead of repo. This ensures that the definitions themselves use consistent and approved language.

Source: content/contribute/style/recommended-words.md:6-94

Acronyms and Initialisms

The style guide provides best practices for handling acronyms and initialisms, which are common in technical glossaries.

• On first use on a page, the term should be spelled out, followed by the acronym in parentheses, e.g., "single sign-on (SSO)".
• For widely known acronyms like URL or HTML, this is not necessary.
• Plural acronyms should not use an apostrophe (e.g., URLs, not URL's).

These rules should be applied within the definitions provided in data/glossary.yaml.

Source: content/contribute/style/grammar.md:8-21

Summary

The Glossary Management system is an effective, data-driven feature of the documentation site. By centralizing all term definitions in a single glossary.yaml file and using a dedicated Hugo template for rendering, it streamlines the contribution process and enforces terminological consistency. This separation of content and presentation is a robust architectural choice that simplifies maintenance and aligns with modern static site generation best practices.