Glossary generation
The brand glossary is a data-driven documentation surface. The brand-system terms live in data/brand/glossary.yml; the docs page renders those terms with the glossary-table shortcode.
This keeps the boundary clear:
| Layer | Owner | Role |
|---|---|---|
| Governance | docs/site-governance/glossary/ | Rules for meaning, preferred terms, and scope |
| Data | data/brand/glossary.yml | Canonical terms, definitions, aliases, sources |
| Rendering | layouts/shortcodes/glossary-table.html | Sortable glossary table in the docs shell |
| Lookup | docs/glossary/ | Easy access from the documentation overview |
Rendering rules#
- The rendered page should stay inside the docs layout so readers keep the documentation sidebar.
- The root glossary page should be linked under Overview for quick access.
- The table should read from structured data, not hand-written Markdown rows.
- English and French pages should render from the same source data.
- Missing definitions should be skipped rather than rendering empty rows.
- Each term row should keep a stable
idbased on the data key so readers can copy a direct anchor link. - Term and abbreviation grouping should come from the
kindfield instead of separate manual tables. Acronym and initialism distinctions belong in definitions. - Inline definitions should continue to use the
definitionshortcode.
Data rules#
The data file is manually curated today. Add automation only when there is a trustworthy upstream source or a repeatable transformation that can be reviewed cleanly.
The main-site reference glossary continues to use data/series/ref/glossary.yml. It uses the same table partial as the brand glossary, but keeps its own title block, introduction, and technology/security-oriented data source.
If the glossary grows beyond a single lookup table, consider generated category pages or richer filters. Do not split the source of truth unless a second glossary has a genuinely different audience or ownership model.