Rules#

For a compact lookup table of preset membership, generated nodes, rule options, and streaming compatibility, see Rule matrix.

Rule Base Classes#

class wenmode.rules.Rule(name=None)#

Base class for parser rules.

Parameters:: name (str) – Stable rule name. Parser rule dictionaries are keyed by this value.

class wenmode.rules.BlockRule(name=None, pattern=None)#

Base class for block-level Markdown rules.

Parameters:: pattern (str) – Regular expression pattern used to detect block openers.

parse(parser, state, candidate)#

Parse a matched block candidate.

Implementations must advance state when they consume input. Returning a node without advancing state raises RuntimeError.

Parameters:

parser (Parser) – Active parser.
state (BlockState) – Current block state.
candidate (BlockCandidate) – Candidate line and match object from dispatch.

Returns:

Parsed node, or None if the rule declines the match.

Return type:

Node | None

class wenmode.rules.ContinueRule(name=None)#

Base class for rules that transform paragraph continuations.

match_candidate(line)#

Return a paragraph continuation candidate for line.

parse_paragraph_continuation(parser, state, lines, candidate)#

Parse a paragraph continuation candidate.

Returning None declines the continuation and must leave state unchanged. Returning a replacement node requires advancing state. Mutating state while declining, or returning a node without advancing state, raises RuntimeError.

Parameters:

parser (Parser) – Active parser.
state (BlockState) – Current block state positioned at the continuation line.
lines (list[str]) – Paragraph lines collected so far.
candidate (ContinueCandidate) – Candidate line and optional match from dispatch.

Returns:

Replacement node, or None to keep parsing the paragraph.

Return type:

Node | None

class wenmode.rules.InlineRule(name=None, pattern=None, opener=None)#

Base class for inline Markdown rules.

Parameters:

pattern (str | None) – Regular expression pattern used by this inline rule. Set this to None for trigger-only rules that implement parse() directly.
opener (str | tuple[str, ...]) – Optional single-character opener, or tuple of single-character openers, that can start the rule. Supplying openers lets the parser dispatch inline rules more efficiently; rule implementations remain responsible for checking any longer delimiter syntax.

parse(parser, text, candidate, state)#

Parse an inline node from candidate.

Parameters:

parser (Parser) – Active parser.
text (str) – Full inline source text.
candidate (InlineCandidate) – Candidate start and optional regex match from dispatch.
state (BlockState) – Current block state.

Returns:

A (node, end_index) pair. Return (None, candidate.start) to decline the match.

Return type:

tuple[Node | None, int]

class wenmode.rules.RootTransform#

Base class for document-wide transforms attached by rules.

Root transforms can collect definitions, defer inline parsing, and update the parsed root after block parsing completes.

prepare(parser, root, state)#

Prepare document-wide state before deferred inlines resolve.

transform(parser, root, state)#

Update the root after deferred inlines have resolved.

class wenmode.rules.NodeTransform#

Base class for per-node transforms attached by parser rules.

Node transforms run immediately after the owning block or continuation rule returns a node. Unlike root transforms, they do not require a complete root and can run during incremental parsing. They mutate the supplied node in place; they do not replace it.

transform(parser, node, state)#

Mutate the supplied node in place.

Block Rules#

class wenmode.rules.ThematicBreak(name=None, pattern=None)#

Parse thematic breaks such as ---, ***, and ___.

Markdown syntax:

---

class wenmode.rules.FencedCode(name=None, pattern=None)#

Parse fenced code blocks opened by backticks or tildes.

Markdown syntax:

```python
print(1)
```

class wenmode.rules.IndentedCode(name=None, pattern=None)#

Parse indented code blocks.

Markdown syntax:

print(1)

class wenmode.rules.HtmlBlock(disallowed_tags=())#

Parse CommonMark HTML block starts.

Markdown syntax:

<div>HTML</div>

Parameters:: disallowed_tags (Sequence[str]) – HTML tag names that should be escaped during parsing.

class wenmode.rules.List(task=False)#

Parse ordered and unordered lists.

Markdown syntax:

- item

Parameters:: task (bool) – Parse GFM task list markers when True.

class wenmode.rules.AtxHeading(transforms=())#

Parse hash-prefixed ATX headings.

Markdown syntax:

# Heading

Parameters:: transforms (Iterable[NodeTransform]) – Node transforms to run after parsing the heading.

class wenmode.rules.SetextHeading(transforms=())#

Parse setext headings from paragraph continuations.

Markdown syntax:

Heading
---

Parameters:: transforms (Iterable[NodeTransform]) – Node transforms to run after parsing the heading.

class wenmode.rules.Blockquote(name=None, pattern=None)#

Parse > block quote containers.

Markdown syntax:

> blockquote

class wenmode.rules.Table(require_body_pipe=True)#

Parse GFM pipe tables.

Markdown syntax:

| A | B |
| --- | --- |
| x | y |

class wenmode.rules.FootnoteDefinition(name=None, pattern=None)#

Parse footnote definition blocks.

Markdown syntax:

[^a]: Footnote text.

class wenmode.rules.LeafDirective(name=None, pattern=None)#

Parse mdast-style leaf directives such as ::name[label].

Markdown syntax:

::toc[On this page]{min=2 max=3}

class wenmode.rules.ContainerDirective(name=None, pattern=None)#

Parse mdast-style container directives fenced with colons.

Markdown syntax:

:::note[Title]
Body.
:::

class wenmode.rules.ReferenceDefinition(name=None, pattern=None)#

Parse link and image reference definitions.

Markdown syntax:

[label]: https://example.com "Title"

Inline Rules#

class wenmode.rules.BackslashEscape(name=None, pattern=None, opener=None)#

Parse backslash escapes for Markdown punctuation.

Markdown syntax:

\*

class wenmode.rules.CharacterReference(name=None, pattern=None, opener=None)#

Parse named and numeric character references.

Markdown syntax:

&copy;

class wenmode.rules.HardBreak(name=None, pattern=None, opener=None)#

Parse hard line breaks created with backslash or trailing spaces.

Markdown syntax:

line\
break

class wenmode.rules.Autolink(name=None, pattern=None, opener=None)#

Parse angle-bracket URI and email autolinks.

Markdown syntax:

<https://example.com>

class wenmode.rules.RawHtml(disallowed_tags=(), comment_style='commonmark')#

Parse inline raw HTML.

Markdown syntax:

<span>HTML</span>

Parameters:

disallowed_tags (Sequence[str]) – HTML tag names that should be escaped during parsing.
comment_style (Literal['commonmark', 'gfm']) – "commonmark" uses CommonMark 0.31-style inline comments. "gfm" uses the stricter GFM 0.29 comment grammar.

class wenmode.rules.Image(references=True)#

Parse inline and reference-style images.

Markdown syntax:

![alt](/image.png)

Parameters:: references (bool) – Enable reference-style images and reference definitions.

class wenmode.rules.Link(references=True)#

Parse inline and reference-style links.

Markdown syntax:

[label](https://example.com)

Parameters:: references (bool) – Enable reference-style links and reference definitions.

class wenmode.rules.InlineCode(name=None, pattern=None, opener=None)#

Parse inline code spans.

Markdown syntax:

`code`

class wenmode.rules.Emphasis(cjk_friendly=False)#

Parse emphasis and strong emphasis delimiters.

Markdown syntax:

*emphasis* and **strong**

class wenmode.rules.Strikethrough(name=None, pattern=None, opener=None)#

Parse deletion spans delimited by tildes.

Markdown syntax:

~~deleted~~

class wenmode.rules.ExtendedAutolink(cjk_friendly=False)#

Parse bare URL and email autolinks.

Markdown syntax:

https://example.com

class wenmode.rules.TextDirective(name=None, pattern=None, opener=None)#

Parse mdast-style text directives such as :name[label].

Markdown syntax:

:abbr[HTML]{title="HyperText Markup Language"}

class wenmode.rules.Footnote(name=None, pattern=None, opener=None)#

Parse footnote references and collect matching definitions.

Markdown syntax:

A note[^a].

[^a]: Footnote text.

Plugin Rules#

Non-standard syntax lives in wenmode.plugins. Each plugin module owns its node classes, parser rules, renderer handlers, and setup function. For usage, see Plugins.