Architecture
Site architecture defines how source material becomes a published page. The site uses three primary patterns: hand-written Markdown pages, Markdown pages that render structured data, and pages generated at build time by Hugo content adapters.
The architecture pages explain the implementation mechanics. Governance pages decide ownership, naming, content rules, and strategy.
Canonical home#
A canonical home is the durable place where a piece of information is maintained. Other pages can summarize it, list it, translate it, or link to it, but only one place is treated as the source of truth.
| Material | Canonical home |
|---|---|
| Essays and longer notes | Blog posts |
| Small things learned | TIL entries |
| Talks, publications, and repeatable references | Data files plus a rendering page |
| Many data records that need their own pages | Data files plus a content adapter |
| Work first published elsewhere | Local archive pages linking back to sources |
The practical test is simple: if this information needs to be updated six months from now, where should the change happen?
Pattern guide#
Use the smallest pattern that preserves ownership and makes future changes obvious.
| Pattern | Use when | Details |
|---|---|---|
| Markdown page | The page itself is the artifact | Governed by content and front matter rules |
| Data-driven page | One durable page presents structured facts | Data-driven pages |
| Content adapter | Many data records need normal Hugo pages | Content adapters |
| Front matter | Page metadata, component profiles, and folder archetypes shape rendering | Front matter |
| Component migration | A generated audit and repeatable rollout standardize component documentation | Component migration |
| Archetypes | Reusable starter files create known content shapes | Archetypes |
| Asset pipeline | CSS, token output, JavaScript, fonts, and fingerprints are bundled | Hugo asset pipeline |
| Token architecture | DTCG source, theme collections, generated artifacts, and validation align | Token architecture |
| i18n mechanics | UI strings, language alternates, and language-aware templates are involved | i18n |
| Generated surface | A data source renders a specific reference, such as the brand glossary | Glossary generation |
| Mermaid diagram | Structured text diagrams document architecture, flows, and relationships | Mermaid diagram syntax |
Prefer explicit Markdown files for durable editorial pages. Prefer structured data when facts repeat. Use content adapters only when data records need their own URLs, metadata, search behaviour, language alternates, or taxonomy behaviour.
| Archetypes | Reusable Hugo starter files for recurring content shapes | |
| Component migration | The rollout recipe and live audit for standardized component documentation | |
| Content adapters | How Hugo content adapters turn data records into generated pages | |
| Data-driven pages | How structured data renders into durable reference pages | |
| Front matter | How page metadata, component and pattern profiles, and folder archetypes shape rendered documentation | |
| Glossary generation | How glossary data renders into the brand documentation | |
| Hugo asset pipeline | How Hugo bundles generated token CSS, site CSS, JavaScript, and fonts | |
| i18n | How UI strings are translated: where keys live, how templates call them, and what happens when one is missing | |
| Mermaid diagram syntax | Supported Mermaid diagram families and when to use them in documentation | |
| Pattern library | The data model and implementation recipe for documented compositions of components | |
| Shortcodes | How shortcodes bridge Markdown authoring and reusable Hugo layout logic | |
| Token architecture | How DTCG tokens, theme collections, generated artifacts, and consumers remain aligned |