# Glossary pages

## Purpose

A glossary defines the terms one product's documentation uses. It is look-up material: the reader arrives with a word, finds its definition, and follows a link when the definition is not enough.

A glossary holds Azion-specific vocabulary: Products, Platform Resources, Features, and the terms Azion uses in its own way. A generic industry term, such as CDN, serverless, or virtual machine, belongs to the [Learning Center](https://www.azion.com/en/learning/), not to a documentation glossary. A term the industry also uses, but Azion uses differently, keeps its entry here and links the Learning Center for the generic sense.

It is not a naming-rules page. Product naming belongs to [Documentation terminology](/en/documentation/style-guide/writing/terminology/); the glossary defines what terms mean for the reader.

## When to use

Every product section carries a glossary, a required slot of the [product section skeleton](/en/documentation/style-guide/content/information-architecture/). Write it when the section is built, and extend it when a page introduces a term the reader must hold to follow the prose.

Do not write an entry for a term no page uses. Do not write an entry for a generic industry term: link the [Learning Center](https://www.azion.com/en/learning/) article from the page that needs it. Do not use the glossary to explain at length. A term that needs more than three sentences needs a [concept page](/en/documentation/style-guide/content/concept/), and its definition links to it.

## Register

Descriptive: 25 words per sentence. The tone is neutral and lexicographic: a definition states what the term is, without selling and without history.

## Structure

- One sentence of orientation naming the product whose terms the page defines.
- One `<GlossaryFilter>` component wrapping one GFM table, `| Term | Definition |`. The component adds the filter box and gives each row a deep-linkable anchor built from its term (`#cache-key`). Mechanics in [Components](/en/documentation/style-guide/components/).
- No closing section. The table is the page.

## Template

```mdx
import GlossaryFilter from '~/components/GlossaryFilter.astro'

Definitions for the terms the **<Product>** documentation uses.

<GlossaryFilter lang="en">

| Term | Definition |
| --- | --- |
| <term> | <What the term is, in one to three sentences, linking its canonical page inline.> |

</GlossaryFilter>
```

## Rules

- **Rows sort alphabetically by term, per language.** The Portuguese page alphabetizes by the Portuguese term; terms from the stay-in-English list keep their English form and sort by it.
- **A term is lowercase** unless it is a product name or another proper noun.
- **A definition is one to three sentences**, and the first says what the term is. Link the canonical page inline from the phrase it explains.
- **Every definition matches a page in the documentation.** The glossary records how the documentation uses a term; it never introduces one.
- **The glossary is a crosslinked structure.** Each definition links its canonical page inline and the pages where the reader meets the term. Every entry keeps a path back into the documentation.
- **Moving an entry never breaks a crosslink.** When an entry migrates to the Learning Center, every page that linked the entry gets the new destination in the same change.
- **Blank lines around the table inside the component are mandatory**, or the table renders as one literal paragraph.

## Examples

The first product glossary is the [Functions glossary](/en/documentation/platform/functions/glossary/): 22 terms, each definition linking its canonical page.

## Related

- [Information architecture](/en/documentation/style-guide/content/information-architecture.md): The slot the glossary fills in every product section.
- [Documentation terminology](/en/documentation/style-guide/writing/terminology.md): The naming rules the glossary never restates.
- [Components](/en/documentation/style-guide/components.md): The GlossaryFilter mechanics.
- [Concept pages](/en/documentation/style-guide/content/concept.md): Where a term goes when three sentences are not enough.