Module

renderers.html

HTML renderer using StringBuilder pattern.

Renders typed AST to HTML with O(n) performance using StringBuilder.

Thread Safety:

All state is local to each render() call. Multiple threads can render concurrently without synchronization.

Single-Pass Heading Decoration: Heading IDs are generated during the AST walk, eliminating the need for regex-based post-processing. TOC data is collected during rendering.

2Classes2Functions

Classes

HeadingInfo 3 ▼
Heading metadata collected during rendering. Used to build TOC without post-render regex scanning.…

Heading metadata collected during rendering.

Used to build TOC without post-render regex scanning. Collected by HtmlRenderer during the AST walk.

Attributes

Name Type Description
level int —
text str —
slug str —
HtmlRenderer 21 ▼
Render AST to HTML using StringBuilder pattern. O(n) rendering using StringBuilder for string accu…

Render AST to HTML using StringBuilder pattern.

O(n) rendering using StringBuilder for string accumulation. All state is local to each render() call.

Usage:

>>> from patitas.parser import Parser
>>> parser = Parser()
>>> doc = parser.parse("# Hello **World**")
>>> renderer = HtmlRenderer()
>>> html = renderer.render(doc)
'<h1>Hello <strong>World</strong></h1>\n'

Thread Safety:

Multiple threads can render concurrently without synchronization.
Each call creates independent StringBuilder.

Methods

render 1 str ▼
Render document AST to HTML string. **Thread Safety:** Creates independent Str…
def render(self, node: Document) -> str

Render document AST to HTML string.

Thread Safety: Creates independent StringBuilder per call. Safe for concurrent execution.

Parameters
Name Type Description
node —

Document AST root
Returns
str HTML string
get_headings 0 list[HeadingInfo] ▼
Get heading info collected during last render.
def get_headings(self) -> list[HeadingInfo]
Returns
list[HeadingInfo] List of HeadingInfo from the last render() call. Empty if render() hasn't been called.
Internal Methods 19 ▼
__init__ 1 ▼
Initialize renderer.
def __init__(self, source: str = '') -> None
Parameters
Name Type Description
source —

Original source buffer for zero-copy extraction

Default:''
_render_block 2 ▼
Render a block node.
def _render_block(self, block: Block, sb: StringBuilder) -> None
Parameters
Name Type Description
block —
sb —
_render_heading 2 ▼
Render heading with ID for anchoring.
def _render_heading(self, heading: Heading, sb: StringBuilder) -> None
Parameters
Name Type Description
heading —
sb —
_render_paragraph 2 ▼
Render paragraph.
def _render_paragraph(self, para: Paragraph, sb: StringBuilder) -> None
Parameters
Name Type Description
para —
sb —
_render_fenced_code 2 ▼
Render fenced code block.
def _render_fenced_code(self, code: FencedCode, sb: StringBuilder) -> None
Parameters
Name Type Description
code —
sb —
_render_indented_code 2 ▼
Render indented code block.
def _render_indented_code(self, code: IndentedCode, sb: StringBuilder) -> None
Parameters
Name Type Description
code —
sb —
_render_blockquote 2 ▼
Render block quote.
def _render_blockquote(self, quote: BlockQuote, sb: StringBuilder) -> None
Parameters
Name Type Description
quote —
sb —
_render_list 2 ▼
Render ordered or unordered list.
def _render_list(self, lst: List, sb: StringBuilder) -> None
Parameters
Name Type Description
lst —
sb —
_render_list_item 3 ▼
Render list item. CommonMark: - Tight lists: Single paragraph items render as …
def _render_list_item(self, item: ListItem, sb: StringBuilder, tight: bool) -> None

Render list item.

CommonMark:

  • Tight lists: Single paragraph items render as text (no

    tags)

  • Loose lists: All paragraphs wrapped in

    tags

Parameters
Name Type Description
item —
sb —
tight —
_render_table 2 ▼
Render GFM-style table.
def _render_table(self, table: Table, sb: StringBuilder) -> None
Parameters
Name Type Description
table —
sb —
_render_table_row 4 ▼
Render table row.
def _render_table_row(self, row: TableRow, sb: StringBuilder, is_header: bool, alignments: tuple[str | None, ...]) -> None
Parameters
Name Type Description
row —
sb —
is_header —
alignments —
_render_math_block 2 ▼
Render block math.
def _render_math_block(self, math: MathBlock, sb: StringBuilder) -> None
Parameters
Name Type Description
math —
sb —
_render_directive 2 ▼
Render directive block. If a directive registry is configured and has a handle…
def _render_directive(self, directive: Directive[Any], sb: StringBuilder) -> None

Render directive block.

If a directive registry is configured and has a handler for this directive, use it. Otherwise, render as a generic container.

Parameters
Name Type Description
directive —
sb —
_render_inlines 2 ▼
Render a sequence of inline nodes.
def _render_inlines(self, inlines: tuple[Inline, ...], sb: StringBuilder) -> None
Parameters
Name Type Description
inlines —
sb —
_render_inline 2 ▼
Render an inline node.
def _render_inline(self, inline: Inline, sb: StringBuilder) -> None
Parameters
Name Type Description
inline —
sb —
_render_role 2 ▼
Render inline role.
def _render_role(self, role: Role, sb: StringBuilder) -> None
Parameters
Name Type Description
role —
sb —
_extract_text 1 str ▼
Extract plain text from inline nodes.
def _extract_text(self, inlines: tuple[Inline, ...]) -> str
Parameters
Name Type Description
inlines —
Returns
str
_collect_footnotes 1 ▼
Collect footnote definitions from document.
def _collect_footnotes(self, doc: Document) -> None
Parameters
Name Type Description
doc —
_render_footnotes_section 1 ▼
Render footnotes section at end of document.
def _render_footnotes_section(self, sb: StringBuilder) -> None
Parameters
Name Type Description
sb —

Functions

html_escape 1 str ▼
Escape HTML special characters. CommonMark-compliant: escapes , &, " but NOT s…
def html_escape(s: str) -> str

Escape HTML special characters.

CommonMark-compliant: escapes <, >, &, " but NOT single quotes. Python's html.escape() escapes ' to ' which CommonMark doesn't require.

Parameters
Name Type Description
s str
Returns
str
_encode_url 1 str ▼
Encode URL for CommonMark compliance. CommonMark requires: 1. Decode HTML enti…
def _encode_url(url: str) -> str

Encode URL for CommonMark compliance.

CommonMark requires:

  1. Decode HTML entities (e.g., ä → ä)
  2. Percent-encode special characters (spaces, backslashes, non-ASCII)

Returns URL safe for href attribute (still needs html_escape for quotes).

Parameters
Name Type Description
url str
Returns
str