glossary directive

[Mpdreamz]

Glossary

Kind	Link
Reference	https://mystmd.org/guide/directives#directive-glossary
Documentation	https://mystmd.org/guide/glossaries-and-terms

Implementation

• Parses directives and aliases
• Emits HTML
• Unit tests
• Validation (emits, warnings and errors).

Specification compliance:

• Arguments is parsed and required
• Body defines terms

[KOTungseth]

In-flight PR for automatically generated definition lists from YAML: kibana/pull/191787

I'm also including my own notes ⬇️

Purpose

Clarify technical terms: Definitions explain specialized, technical, or domain-specific terms that may not be familiar to all users. This helps bridge the gap between experts and less-experienced users, ensuring clarity and understanding.

Ensure consistency: Providing clear definitions ensures that terms are used consistently throughout the documentation, which reduces confusion and misinterpretation. This is especially important in technical documentation, where precision matters.

Support learning: Definitions support the learning process by introducing new or complex concepts in a clear, concise manner. They help users build a foundational understanding of the technology, process, or system being documented.

Enhance usability: By defining key terms directly in the documentation (e.g., through tooltips, glossaries, or inline explanations), users don’t have to leave the document to search for meanings, making the content more user-friendly and efficient.

Facilitate global understanding: Definitions help ensure that a wide range of users, including those from different technical backgrounds or language levels, can fully comprehend the material.

Reduce ambiguity: Definitions remove potential ambiguity, especially in cases where the same term might have different meanings in various contexts. They provide specific, context-driven explanations.

Best practices

Organize definitions logically: Group related definitions together in a logical order. This can be alphabetical, thematic, or based on usage within the documentation, making it easier for users to find what they need.

Include examples: Whenever possible, provide examples of how the term is used in context. This can help clarify the meaning and show practical applications of the defined term.

Avoid overloading definitions: Limit the number of definitions provided in a single section. Overloading users with too many terms at once can lead to confusion and hinder understanding.

[Mpdreamz]

Ahh that's a great resource @KOTungseth I was thinking of exposing that under our own custom directive e.g

```{settings} path/to/settings.yml
```

This glossary is as followed:

:::{glossary}
MyST
: An amazing markup language that supports glossaries
:::

You can use {term}`MyST` to create glossaries.

Where you can define definitions/abbreviations and refer to them later on with the {term}\TERM` role which would create a popover explanation.

Ideally we support this separately (if we want it at all) by including all availableterms for a dockset in dockset.yml

And use {settings} for the well understood format of rendering of externally provided/generated settings/properties?

[KOTungseth]

Let's dedicate the glossary directive to Elastic Glossary.

[theletterf]

+CC @jmikell821 you might want to follow up this one.

[cotti]

Codebase audit (2026-05-26)

Doing a sweep of the oldest open issues and checking whether they're still actionable. Sharing what I found here.

Current state in docs-builder

Feature	Status	Notes
Myst {glossary} directive	❌ Not implemented	No GlossaryBlock.cs; not registered in DirectiveBlockParser.cs; not in UnsupportedBlocks either, so it falls through to UnknownDirectiveBlock silently.
Myst {term} role	❌ Not implemented	No TermRole.cs in src/Elastic.Markdown/Myst/Roles/.
Generic Markdown definition lists (Term\n: Definition)	✅ Fully implemented	Markdig UseDefinitionLists() + custom DefinitionTermAnchorRenderer that adds id="..." + <a class="paramlink"> anchors for backtick-quoted terms. CSS at Assets/markdown/definition-list.css. Tests at tests/authoring/Container/DefinitionLists.fs.
{settings} directive (the alternate proposal from Mpdreamz in this thread)	✅ Fully implemented and tested	src/Elastic.Markdown/Myst/Directives/Settings/. Renders YAML settings as <dl> with anchors, deployment filters, applies_to badges, nested settings. Documented at docs/syntax/automated_settings.md.
Cross-page {term} resolution (link index)	❌ Not implemented	CrossLinkResolver handles pages + page-level anchors only.

What this means for the original asks

Checklist item	Status
Parses directives and aliases	❌
Emits HTML	❌ (for {glossary}; the generic DL emits HTML fine)
Unit tests	❌
Validation (emits, warnings and errors)	❌

But — re-reading the thread — Mpdreamz proposed splitting this into two: {settings} for external generated settings (now ✅ shipped) and {glossary} for term definitions/popovers. And KOTungseth said "Let's dedicate the glossary directive to [Elastic Glossary]," which today exists at reference/glossary as an ordinary markdown page using definition lists.

So the directive part is largely moot — there's already a curated glossary page, and the rendering substrate (definition lists with anchors) works. The piece that would still add authoring value is the {term} role for cross-page popovers — that's the bit that lets writers say "use the canonical definition here" without rewriting it everywhere.

Suggested narrow scope

Drop the {glossary} directive, ship {term} role only:

1. At build time, harvest <dt id="..."> from a designated glossary file (e.g. reference/glossary.md) into a term-index.json artifact alongside link-index.json.
2. {term}\name`role →name`.
3. Frontend <term-popover> web component (modeled on existing AppliesToPopover.tsx) shows the definition on hover/focus.
4. Validation: unresolved term → warning, errors in strict mode.

Lingering questions

1. Is the {term} popover UX actually wanted? — original Myst spec describes the role behavior, but Elastic has not historically used popovers for terms. Worth a UX/writer-team call before building.
2. One canonical glossary or many? — the existing reference/glossary is curated. Do we want per-content-set glossaries (e.g. Security has its own glossary), or always resolve to the global one?
3. Backward compatibility with definition list ids — DefinitionTermAnchorRenderer currently only emits an id for backtick-quoted terms. Should we extend it (or relax it) for terms intended for {term} reference? Or keep the backtick convention and document it as the indexing trigger?
4. Cross-repo terms — should {term} ever resolve into a different repo's content set (via the existing cross-link index), or strictly intra-build?

Recommendation

Either:

• Close as superseded — {settings} covered the original Mpdreamz use case; reference/glossary page covers the KOTungseth direction. The original 4-checkbox spec is no longer the right framing.
• Recast as {term} role only — file a new, smaller issue specifically for the popover role with the questions above answered.

Happy to drive either path.