Helper Modules

Presets

Heading Helpers

class wenmode.headings.Slugger

Generate unique slug IDs for headings.

slug(value)

Return a unique slug for a heading title.

use(value)

Mark an existing slug as already used.

wenmode.headings.add_heading_ids(node, *, slugger, min_depth=1, max_depth=6, overwrite=False)

Add generated IDs to heading nodes in a tree.

Existing heading IDs are preserved unless overwrite is True.

Parameters:

  • node (Node) – Root or subtree to update.

  • slugger (Slugger) – Slug generator used to create unique IDs.

  • min_depth (int) – Minimum heading depth to update.

  • max_depth (int) – Maximum heading depth to update.

  • overwrite (bool) – Whether to replace existing heading IDs.

wenmode.headings.iter_headings(node)

Return all heading nodes under a node.

wenmode.headings.collect_headings(node, headings)

Append heading descendants of node to headings.

wenmode.headings.plain_text(nodes)

Return the plain text content of a node list.

wenmode.headings.plain_text_node(node)

Return the plain text content of one node.

wenmode.headings.slugify(value)

Convert text into a URL-friendly slug.

Table of Contents Helpers

class wenmode.toc.TocItem(id, title, depth, children=<factory>)

One table-of-contents entry.

wenmode.toc.collect_toc(node, *, min_depth=1, max_depth=6)

Collect heading nodes with IDs into a nested table of contents.

Parameters:

  • node (Node) – Root or subtree to inspect.

  • min_depth (int) – Minimum heading depth to include.

  • max_depth (int) – Maximum heading depth to include.

Returns:

Nested table-of-contents items.

Return type:

list[TocItem]

wenmode.toc.render_toc_html(items, *, label='Table of contents')

Render table-of-contents items as an HTML nav element.

Parameters:

  • items (list[TocItem]) – Items returned by collect_toc().

  • label (str) – Accessible label for the navigation element.

Returns:

HTML string, or an empty string when items is empty.

Return type:

str

wenmode.toc.render_toc_list(items)

Render table-of-contents items as a nested ordered list.

Extension State

class wenmode.state.StateKey(name, factory)

Typed key for per-parse extension state.

Rules and transforms should use StateKey instead of storing mutable per-document data on rule instances.

Parameters:

  • name (str) – Unique key name. Use a package-qualified name to avoid collisions.

  • factory (Callable[[], T]) – Callable that creates the initial value for each parse.

class wenmode.state.StateStore

Per-parse storage for extension state.

get(key)

Return the value for a key, creating it if necessary.

Parameters:

key (StateKey[T]) – State key to read.

Returns:

Stored value for this parse.

Return type:

T

class wenmode.state.StreamLineBuffer(source)

Lazy line buffer for iterable Markdown sources.

has(index)

Return whether a line index can be read.

get(index)

Return a buffered line by absolute index.

class wenmode.state.BlockState(lines, index=0, store=<factory>, depth=0, pending_inlines=<factory>, pending_inline_callbacks=<factory>, defer_inlines=False)

Mutable state for one block parse.

Custom block and continuation rules receive this object and should advance it when they consume input.

Parameters:

  • lines (list[str]) – Source lines for this block parse.

  • index (int) – Current line index.

  • store (StateStore) – Per-parse extension state store.

  • depth (int) – Container nesting depth.

  • pending_inlines (list[tuple[list[Node], str]]) – Deferred inline parse targets.

  • pending_inline_callbacks (list[Callable[[], None]]) – Callbacks to run after deferred inline parsing is resolved.

  • defer_inlines (bool) – Whether inline parsing is currently deferred.

property done: bool

Whether the state has consumed all available lines.

property line: str

Current source line.

advance(count=1)

Advance the current line index.

Parameters:

count (int) – Number of lines to consume.

has(offset=0)

Return whether a line exists at an offset from the current index.

peek(offset=0)

Return a line at an offset from the current index.

has_index(index)

Return whether an absolute line index is available.

line_at(index)

Return a line by absolute index.

first_nonblank_from_current()

Return the next nonblank line at or after the current index.

class wenmode.state.StreamBlockState(line_buffer, index=0, store=None, depth=0, pending_inlines=None, pending_inline_callbacks=None, defer_inlines=False)

Block state backed by a lazy StreamLineBuffer.

property done: bool

Whether the state has consumed all available lines.

property line: str

Current source line.

has(offset=0)

Return whether a line exists at an offset from the current index.

peek(offset=0)

Return a line at an offset from the current index.

has_index(index)

Return whether an absolute line index is available.

line_at(index)

Return a line by absolute index.

first_nonblank_from_current()

Return the next nonblank line at or after the current index.