Installation

pip install wenmode

Run the CLI without installing it permanently:

uvx wenmode render --preset=github README.md
uvx wenmode ast --preset=github README.md

After installation, use either the console script or Python module entry point:

wenmode render README.md --preset=github
python -m wenmode ast README.md --positions

Quick start

from wenmode import Wenmode

wen = Wenmode()

text = '''
# Hello

This is **wenmode**.
'''
expected = '''
<h1>Hello</h1>
<p>This is <strong>wenmode</strong>.</p>
'''

html = wen.render(text)
assert html == expected.lstrip()

Use parse() when you need the mdast-compatible syntax tree:

from wenmode import Wenmode

wen = Wenmode()
text = 'A [link](https://example.com).'

tree = wen.parse(text)
ast = tree.to_ast()

assert ast == {
    'type': 'root',
    'children': [
        {
            'type': 'paragraph',
            'children': [
                {'type': 'text', 'value': 'A '},
                {
                    'type': 'link',
                    'children': [{'type': 'text', 'value': 'link'}],
                    'url': 'https://example.com',
                },
                {'type': 'text', 'value': '.'},
            ],
        }
    ],
}

Set positions=True to include source ranges for editor integration, diagnostics, or AST-based tooling:

from wenmode import Wenmode

wen = Wenmode(positions=True)
ast = wen.parse('A **bold**.\n').to_ast()

assert ast['children'][0] == {
    'type': 'paragraph',
    'position': {
        'start': {'line': 1, 'column': 1, 'offset': 0},
        'end': {'line': 2, 'column': 1, 'offset': 12}
    },
    'children': [
        {
            'type': 'text',
            'position': {
                'start': {'line': 1, 'column': 1, 'offset': 0},
                'end': {'line': 1, 'column': 3, 'offset': 2}
            },
            'value': 'A '
        },
        {
            'type': 'strong',
            'position': {
                'start': {'line': 1, 'column': 3, 'offset': 2},
                'end': {'line': 1, 'column': 11, 'offset': 10}
            },
            'children': [
                {
                    'type': 'text',
                    'position': {
                        'start': {'line': 1, 'column': 5, 'offset': 4},
                        'end': {'line': 1, 'column': 9, 'offset': 8}
                    },
                    'value': 'bold'
                }
            ]
        },
        {
            'type': 'text',
            'position': {
                'start': {'line': 1, 'column': 11, 'offset': 10},
                'end': {'line': 1, 'column': 12, 'offset': 11}
            },
            'value': '.'
        }
    ]
}

Pass a renderer when you need reStructuredText or AsciiDoc output:

from wenmode import AsciiDocRenderer, Wenmode

wen = Wenmode(renderer=AsciiDocRenderer())

text = '# Hello'
expected = '= Hello\n'

asciidoc = wen.render(text)
assert asciidoc == expected

Rules, presets, and plugins

Most applications start with a preset:

• commonmark, the default CommonMark-style rule set,

• github, for GitHub-flavored Markdown features such as tables and task lists,

• streaming, for incremental HTML output.

Rules are opt-in and composable. Wenmode() uses the commonmark preset by default. Pass an explicit rule list to define a custom Markdown dialect.

from wenmode import Wenmode
from wenmode.rules import AtxHeading, FencedCode, Image, InlineCode, Link

wen = Wenmode([AtxHeading, FencedCode, Link, Image, InlineCode])
text = '''
# h1

hi `code` **strong**
'''
expected = '''
<h1>h1</h1>
<p>hi <code>code</code> **strong**</p>
'''

assert wen.render(text) == expected.lstrip()

Because Emphasis is not enabled above, **strong** stays as text.

Use Parser directly when you only need an AST and want to choose rendering separately:

from wenmode import HTMLRenderer, Parser
from wenmode.presets import commonmark

parser = Parser(commonmark())
text = '# Hello'

tree = parser.parse(text)

html = HTMLRenderer().render(tree)

Use the github preset for GitHub-flavored Markdown features such as tables, task lists, strikethrough, extended autolinks, and footnotes:

from wenmode import Wenmode
from wenmode.presets import github

wen = Wenmode(github())

Use built-in plugins for non-standard syntax, document metadata, and rendering behavior such as front matter, math, definition lists, abbreviations, spoilers, ruby text, HTML smart punctuation, and extra inline formatting:

from wenmode import Wenmode
from wenmode.plugins import inline_math

wen = Wenmode(plugins=[inline_math])

assert wen.render('Inline $x + y$.\n') == (
    '<p>Inline <span class="math math-inline">x + y</span>.</p>\n'
)

Benchmark

Wenmode is designed so enabling more rules adds limited dispatch overhead. The benchmark script compares Markdown-to-HTML throughput across Wenmode and the libraries covered by the migration guides:

uv run --locked --group benchmark python scripts/benchmark.py --case all

wenmode-core uses CommonMark-style rules plus pipe tables. It allows raw HTML passthrough and disables URL sanitization to match the other HTML renderers. Mistune, Python-Markdown, markdown-it-py, and markdown2 enable table support. Marko uses its broader GFM helper. commonmark.py is a CommonMark-only baseline because it does not support pipe tables.

wenmode-all uses the github preset plus Wenmode’s built-in plugins, including front matter, math, definition lists, abbreviations, spoilers, ruby text, heading IDs, GitHub alerts, and additional inline formatting. The benchmark corpora use few of these extra rules. This target measures rule dispatch overhead, not equivalent syntax coverage.

All benchmark targets are created once before warmup and timed iterations, then reused for every render call. Python-Markdown resets the same reusable Markdown instance before each conversion.

Versions used in this snapshot:

Results from one local Python 3.12.9 run on an Apple M1 Pro (macOS arm64), using --case all --iterations 5 --warmup 2. Mean times cover the five timed iterations; MB/s uses the best time, and vs core compares mean times:

In this run, wenmode-core has the lowest mean time in every case. wenmode-all is faster than the other parsers on Rust Book and Pro Git; Mistune is faster than wenmode-all on the docs corpus.

Benchmark numbers depend on hardware, Python version, corpus, and parser configuration. See the full methodology in the Benchmarks documentation.

Streaming

Use the streaming preset to render HTML chunks before the complete document is parsed and rendered:

from wenmode import Wenmode
from wenmode.presets import streaming

wen = Wenmode(streaming())

text = '''
# Hello

A [link](/url).
'''

for chunk in wen.stream(text):
    send(chunk)

Pass the returned iterator to a streaming response in Django, Flask, FastAPI, or another framework. The streaming preset keeps tables, strikethrough, direct links, and direct images enabled. It excludes reference-style links, footnotes, and other deferred document-wide transforms.

Learn more

• Usage for the main APIs.

• Presets for choosing a rule set.

• Security for raw HTML and URL handling.

• Plugins for built-in extensions.

• Migration guides for moving from other Python Markdown parsers.