Troubleshooting¶

Diagnose common Wenmode integration issues around raw HTML, URL sanitization, directives, streaming, custom renderers, and rule selection.

Raw HTML is escaped¶

HTMLRenderer() escapes raw HTML nodes by default. This is the recommended setting for user-authored Markdown.

Use raw HTML passthrough only for trusted or separately sanitized content:

from wenmode import HTMLRenderer, Wenmode

wenmode = Wenmode(renderer=HTMLRenderer(escape=False))

If you do not want raw HTML syntax to become html nodes at all, remove HtmlBlock and RawHtml from the rule list. See Security.

Links render without href¶

HTMLRenderer() drops unsafe URL schemes by default. For example, javascript: links render without href.

from wenmode import Wenmode

html = Wenmode().render('[x](javascript:alert(1))')
assert html == '<p><a>x</a></p>\n'

Use HTMLRenderer(sanitize_urls=False) only when URL validation is handled outside Wenmode.

A directive parses but does not render custom HTML¶

Directive syntax rules and directive renderers are separate. Enabling ContainerDirective, LeafDirective, TextDirective, FencedDirective, or Role only creates directive nodes. Register a directive renderer when you want special HTML output.

from wenmode import Wenmode
from wenmode.directives import Admonition
from wenmode.rules import ContainerDirective

wenmode = Wenmode([ContainerDirective], directives=[Admonition()])

Without a matching directive renderer, Wenmode falls back to rendering directive children.

A custom renderer handler is not called¶

Renderer handlers are selected by node.type, not by the Python class name. Check the AST with root.to_ast() and register the exact type string:

from wenmode import Wenmode

root = Wenmode().parse('**strong**')
assert root.to_ast()['children'][0]['children'][0]['type'] == 'strong'

For custom nodes, set a stable type value and register handlers during application startup. See Custom rules.

Streaming raises StreamingUnsupportedError¶

Streaming cannot use rules that need document-wide deferred inline resolution, such as reference-style links, footnotes, or abbreviations. Use the streaming preset:

from wenmode import Wenmode
from wenmode.presets import streaming

wenmode = Wenmode(streaming)

If you build a custom streaming rule list, avoid Footnote, Abbreviation, Link(references=True), and Image(references=True). See Rule matrix.

GFM syntax is not recognized¶

Wenmode() uses the commonmark preset. Tables, task list items, strikethrough, footnotes, and extended autolinks require the github preset or the individual extension rules.

from wenmode import Wenmode
from wenmode.presets import github

wenmode = Wenmode(github)

Reference-style links stay as text¶

Reference-style links need Link(references=True) and collected reference definitions. The streaming preset disables references so it can emit output incrementally.

Use commonmark or github for full-document reference-style link support, or use direct links in streaming responses.