Skip to content

✨ NEW: Add highlight_verbatim option to skip the <pre><code> wrapper (#256) - #419

Open
cjchanh wants to merge 2 commits into
executablebooks:masterfrom
cjchanh:highlight-verbatim-option
Open

✨ NEW: Add highlight_verbatim option to skip the <pre><code> wrapper (#256)#419
cjchanh wants to merge 2 commits into
executablebooks:masterfrom
cjchanh:highlight-verbatim-option

Conversation

@cjchanh

@cjchanh cjchanh commented Aug 19, 2026

Copy link
Copy Markdown

Add highlight_verbatim option to skip the <pre><code> wrapper

Fixes #256.

Summary

New highlight_verbatim option: when set, the renderer passes the
highlighter's output through byte-exact — no <pre><code> wrapper, no
language-class injection, no renderer-added newline. The highlighter's return
value is the final rendered block, byte for byte.

Motivation (from #256)

When highlight returns pygments-style output (starts with <div, not
<pre>), markdown-it-py wraps it in <pre><code>…</code></pre> anyway,
forcing users to rewrite their Pygments CSS themes for the duplicated
wrapper. Existing workarounds require subclassing RendererHTML and
reimplementing fence().

Behavior

  • highlight_verbatim=False (default): behavior byte-identical to today
    for every existing case, including the <pre-continues heuristic.
  • highlight_verbatim=True: fence() returns the highlighter's output
    untouched. The option is inert without a highlight callback.

Byte-exactness guarantee

The renderer does not append, strip, or alter a single byte — trailing
newline or none, the output equals the highlighter's return. Regression-tested
in both directions.

Tests

Nine tests in tests/test_api/test_highlight_verbatim.py: default wrapping
unchanged, <pre passthrough, non-<pre passthrough, byte-exactness both
ways, language-class injection skipped, instance-toggle, default-path
inertness. Full suite: 991 passed.

Verification

pip install -e . && pytest tests/

Docs & changelog

docs/using.md updated; CHANGELOG.md entry added.

The verbatim path appended "\n" to the highlighter's return, breaking
byte-exactness (the very contract of the option). Verbatim now returns
the highlighter's bytes untouched; four tests that pinned the added
newline are corrected, and a byte-exactness regression test added.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Option to skip adding <pre><code> to highlighted code

1 participant