Migrating from markdown2#

Replace markdown2’s Markdown-to-HTML calls and extras with Wenmode presets, configured rules, AST helpers, and renderer options.

markdown2 exposes a compact API and optional extras. Wenmode is more explicit: syntax is selected by presets or rules, and output is controlled by renderers.

Simple rendering#

markdown2’s common API is:

markdown2#

import markdown2

html = markdown2.markdown(text)

Use Wenmode’s high-level renderer:

wenmode#

from wenmode import Wenmode

html = Wenmode().render(text)

If you previously reused a markdown2 converter object, keep a reusable Wenmode instance:

markdown2#

import markdown2

converter = markdown2.Markdown(extras=['tables'])
html = converter.convert(text)

wenmode#

from wenmode import Wenmode
from wenmode.presets import github

wen = Wenmode(github)
html = wen.render(text)

Extras mapping#

markdown2 extras vary in scope. Some map directly to Wenmode rules; others need custom plugins or preprocessing.

markdown2 extra	Wenmode replacement
`tables`	`github` preset or `Table` rule
`fenced-code-blocks`	default `commonmark` preset includes fenced code
`footnotes`	`github` preset or `Footnote` rule
`header-ids`	`AtxHeading(transforms=[HeadingIdTransform()])`, `SetextHeading(transforms=[HeadingIdTransform()])`, or `add_heading_ids()`
`strike`	`github` preset or `Strikethrough` rule
`code-friendly`	usually no direct migration; test the exact documents and adjust rule lists if needed
`smarty-pants`	run a typography transform before or after Wenmode, or add a custom renderer transform
`metadata`	`wenmode.plugins.frontmatter` for top-level front matter metadata
`toc`-style workflows	heading helpers plus `collect_toc()` / `render_toc_html()`

Tables, footnotes, and strikethrough#

For the common “extras for GFM-like documents” setup:

markdown2#

import markdown2

html = markdown2.markdown(text, extras=['tables', 'footnotes', 'strike'])

Use Wenmode’s github preset:

wenmode#

from wenmode import Wenmode
from wenmode.presets import github

html = Wenmode(github).render(text)

Heading IDs#

If you used markdown2’s header ID support, enable heading ID transforms:

markdown2#

import markdown2

html = markdown2.markdown(text, extras=['header-ids'])

wenmode#

from wenmode import Wenmode
from wenmode.headings import HeadingIdTransform
from wenmode.rules import AtxHeading, SetextHeading

wen = Wenmode([
    AtxHeading(transforms=[HeadingIdTransform()]),
    SetextHeading(transforms=[HeadingIdTransform()]),
])
html = wen.render(text)

For a fuller CommonMark-like dialect with heading IDs, start from commonmark and replace the heading rules with configured instances.

Raw HTML behavior#

Review raw HTML behavior carefully. Wenmode’s default renderer escapes raw HTML nodes and sanitizes unsafe URLs:

markdown2#

import markdown2

html = markdown2.markdown(text)

wenmode#

from wenmode import Wenmode

html = Wenmode().render(text)

Use passthrough only for trusted content:

wenmode#

from wenmode import HTMLRenderer, Wenmode

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

AST and transformations#

markdown2 is primarily an HTML converter. If you added preprocessing or postprocessing around markdown2, consider moving that logic to Wenmode’s AST:

markdown2#

import markdown2

html = markdown2.markdown(text)

wenmode#

from wenmode import Wenmode

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

Use root transforms for document-wide state such as definitions, collected metadata, or generated attributes.

Checklist#

Replace extras with github, configured rules, or custom plugins.
Handle front matter or metadata with wenmode.plugins.frontmatter or application-specific load and dump callbacks.
Rebuild heading IDs and TOC behavior with Wenmode helpers.
Compare HTML output for raw HTML, code blocks, tables, and footnotes.