Migrating from commonmark.py

Move CommonMark-only rendering and AST workflows from commonmark.py to Wenmode’s CommonMark-style preset, optional GFM rules, and plugins.

---

commonmark.py targets the CommonMark specification. Wenmode’s default Wenmode() path is also CommonMark-oriented, while making it possible to add GFM and Wenmode plugins later.

Simple rendering

commonmark.py commonly renders HTML with:

commonmark.py

import commonmark

html = commonmark.commonmark(text)

Use Wenmode:

wenmode

from wenmode import Wenmode

html = Wenmode().render(text)

Parser and renderer separately

If your commonmark.py integration separated parsing and rendering, mirror that shape with Parser and HTMLRenderer.

commonmark.py

import commonmark

parser = commonmark.Parser()
renderer = commonmark.HtmlRenderer()

root = parser.parse(text)
html = renderer.render(root)

wenmode

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

parser = Parser(commonmark)
root = parser.parse(text)
html = HTMLRenderer().render(root)

AST migration

commonmark.py AST objects and Wenmode nodes are different. Migrate to to_ast() when you need plain data.

commonmark.py

import commonmark

root = commonmark.Parser().parse(text)

wenmode

from wenmode import Wenmode

root = Wenmode().parse(text)
payload = root.to_ast()

Wenmode uses mdast-style node names where possible, so downstream tools that already understand root, paragraph, heading, text, link, image, and code shapes are usually easier to adapt than code tied to commonmark.py’s node classes.

Adding features after migration

Once the CommonMark path is migrated, you can opt into additional syntax:

commonmark.py

import commonmark

html = commonmark.commonmark(text)

wenmode

from wenmode import Wenmode
from wenmode.presets import github

html = Wenmode(github).render(text)

Use github when the migrated code is ready for the full GFM preset. Use custom rule lists for smaller dialects.

Raw HTML behavior

Review raw HTML output. Wenmode parses raw HTML syntax in the default preset, but the default HTMLRenderer() escapes raw HTML nodes. If your commonmark.py integration expected raw HTML passthrough for trusted input, configure that explicitly:

commonmark.py

import commonmark

html = commonmark.commonmark(text)

wenmode

from wenmode import HTMLRenderer, Wenmode

html = Wenmode(renderer=HTMLRenderer(escape=False)).render(text)

For untrusted user-authored Markdown, leave Wenmode’s default escaping enabled.

Checklist

• Replace commonmark.commonmark(text) with Wenmode().render(text).

• Replace commonmark.py AST traversal with Wenmode node traversal or to_ast().

• Review raw HTML passthrough assumptions.

• Add github, built-in plugins, or custom plugins only after the CommonMark migration is stable.