Module

`parsing.backends.patitas.wrapper`

PatitasParser wrapper implementing BaseMarkdownParser.

Provides Bengal integration by implementing the BaseMarkdownParser interface. This allows Patitas to be used as a drop-in replacement for legacy parsers.

Usage:

parser = PatitasParser()
html = parser.parse("# Hello", {})

html, toc = parser.parse_with_toc("## Section 1

Section 2", {})

Thread Safety:

PatitasParser is thread-safe. Each parse() call creates independent parser/renderer instances with no shared state.

Classes

PatitasParser 14 ▼

Parser using Patitas library (modern Markdown parser). Provides: - O(n) guaranteed parsing (no reg…

Parser using Patitas library (modern Markdown parser).

Provides:

O(n) guaranteed parsing (no regex backtracking)
Thread-safe by design (immutable AST)
Typed AST with frozen dataclasses
StringBuilder O(n) rendering

Supported features:

ATX/setext headings
Fenced/indented code blocks
Block quotes
Lists (ordered/unordered)
Thematic breaks
Emphasis/strong
Links/images
Inline code
Hard/soft breaks
Raw HTML

Supported features (via plugins):

Tables (GFM)
Strikethrough
Task lists
Math (inline and block)
Cross-references ([[link]] syntax)

Attributes

Name	Type	Description
`DEFAULT_PLUGINS`	`ClassVar[list[str]]`	—

Methods

supports_ast 0 bool ▼

Check if this parser supports true AST output.

property

def supports_ast(self) -> bool

Returns

bool True - Patitas natively supports typed AST output

parse 2 str ▼

Parse Markdown content into HTML.

def parse(self, content: str, metadata: dict[str, Any]) -> str

Parameters

Name	Type	Description
`content`	`—`	Markdown content to parse
`metadata`	`—`	Page metadata (used for cross-reference context)

Returns

str Rendered HTML string

parse_with_toc 2 tuple[str, str, str, str] ▼

Parse Markdown content and extract table of contents, excerpt, and meta descrip…

def parse_with_toc(self, content: str, metadata: dict[str, Any]) -> tuple[str, str, str, str]

Parse Markdown content and extract table of contents, excerpt, and meta description.

Uses single-pass heading decoration (RFC: rfc-path-to-200-pgs). Heading IDs and TOC are generated during the AST walk - no regex post-pass. Excerpt and meta description are extracted from AST for structurally correct plain text.

Parameters

Name	Type	Description
`content`	`—`	Markdown content to parse
`metadata`	`—`	Page metadata (includes source path for cross-reference context)

Returns

tuple[str, str, str, str] Tuple of (HTML with heading IDs, TOC HTML, excerpt, meta_description)

parse_with_context 3 str ▼

Parse Markdown with variable substitution support. Enables {{ page.title }}, {…

def parse_with_context(self, content: str, metadata: dict[str, Any], context: dict[str, Any]) -> str

Parse Markdown with variable substitution support.

Enables {{ page.title }}, {{ site.baseurl }}, etc. in markdown content. Uses VariableSubstitutionPlugin for preprocessing and restoration.

Parameters

Name	Type	Description
`content`	`—`	Markdown content to parse
`metadata`	`—`	Page metadata
`context`	`—`	Variable context (page, site, config)

Returns

str Rendered HTML with variables substituted

parse_with_toc_and_context 3 tuple[str, str, str, str] ▼

Parse Markdown with variable substitution and extract TOC, excerpt, and meta de…

def parse_with_toc_and_context(self, content: str, metadata: dict[str, Any], context: dict[str, Any]) -> tuple[str, str, str, str]

Parse Markdown with variable substitution and extract TOC, excerpt, and meta description.

Parameters

Name	Type	Description
`content`	`—`	Markdown content to parse
`metadata`	`—`	Page metadata
`context`	`—`	Variable context (page, site, config)

Returns

tuple[str, str, str, str] Tuple of (HTML with heading IDs, TOC HTML, excerpt, meta_description)

parse_to_ast 2 list[dict[str, Any]] ▼

Parse Markdown content to AST tokens. Note: Returns dict representation for co…

def parse_to_ast(self, content: str, metadata: dict[str, Any]) -> list[dict[str, Any]]

Parse Markdown content to AST tokens.

Note: Returns dict representation for compatibility with BaseMarkdownParser. Use patitas.parse_to_ast() directly for typed AST.

Parameters

Name	Type	Description
`content`	`—`	Raw Markdown content
`metadata`	`—`	Page metadata (unused)

Returns

list[dict[str, Any]] List of AST token dictionaries

parse_to_document 2 Document ▼

Parse Markdown content to typed Document AST. Returns Document for serializati…

def parse_to_document(self, content: str, metadata: dict[str, Any]) -> Document

Parse Markdown content to typed Document AST.

Returns Document for serialization via patitas.to_dict(doc). Used when persist_tokens is enabled for canonical AST cache format.

Parameters

Name	Type	Description
`content`	`—`	Raw Markdown content
`metadata`	`—`	Page metadata (unused)

Returns

Document Document AST

render_ast 1 str ▼

Render AST tokens to HTML.

def render_ast(self, ast: list[dict[str, Any]]) -> str

Parameters

Name	Type	Description
`ast`	`—`	List of AST token dictionaries

Returns

str Rendered HTML string

render_ast_from_dict 4 tuple[str, str] | None ▼

Render Patitas Document dict to HTML and TOC. Fallback when cached HTML is mis…

def render_ast_from_dict(self, ast_dict: dict[str, Any], source: str, *, page: Any = None, site: Any = None) -> tuple[str, str] | None

Render Patitas Document dict to HTML and TOC.

Fallback when cached HTML is missing; requires patitas>=0.2.0.

Parameters

Name	Type	Description
`ast_dict`	`—`	Serialized Document from patitas.to_dict(doc)
`source`	`—`	Original source buffer (required for ZCLH)
`page`	`—`	Page for directive context (optional) Default:`None`
`site`	`—`	Site for xref_index (optional) Default:`None`

Returns

tuple[str, str] | None (html, toc) or None if not supported (patitas < 0.2.0 or invalid format)

enable_cross_references 4 ▼

Enable cross-reference support with [[link]] syntax. Should be called after co…

def enable_cross_references(self, xref_index: dict[str, Any], version_config: Any | None = None, cross_version_tracker: Any | None = None, external_ref_resolver: Any | None = None) -> None

Enable cross-reference support with [[link]] syntax.

Should be called after content discovery when xref_index is built. Creates CrossReferencePlugin for post-processing HTML output.

Performance: O(1) - just stores reference to index Thread-safe: Each parser instance needs this called once

Parameters

Name	Type	Description
`xref_index`	`—`	Pre-built cross-reference index from site discovery
`version_config`	`—`	Optional versioning configuration for cross-version links Default:`None`
`cross_version_tracker`	`—`	Optional callback for tracking cross-version link dependencies. Called with (source_page, target_version, target_path) when a [[v2:path]] link is resolved. Default:`None`
`external_ref_resolver`	`—`	Optional resolver for [[ext:project:target]] syntax. Default:`None`

Internal Methods 3 ▼

__init__ 2 ▼

Initialize the Patitas parser.

def __init__(self, enable_highlighting: bool = True, plugins: list[str] | None = None) -> None

Parameters

Name	Type	Description
`enable_highlighting`	`—`	Enable syntax highlighting for code blocks Default:`True`
`plugins`	`—`	List of plugins to enable. Defaults to standard set: table, strikethrough, task_lists, math Default:`None`

_apply_post_processing 2 str ▼

Apply common post-processing to HTML output.

def _apply_post_processing(self, html: str, metadata: dict[str, Any]) -> str

Parameters

Name	Type	Description
`html`	`—`
`metadata`	`—`

Returns

str

_node_to_dict 1 dict[str, Any] ▼

Convert AST node to dictionary representation.

def _node_to_dict(self, node: Block) -> dict[str, Any]

Parameters

Name	Type	Description
`node`	`—`	Block node

Returns

dict[str, Any] Dictionary representation