Module

rendering.plugins.directives

Mistune directives package.

Provides all documentation directives (admonitions, tabs, dropdown, code-tabs) as a single factory function for easy registration with Mistune.

Also provides:

  • Directive caching for performance
  • Error handling and validation
  • KNOWN_DIRECTIVE_NAMES: Single source of truth for all registered directive names

Directive System v2:

  • BengalDirective: Base class for typed directives with contract validation
  • DirectiveToken: Typed AST token structure
  • DirectiveOptions: Typed option parsing with coercion
  • DirectiveContract: Nesting validation for parent-child relationships

See: plan/active/rfc-directive-system-v2.md for architecture details.

View source
2 Functions

Functions

get_known_directive_names
Derive known directive names from actual directive classes. This is the SINGLE SOURCE OF TRUTH. Do…
0 frozenset[str] 
def get_known_directive_names() -> frozenset[str]

Derive known directive names from actual directive classes.

This is the SINGLE SOURCE OF TRUTH. Do not maintain a separate list. Each directive class declares its names via the DIRECTIVE_NAMES class attribute.

Returns

frozenset[str] —

Frozenset of all registered directive names.

create_documentation_directives
Create documentation directives plugin for Mistune. Returns a function that can be passed to mistu…
0 Callable[[Any], None] 
def create_documentation_directives() -> Callable[[Any], None]

Create documentation directives plugin for Mistune.

Returns a function that can be passed to mistune.create_markdown(plugins=[...]).

Provides:

  • admonitions: note, tip, warning, danger, error, info, example, success
  • badge: MyST badge directive with custom CSS classes
  • tabs: Tabbed content with full markdown support
  • dropdown: Collapsible sections with markdown
  • code-tabs: Code examples in multiple languages
  • rubric: Pseudo-headings for API documentation (not in TOC)
  • list-table: MyST-style tables using nested lists (avoids pipe character issues)
  • checklist: Styled checklist containers for bullet lists and task lists
  • container: Generic wrapper div with CSS classes (like Sphinx container)
  • include: Include markdown files directly in content
  • literalinclude: Include code files as syntax-highlighted code blocks

Usage:

from bengal.rendering.plugins.directives import create_documentation_directives

md = mistune.create_markdown(
    plugins=[create_documentation_directives()]
)

Returns

Callable[[Any], None]