# Custom Directives
URL: /bengal/docs/0.4.3/extending/custom-directives/
Section: extending
Description: Create custom MyST directive blocks for specialized content
---
> For a complete page index, fetch /bengal/llms.txt.
Directives are block-level content elements that extend Markdown with custom rendering. Bengal uses MyST-style syntax (`:::{name}`) and provides a structural `DirectiveHandler` protocol for creating your own directives.
The public API lives in `bengal.parsing.backends.patitas.directives`. There is no `bengal.directives` package — import from the path shown in every example below.
## Shortcodes vs Directives
| Use | Shortcode | Directive |
|-----|-----------|-----------|
| **When** | Simple HTML, no validation | Validation, nesting, complex logic |
| **How** | Template file in `templates/shortcodes/` | Python class |
| **Syntax** | `{{< name args >}}` | `:::{name}` |
Use a **shortcode** when output is simple HTML from args and you want template authors to add or customize without code. Use a **directive** when you need validation (e.g., YouTube 11-char ID), parent-child nesting, or structured errors.
See [Template Shortcodes](../shortcodes/) for the template-only path.
## Directive Basics
Directives in Bengal:
- Parse content using the MyST fenced syntax
- Support typed options with automatic coercion (frozen dataclasses)
- Can define parent-child nesting relationships via contracts
- Are registered through a `DirectiveRegistryBuilder`
A directive is a **stateless handler** that implements the `DirectiveHandler`
protocol. It is *structural* typing — you do not subclass anything. A handler
declares two class attributes and two methods:
- `names: tuple[str, ...]` — directive names this handler responds to.
- `token_type: str` — token type identifier used for AST dispatch.
- `parse(self, name, title, options, content, children, location)` — builds a
`Directive` AST node.
- `render(self, node, rendered_children, sb)` — **appends** HTML to a
`StringBuilder`. It returns `None`; it does not return a string.
:::{warning} Handlers must be stateless
Multiple threads may call the same handler instance concurrently. Keep all
state in the (immutable) AST node or in the method arguments. Options are
**frozen dataclasses**, so read them with attribute access (`options.width`),
never mutate them.
:::
## Creating a Custom Directive
Implement the `DirectiveHandler` protocol:
```python
from typing import ClassVar
from patitas.nodes import Directive
class AlertDirective:
"""Custom alert box directive."""
# Required: names that trigger this directive
names: ClassVar[tuple[str, ...]] = ("alert", "callout")
# Required: token type for the AST
token_type: ClassVar[str] = "alert"
def parse(self, name, title, options, content, children, location):
"""Build the directive AST node."""
return Directive(
location=location,
name=name,
title=title or "info",
options=options,
children=tuple(children),
)
def render(self, node, rendered_children, sb):
"""Append HTML to the StringBuilder (returns None)."""
level = node.title or "info"
sb.append(f'')
sb.append(rendered_children)
sb.append("
")
```
Usage in Markdown:
```markdown
:::{alert} warning
:class: my-custom-class
This is a warning message.
:::
```
## Handler Attributes
### names (Required)
A tuple of directive names that trigger this handler:
```python
from typing import ClassVar
class DropdownHandler:
names: ClassVar[tuple[str, ...]] = ("dropdown", "details", "collapsible")
```
All names map to the same handler instance.
### token_type (Required)
String identifier for the AST node, used to match the parse and render phases:
```python
from typing import ClassVar
class DropdownHandler:
names: ClassVar[tuple[str, ...]] = ("dropdown",)
token_type: ClassVar[str] = "dropdown"
```
### options_class (Optional)
A frozen-dataclass subclass of `DirectiveOptions` for typed option parsing.
Options are parsed from `:key: value` lines and coerced to the field's type
automatically:
```python
from dataclasses import dataclass
from typing import ClassVar
from patitas.nodes import Directive
from bengal.parsing.backends.patitas.directives import DirectiveOptions
@dataclass(frozen=True, slots=True)
class DropdownOptions(DirectiveOptions):
open: bool = False
icon: str | None = None
class DropdownHandler:
names: ClassVar[tuple[str, ...]] = ("dropdown",)
token_type: ClassVar[str] = "dropdown"
options_class: ClassVar[type[DropdownOptions]] = DropdownOptions
def parse(self, name, title, options, content, children, location):
# options is a DropdownOptions instance (frozen — read, don't mutate)
return Directive(
location=location,
name=name,
title=title or "Details",
options=options,
children=tuple(children),
)
def render(self, node, rendered_children, sb):
is_open = " open" if node.options.open else ""
sb.append(f"")
sb.append(f"{node.title}")
sb.append(rendered_children)
sb.append("")
```
`DirectiveOptions` also ships with reusable bases such as `StyledOptions`
(adds `class_` and `name`) and typed option classes for the built-ins
(`AdmonitionOptions`, `FigureOptions`, `TabSetOptions`, and more).
### contract (Optional)
Define valid parent-child nesting relationships with `DirectiveContract`:
```python
from typing import ClassVar
from bengal.parsing.backends.patitas.directives import DirectiveContract
class StepHandler:
names: ClassVar[tuple[str, ...]] = ("step",)
token_type: ClassVar[str] = "step"
contract: ClassVar[DirectiveContract] = DirectiveContract(
allows_parent=("steps",),
)
```
This ensures `:::{step}` is only valid inside `:::{steps}`. A
`ContractViolation` is raised when nesting rules are broken.
## Methods to Implement
### parse
Build the `Directive` AST node from the parsed components. The node fields are
`location`, `name`, `title`, `options`, `children`, and an optional
`raw_content`:
```python
from patitas.nodes import Directive
def parse(self, name, title, options, content, children, location):
return Directive(
location=location, # SourceLocation for error messages
name=name, # The directive name actually used
title=title, # Optional text after the directive name
options=options, # Typed options (frozen dataclass)
children=tuple(children), # Parsed child blocks
)
```
### render
Append HTML to the `StringBuilder`. `render()` returns `None` — write output
with `sb.append(...)` (or `sb.append_line(...)`), do not build and return a
string:
```python
def render(self, node, rendered_children, sb):
sb.append(f"{node.title}
")
sb.append(rendered_children) # pre-rendered HTML of child blocks
sb.append("Test content
", sb)
html = sb.build()
assert 'class="alert alert-warning"' in html
assert "Test content
" in html
```
For full parse-and-render integration, use the public `PatitasParser`. It wires
up the directive registry (including typed option parsing) the same way a real
build does:
```python
from bengal.parsing.backends.patitas import PatitasParser
def test_directive_full_integration():
parser = PatitasParser()
source = """:::{note}
This is a note.
:::"""
html = parser.parse(source, metadata={})
assert "admonition" in html
assert "note" in html
```
To register your own handlers for the parse, build a registry and drive the
lower-level parse/render contexts directly:
```python
from bengal.parsing.backends.patitas import (
ParseConfig,
RenderConfig,
parse_config_context,
render_config_context,
)
from bengal.parsing.backends.patitas.directives import create_default_registry
```
To look up a built-in handler, query the registry rather than a global getter:
```python
from bengal.parsing.backends.patitas.directives import create_default_registry
def test_dropdown_handler_is_registered():
registry = create_default_registry()
handler = registry.get("dropdown")
assert handler is not None
```
## Related
- [Directives Reference](/docs/reference/directives/) for built-in directives
- [Build Pipeline](/docs/reference/architecture/core/pipeline/) for understanding when directives are processed