Module

rendering.plugins.directives.glossary

Glossary directive for Bengal SSG.

Renders key terms from a centralized glossary data file as definition lists. Supports filtering by tags to show relevant terms for each page.

Syntax:

:::{glossary}
:tags: directives, navigation
:::

:::{glossary}
:tags: admonitions
:sorted: true
:collapsed: true
:limit: 3
:::

The directive loads terms from data/glossary.yaml (via site.data.glossary) and renders matching terms as a styled definition list.

Options:

  • tags: Comma-separated list of tags to filter terms (required)
  • sorted: Sort terms alphabetically (default: false)
  • show-tags: Display tag badges under each term (default: false)
  • collapsed: Wrap glossary in collapsible <details> element (default: false)
  • limit: Show only first N terms, with "Show all" to expand (default: all)
  • source: Custom glossary file path (default: data/glossary.yaml)

Architecture:

Data loading is deferred to the render phase where we have access to
renderer._site.data (pre-loaded by Site.__post_init__). This follows
where data files are accessible via site.data.*.
View source
1 Class 6 Functions

Classes

GlossaryDirective
Glossary directive using Mistune's fenced syntax. Syntax: :::{glossary} :tags: tag1, tag2 …
4

Glossary directive using Mistune's fenced syntax.

Syntax:

:::{glossary}
:tags: tag1, tag2
:sorted: true
:show-tags: true
:collapsed: true
:limit: 3
:::

Options:

  • tags: Comma-separated list of tags to filter terms (required)
  • sorted: Sort terms alphabetically (default: false, preserves file order)
  • show-tags: Display tag badges under each term (default: false)
  • collapsed: Wrap in collapsible <details> element (default: false)
  • limit: Show only first N terms with "Show all" expansion (default: all)
  • source: Custom glossary file path (default: data/glossary.yaml)

Architecture:

Parse phase records options only. Data loading is deferred to render
phase where renderer._site provides access to site.data and site.root_path.
Inherits from DirectivePlugin

Methods 1

parse
Parse glossary directive options. Note: Data loading is deferred to render pha…
3 dict[str, Any] 
def parse(self, block: Any, m: Match[str], state: Any) -> dict[str, Any]

Parse glossary directive options.

Note: Data loading is deferred to render phase where we have access to site.data via renderer._site.

Parameters 3
block Any

Block parser
m Match[str]

Regex match object
state Any

Parser state
Returns

dict[str, Any] —

Token dict with type 'glossary' containing options for render phase

Internal Methods 3
_parse_bool
Parse boolean option value.
1 bool 
def _parse_bool(self, value: str | bool) -> bool

Parse boolean option value.

Parameters 1
value str | bool
Returns

bool

_parse_int
Parse integer option value, returns 0 on invalid input.
1 int 
def _parse_int(self, value: str | int) -> int

Parse integer option value, returns 0 on invalid input.

Parameters 1
value str | int
Returns

int

__call__
Register the directive and renderer.
2 Any 
def __call__(self, directive: Any, md: Any) -> Any

Register the directive and renderer.

Parameters 2
directive Any
md Any
Returns

Any

Functions

render_glossary
Render glossary to HTML as a definition list. Data loading happens here (deferred from parse phase…
2 str 
def render_glossary(renderer: Any, text: str, **attrs: Any) -> str

Render glossary to HTML as a definition list.

Data loading happens here (deferred from parse phase) using:

  1. renderer._site.data.glossary (pre-loaded by Site from data/ directory)
  2. Fallback: file loading using renderer._site.root_path

Parameters 2

Name Type Default Description
renderer Any —

Mistune renderer (has _site attribute with site.data and root_path)
text str —

Rendered children content (unused for glossary) **attrs: Glossary attributes from directive (tags, sorted, etc.)

Returns

str —

HTML string for glossary definition list

_load_glossary_data
Load glossary data from site.data or file. Tries these sources in order: 1. site.data.glossary (if…
2 dict[str, Any] 
def _load_glossary_data(renderer: Any, source_path: str) -> dict[str, Any]

Load glossary data from site.data or file.

Tries these sources in order:

  1. site.data.glossary (if source is default data/glossary.yaml)
  2. File loading using site.root_path

Parameters 2

Name Type Default Description
renderer Any —

Mistune renderer with _site attribute
source_path str —

Path to glossary file (default: data/glossary.yaml)

Returns

dict[str, Any] —

Dict with 'terms' key, or 'error' key on failure

_filter_terms
Filter terms by tags. A term matches if it has ANY of the requested tags (OR logic).
2 list[dict[str, Any]] 
def _filter_terms(terms: list[dict[str, Any]], tags: list[str]) -> list[dict[str, Any]]

Filter terms by tags.

A term matches if it has ANY of the requested tags (OR logic).

Parameters 2

Name Type Default Description
terms list[dict[str, Any]] —

List of term dicts from glossary
tags list[str] —

List of tags to match

Returns

list[dict[str, Any]] —

List of matching terms

_render_term
Render a single glossary term as dt/dd pair.
3 str 
def _render_term(renderer: Any, term_data: dict[str, Any], show_tags: bool) -> str

Render a single glossary term as dt/dd pair.

Parameters 3

Name Type Default Description
renderer Any —
term_data dict[str, Any] —
show_tags bool —

Returns

str

_parse_inline_markdown
Parse inline markdown in glossary definitions. Tries to use mistune's inline parser first (proper …
2 str 
def _parse_inline_markdown(renderer: Any, text: str) -> str

Parse inline markdown in glossary definitions.

Tries to use mistune's inline parser first (proper way), falls back to simple regex for basic markdown if not available.

Parameters 2

Name Type Default Description
renderer Any —

Mistune renderer instance
text str —

Text to parse

Returns

str —

HTML string with inline markdown converted

_escape_html
Escape HTML special characters.
1 str 
def _escape_html(text: str) -> str

Escape HTML special characters.

Parameters 1

Name Type Default Description
text str —

Returns

str