Module

directives.protocol

DirectiveHandler protocol for extensible block-level directives.

Directives are the primary extension mechanism for block-level markup. Implement the DirectiveHandler protocol to create custom directives.

Thread Safety:

Handlers must be stateless. All state should be in the AST node or passed as arguments. Multiple threads may call the same handler instance concurrently.

Example:

>>> class NoteDirective:
...     names = ("note",)
...
...     def parse(self, name, title, options, content, children, location):
...         return Directive(location, name, title, options, children)
...
...     def render(self, node, rendered_children, sb):
...         sb.append('<div class="admonition note">')
...         sb.append(rendered_children)
...         sb.append('</div>')
3Classes

Classes

DirectiveHandler 8 ▼
Protocol for directive implementations. Implement this protocol to create custom directives. The p…

Protocol for directive implementations.

Implement this protocol to create custom directives. The parser calls parse() to build the AST node, and the renderer calls render() to produce HTML output.

Thread Safety: Handlers must be stateless. All mutable state must be in the AST node (which is immutable) or passed as arguments. Multiple threads may call the same handler instance concurrently.

Attributes

Name Type Description
names ClassVar[tuple[str, ...]]

Tuple of directive names this handler responds to.
token_type ClassVar[str]

Token type identifier for the AST. Used for dispatch.
contract ClassVar[DirectiveContract | None]

Optional nesting validation contract.
options_class ClassVar[type[DirectiveOptions]]

Class for typed options parsing.
preserves_raw_content ClassVar[bool] —
Example —

("note", "warning", "tip") for admonitions

Methods

parse 6 Directive ▼
Build the directive AST node. Called by the parser when a directive block is e…
def parse(self, name: str, title: str | None, options: DirectiveOptions, content: str, children: Sequence[Block], location: SourceLocation) -> Directive

Build the directive AST node.

Called by the parser when a directive block is encountered. Return a Directive node to include in the AST.

Thread Safety: This method is called from parser context. Must not modify any shared state.

Parameters
Name Type Description
name —

The directive name used (e.g., "note" or "warning")
title —

Optional title text after the directive name
options —

Typed options parsed from :key: value lines
content —

Raw content string (prefer children for most cases)
children —

Parsed child nodes from the directive body
location —

Source location for error messages
Returns
Directive A Directive node for the AST
render 3 ▼
Render the directive to HTML. Called by the renderer when a Directive node is …
def render(self, node: Directive, rendered_children: str, sb: StringBuilder) -> None

Render the directive to HTML.

Called by the renderer when a Directive node is encountered. Append HTML output to the StringBuilder.

Thread Safety: This method may be called concurrently from multiple threads. Must not modify any shared state.

Parameters
Name Type Description
node —

The Directive AST node to render
rendered_children —

Pre-rendered HTML of child nodes
sb —

StringBuilder to append output to
DirectiveParseOnly 5 ▼
Protocol for directives that only need custom parsing. Use this when default rendering is acceptab…

Protocol for directives that only need custom parsing.

Use this when default rendering is acceptable but you need custom AST construction.

Attributes

Name Type Description
names ClassVar[tuple[str, ...]] —
token_type ClassVar[str] —
contract ClassVar[DirectiveContract | None] —
options_class ClassVar[type[DirectiveOptions]] —

Methods

parse 6 Directive ▼
Build the directive AST node.
def parse(self, name: str, title: str | None, options: DirectiveOptions, content: str, children: Sequence[Block], location: SourceLocation) -> Directive
Parameters
Name Type Description
name —
title —
options —
content —
children —
location —
Returns
Directive
DirectiveRenderOnly 3 ▼
Protocol for directives that only need custom rendering. Use this when default parsing is acceptab…

Protocol for directives that only need custom rendering.

Use this when default parsing is acceptable but you need custom HTML output.

Attributes

Name Type Description
names ClassVar[tuple[str, ...]] —
token_type ClassVar[str] —

Methods

render 3 ▼
Render the directive to HTML.
def render(self, node: Directive, rendered_children: str, sb: StringBuilder) -> None
Parameters
Name Type Description
node —
rendered_children —
sb —