# directives

URL: /patitas/api/directives/
Section: directives
Description: Directive system for Patitas.

Provides extensible block-level markup through the directive syntax:

:::{directive-name} optional title
:option-key: option value

Content goes here.
:::

Key components:
- DirectiveHandler: Protocol for custom directive implementations
- DirectiveOptions: Base class for typed option parsing
- DirectiveContract: Nesting validation rules
- DirectiveRegistry: Handler lookup and registration

Thread Safety:
All components are designed for thread-safety:
- Options are frozen dataclasses
- Contracts are frozen dataclasses
- Registry is immutable after creation
- Handlers must be stateless

Example:
    >>> from patitas.directives import DirectiveHandler, DirectiveOptions
    >>>
    >>> @dataclass(frozen=True, slots=True)
    ... class VideoOptions(DirectiveOptions):
    ...     width: int | None = None
    ...     autoplay: bool = False
    ...
    >>> class VideoDirective:
    ...     names = ("video",)
    ...     token_type = "video"
    ...     options_class = VideoOptions
    ...
    ...     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(f'<video src="{node.title}"></video>')

---

> For a complete page index, fetch /patitas/llms.txt.

Open LLM text
(/patitas/api/directives/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Findex.txt)

Module

#
`directives`

Directive system for Patitas.

Provides extensible block-level markup through the directive syntax:

optional title
Content goes here.

Key components:

- DirectiveHandler: Protocol for custom directive implementations

- DirectiveOptions: Base class for typed option parsing

- DirectiveContract: Nesting validation rules

- DirectiveRegistry: Handler lookup and registration

Thread Safety:

All components are designed for thread-safety:

- Options are frozen dataclasses

- Contracts are frozen dataclasses

- Registry is immutable after creation

- Handlers must be stateless

Example:

```
>>> from patitas.directives import DirectiveHandler, DirectiveOptions
>>>
>>> @dataclass(frozen=True, slots=True)
... class VideoOptions(DirectiveOptions):
...     width: int | None = None
...     autoplay: bool = False
...
>>> class VideoDirective:
...     names = ("video",)
...     token_type = "video"
...     options_class = VideoOptions
...
...     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(f'<video src="{node.title}"></video>')
```