Relevant source files

The following files were used as context for generating this wiki page: - [data/glossary.yaml](https://github.com/Alonso-pixel/docker-docs/blob/main/data/glossary.yaml) - [layouts/_default/glossary.html](https://github.com/Alonso-pixel/docker-docs/blob/main/layouts/_default/glossary.html) - [content/reference/glossary.md](https://github.com/Alonso-pixel/docker-docs/blob/main/content/reference/glossary.md) - [content/contribute/style/grammar.md](https://github.com/Alonso-pixel/docker-docs/blob/main/content/contribute/style/grammar.md) - [content/contribute/style/recommended-words.md](https://github.com/Alonso-pixel/docker-docs/blob/main/content/contribute/style/recommended-words.md) - [hugo.yaml](https://github.com/Alonso-pixel/docker-docs/blob/main/hugo.yaml)

# Glossary Management 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. ```mermaid flowchart TD A[data/glossary.yaml] -->|Hugo build process| B{layouts/_default/glossary.html}; C[content/reference/glossary.md] -->|Specifies layout='glossary'| B; B -->|Renders data into HTML| D[Public Glossary Page]; subgraph "Data & Content" A C end subgraph "Templating" B end subgraph "Output" D end ``` *Sources: [content/reference/glossary.md:6](), [layouts/_default/glossary.html](), [data/glossary.yaml]()* 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. ```mermaid erDiagram GLOSSARY_ENTRY { string term string definition } ``` 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. ```yaml --- 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 `

` 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 (`
`). The core logic of the template is a loop that iterates through the sorted glossary data: ```go-html-template {{ define "main" }}
{{ range sort site.Data.glossary "term" }}

{{ .term }}

{{ .definition | markdownify }}

{{ end }}
{{ 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. - `
`: For each entry, it creates a definition term (`
`) and uses the `anchorize` function to create a URL-friendly ID, allowing for direct linking to terms. - `
{{ .definition | markdownify }}`: It creates a definition description (`
`) 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. ```html ``` 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.