Module

rendering.plugins.directives.example_label

Example label directive for Mistune.

Provides a lightweight semantic label for example sections - a "soft header" that doesn't appear in TOC and is lighter weight than a full admonition callout.

Use cases:

  • Example sections in documentation
  • Code example labels
  • Demo/sample section headers

Syntax:

:::{example-label} Basic Usage
:::

Content follows...

Renders as:

<p class="example-label" role="heading" aria-level="6">
  <span class="example-label-prefix">Example:</span> Basic Usage
</p>

Architecture:

Similar to rubric but purpose-built for examples with semantic styling.
View source
2 Classes 1 Function

Classes

ExampleLabelOptions dataclass
Options for example-label directive.
0

Options for example-label directive.

Inherits from DirectiveOptions

Attributes

Name Type Description
css_class str

Additional CSS classes
prefix str

Custom prefix text (default: "Example")
no_prefix bool

If true, don't show the prefix
_field_aliases ClassVar[dict[str, str]]
ExampleLabelDirective
Example label directive for lightweight example section headers. Syntax: :::{example-label} Ti…
2

Example label directive for lightweight example section headers.

Syntax:

:::{example-label} Title Text
:::

With options:

:::{example-label} API Usage
:prefix: Demo
:class: featured
:::

Creates a semantic label that looks like a soft header but doesn't appear in TOC. Lighter weight than admonition callouts, perfect for example sections.

Renders immediately with no content inside - any content is ignored.

Inherits from BengalDirective

Attributes

Name Type Description
NAMES ClassVar[list[str]]
TOKEN_TYPE ClassVar[str]
OPTIONS_CLASS ClassVar[type[DirectiveOptions]]
DIRECTIVE_NAMES ClassVar[list[str]]

Methods 2

parse_directive
Build example label token from parsed components. Example labels are label-onl…
5 DirectiveToken 
def parse_directive(self, title: str, options: ExampleLabelOptions, content: str, children: list[Any], state: Any) -> DirectiveToken

Build example label token from parsed components.

Example labels are label-only - children are always empty.

Parameters 5
title str
options ExampleLabelOptions
content str
children list[Any]
state Any
Returns

DirectiveToken

render
Render example label to HTML. Renders as a styled paragraph with role="heading…
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render example label to HTML.

Renders as a styled paragraph with role="heading" for accessibility. Uses aria-level="6" to not interfere with document outline (lower than rubric's 5).

Parameters 2
renderer Any
text str
Returns

str

Functions

render_example_label
Legacy render function for backward compatibility.
2 str 
def render_example_label(renderer: Any, text: str, **attrs: Any) -> str

Legacy render function for backward compatibility.

Parameters 2

Name Type Default Description
renderer Any —
text str —

Returns

str