URL: /guides/authoring/glossary

---
title: "Glossary"
description: "Author terms once; auto-link them on every page."
icon: "book-marked"
---

# Glossary

Tangly auto-links glossary terms across your docs. Define a term once and every mention of it on every other page becomes a hover-tip with the definition and a click-through to the canonical entry.

There are two authoring forms — pick the one that fits your scale.

## Single-file form

Drop a `glossary.mdx` at the project root. Every `## H2` is one term; the body until the next H2 is the definition. The slug is the heading's GitHub-flavored slug.

```md
---
title: Glossary
glossary: false
---

# Glossary

## Capacity factor

The ratio of a generator's actual output over a period to its theoretical maximum
output if it had run at full nameplate capacity for the same period.

## Spot price

(aka pool price, market price)

The marginal clearing price for a single dispatch interval in the wholesale market.
```

`glossary: false` in the page's frontmatter is important — without it the glossary page would auto-link its own terms recursively.

Aliases are picked up two ways:

1. An explicit `**Aliases:** CF, load factor` line near the top of the body.
2. A `(aka X, Y)` parenthetical in the first paragraph.

## Per-term form

For larger glossaries, use a `glossary/` directory with one file per term. Each file is one entry; the filename (sans extension) is the slug.

```md
---
term: Capacity factor
aliases:
  - CF
  - load factor
---

The ratio of a generator's actual output over a period to its theoretical
maximum output if it had run at full nameplate capacity for the same period.
```

If both forms exist (`glossary.mdx` AND `glossary/`), the single-file form wins and Tangly logs a warning.

## How auto-linking works

A rehype plugin walks every page's HTML AST after Shiki has run (so code blocks are never touched). For each text node, it scans for term + alias matches and wraps the first occurrence per page in a `<GlossaryTerm>` component. Subsequent matches on the same page are left alone — the goal is a hint, not noise.

Pages can opt out with `glossary: false` in frontmatter (typical for the glossary page itself, the changelog, and any auto-generated reference).

## Tooltip excerpts

The hover-tip uses the first paragraph of the definition, trimmed to 200 characters. Click-through goes to `/<glossary-slug>#<term-slug>` (or the per-term file's route if you used the directory form).