Module

rendering.plugins.directives.base

Base class for Bengal directives.

Provides BengalDirective as the foundation for all directive implementations, offering automatic registration, typed options, contract validation, and encapsulated rendering.

Architecture:

BengalDirective extends mistune's DirectivePlugin with:
  • Automatic directive and renderer registration via NAMES/TOKEN_TYPE
  • Typed option parsing via OPTIONS_CLASS
  • Nesting validation via CONTRACT
  • Template method pattern for parse flow
  • Encapsulated render method

Related:

  • bengal/rendering/plugins/directives/tokens.py: DirectiveToken
  • bengal/rendering/plugins/directives/options.py: DirectiveOptions
  • bengal/rendering/plugins/directives/contracts.py: DirectiveContract
  • RFC: plan/active/rfc-directive-system-v2.md
View source
1 Class

Classes

BengalDirective
Base class for Bengal directives with nesting validation. Provides: - Automatic directive and rend…
12

Base class for Bengal directives with nesting validation.

Provides:

  • Automatic directive and renderer registration
  • Typed option parsing via OPTIONS_CLASS
  • Contract validation for parent-child relationships
  • Shared utility methods (escape_html, build_class_string)
  • Consistent type hints and logging

Subclass Requirements:

NAMES: List of directive names to register (e.g., ["dropdown", "details"])
TOKEN_TYPE: Token type string for AST (e.g., "dropdown")
OPTIONS_CLASS: (optional) Typed options dataclass
CONTRACT: (optional) Nesting validation contract
parse_directive(): Build token from parsed components
render(): Render token to HTML
Inherits from DirectivePlugin

Attributes

Name Type Description
NAMES ClassVar[list[str]]
TOKEN_TYPE ClassVar[str]
OPTIONS_CLASS ClassVar[type[DirectiveOptions]]
CONTRACT ClassVar[DirectiveContract | None]

Methods 6

parse
Standard parse flow with contract validation. Validation steps: 1. Validate pa…
3 dict[str, Any] 
def parse(self, block: Any, m: Match[str], state: Any) -> dict[str, Any]

Standard parse flow with contract validation.

Validation steps:

  1. Validate parent context (if CONTRACT.requires_parent)
  2. Parse content and children
  3. Validate children (if CONTRACT.requires_children)

Override parse_directive() instead of this method for most cases. Override this method only if you need custom pre/post processing.

Parameters 3
block Any

Mistune block parser instance
m Match[str]

Regex match object from directive pattern
state Any

Parser state
Returns

dict[str, Any] —

Token dict for mistune AST

parse_directive
Build the token from parsed components. Override this method to implement dire…
5 DirectiveToken | di… 
def parse_directive(self, title: str, options: DirectiveOptions, content: str, children: list[Any], state: Any) -> DirectiveToken | dict[str, Any]

Build the token from parsed components.

Override this method to implement directive-specific logic.

Parameters 5
title str

Directive title (text after directive name)
options DirectiveOptions

Parsed and typed options
content str

Raw content string (rarely needed, use children)
children list[Any]

Parsed nested content tokens
state Any

Parser state (for accessing heading levels, etc.)
Returns

DirectiveToken | dict[str, Any] —

DirectiveToken or dict for AST

render
Render token to HTML.
2 str 
def render(self, renderer: Any, text: str, **attrs: Any) -> str

Render token to HTML.

Parameters 2
renderer Any

Mistune renderer instance
text str

Pre-rendered children HTML **attrs: Token attributes
Returns

str —

HTML string

escape_html staticmethod
Escape HTML special characters for use in attributes. Escapes: & < > " '
1 str 
def escape_html(text: str) -> str

Escape HTML special characters for use in attributes.

Escapes: & < > " '

Parameters 1
text str

Raw text to escape
Returns

str —

HTML-escaped text

build_class_string staticmethod
Build CSS class string from multiple class sources. Filters out empty strings …
0 str 
def build_class_string(*classes: str) -> str

Build CSS class string from multiple class sources.

Filters out empty strings and joins with space.

Returns

str —

Space-joined class string

bool_attr staticmethod
Return HTML boolean attribute string.
2 str 
def bool_attr(name: str, value: bool) -> str

Return HTML boolean attribute string.

Parameters 2
name str

Attribute name (e.g., "open")
value bool

Whether to include the attribute
Returns

str —

" name" if value is True, "" otherwise

Internal Methods 6
__init__
Initialize directive with logger.
0 None 
def __init__(self) -> None

Initialize directive with logger.

_get_parent_directive_type
Extract parent directive type from parser state. Mistune tracks directive nest…
1 str | None 
def _get_parent_directive_type(self, state: Any) -> str | None

Extract parent directive type from parser state.

Mistune tracks directive nesting in state. This method extracts the immediate parent directive type for contract validation.

Parameters 1
state Any

Parser state
Returns

str | None —

Parent directive type (e.g., "steps") or None if at root

_push_directive_stack
Push current directive onto the stack for child validation.
2 None 
def _push_directive_stack(self, state: Any, directive_type: str) -> None

Push current directive onto the stack for child validation.

Parameters 2
state Any

Parser state
directive_type str

Current directive type
_pop_directive_stack
Pop current directive from the stack.
1 None 
def _pop_directive_stack(self, state: Any) -> None

Pop current directive from the stack.

Parameters 1
state Any

Parser state
_get_source_location
Extract source file location from parser state.
1 str | None 
def _get_source_location(self, state: Any) -> str | None

Extract source file location from parser state.

Parameters 1
state Any

Parser state
Returns

str | None —

Location string like "content/guide.md:45" or None

__call__
Register directive names and renderer. Override only if you need custom regist…
2 None 
def __call__(self, directive: Any, md: Any) -> None

Register directive names and renderer.

Override only if you need custom registration logic (e.g., multiple token types like AdmonitionDirective).

Parameters 2
directive Any

Mistune directive registry
md Any

Mistune Markdown instance