# protocol
URL: /patitas/api/directives/protocol/
Section: directives
Description: 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('')
... sb.append(rendered_children)
... sb.append('
')
---
> For a complete page index, fetch /patitas/llms.txt.
Open LLM text
(/patitas/api/directives/protocol/index.txt)
Share with AI
Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fprotocol%2Findex.txt)
Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fprotocol%2Findex.txt)
Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fprotocol%2Findex.txt)
Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fprotocol%2Findex.txt)
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('')
... sb.append(rendered_children)
... sb.append('
')
```
3Classes
## Classes
`DirectiveHandler`
8
▼
Protocol for directive implementations.
Implement this protocol to create custom directives. The p…
Bases:
`Protocol`
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 (/patitas/api/directives/contracts/#DirectiveContract) | None]`
Optional nesting validation contract.
`options_class`
`ClassVar[type[Any]]`
Class for typed options parsing.
`preserves_raw_content`
`ClassVar[bool]`
—
`Example`
—
("note", "warning", "tip") for admonitions
#### Methods
`parse`
6
`Directive (/patitas/api/nodes/#Directive)[Any]`
▼
Build the directive AST node.
Called by the parser when a directive block is e…
`def parse(self, name: str, title: str | None, options: Any, content: str, children: Sequence[Block], location: SourceLocation) -> Directive[Any]`
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 (/patitas/api/nodes/#Directive)[Any]`
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[Any], 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…
Bases:
`Protocol`
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 (/patitas/api/directives/contracts/#DirectiveContract) | None]`
—
`options_class`
`ClassVar[type[Any]]`
—
#### Methods
`parse`
6
`Directive (/patitas/api/nodes/#Directive)[Any]`
▼
Build the directive AST node.
`def parse(self, name: str, title: str | None, options: Any, content: str, children: Sequence[Block], location: SourceLocation) -> Directive[Any]`
##### Parameters
Name
Type
Description
`name`
`—`
`title`
`—`
`options`
`—`
`content`
`—`
`children`
`—`
`location`
`—`
##### Returns
`Directive (/patitas/api/nodes/#Directive)[Any]`
`DirectiveRenderOnly`
3
▼
Protocol for directives that only need custom rendering.
Use this when default parsing is acceptab…
Bases:
`Protocol`
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[Any], rendered_children: str, sb: StringBuilder) -> None`
##### Parameters
Name
Type
Description
`node`
`—`
`rendered_children`
`—`
`sb`
`—`