Description
The Contextual Documentation Glossary turns specialized Docs rows into definitions available at the moment a reader encounters an unfamiliar term. Rows authored with kind: glossary remain normal, navigable documentation pages, but their titles also become a glossary roster for the document renderer. The first matching occurrence of each term in every H2-delimited section receives an inline trigger; hovering, focusing, or clicking opens a definition card sourced from that glossary row’s exported summary.
The transformation happens during rendering, so source Markdown and agent envelopes remain free of custom annotation tokens. Matching prefers longer terms, respects word boundaries, skips headings, code, links, buttons, and already-marked content, and never marks a glossary page with its own term. Definition artifacts load lazily on first use and cache for the browser session. Every popover identifies the Docs Dotabase as its source and links to the full glossary page.
Selling Points
- Explains product vocabulary in place, reducing context switching for readers new to Dots.
- Keeps definitions centrally authored as real Docs rows instead of duplicating tooltip copy across pages.
- Preserves clean Markdown and agent-readable envelopes because inline marking is a presentation pass.
- Supports mouse, keyboard focus, and click interaction while giving every definition a durable full-page destination.
- Avoids overwhelming prose by marking only the first occurrence per section and excluding code, headings, and links.
User Story
A new user reads a guide that mentions a DOT and an edge before they understand either term. They focus the dotted DOT label, read the short definition sourced from the glossary row, and continue without losing their place. When they need more depth, they choose “Open page” from the card and arrive at the complete glossary entry with its own graph relationships and navigation.
Extension Surface
This feature is configurable through Docs content. An author creates a valid page with kind: glossary under apps/docs/pipeline/frontmatter.ts; apps/docs/src/pages/DocPage.tsx supplies the resulting corpus terms to the Markdown renderer, and apps/docs/src/components/doc/markdown/rehype-glossary.ts marks eligible occurrences automatically. No code is needed for a new term or definition. Matching policy, section budget, and popover behavior are fixed and have no external plugin contract.
Capabilities & Limits
- Builds the term roster from published glossary rows and injects inline triggers without altering authored Markdown.
- Loads definitions lazily from each glossary page’s summary, caches successful reads, and links to the full source page.
- Handles hover, focus, click, delayed dismissal, viewport positioning, and retry after a failed definition fetch.
- Limit: matching is title-based literal text matching, not stemming, alias expansion, or semantic entity recognition.
- Limit: definitions are only available for glossary rows in the current exported corpus; a missing artifact produces an honest error.
Implementation Map
apps/docs/src/components/doc/markdown/rehype-glossary.tsapps/docs/src/components/doc/markdown/GlossaryTerm.tsxapps/docs/src/components/doc/markdown/glossary-defs.tsapps/docs/src/components/doc/markdown/DocMarkdown.tsxapps/docs/pipeline/frontmatter.tsglossary