fix: preserve math expressions in comment shortcodes (LaTeX + HTML)#3
Merged
vgreg merged 3 commits intovgreg:mainfrom May 9, 2026
Merged
fix: preserve math expressions in comment shortcodes (LaTeX + HTML)#3vgreg merged 3 commits intovgreg:mainfrom
vgreg merged 3 commits intovgreg:mainfrom
Conversation
$...$ regions were escaped by escape_latex, producing broken LaTeX
like \$\textbackslash{}hat\{h\}\_*\$.
Add escape_latex_with_math which copies $...$ content verbatim and
only escapes surrounding text.
Parse comment text as Markdown so that $...$ regions become proper pandoc.Math nodes, rendered by MathJax/KaTeX in HTML output. Also fix inline comment display: replace inline-flex (which created column artifacts with multiple Pandoc nodes) with inline-block. Companion to the LaTeX math fix (previous commit)
Contributor
Author
|
@vgreg : Gently reminder : did you have time to look at my pull request ? This allows the use of maths in comments which is useful for many use cases 🙂 |
vgreg
reviewed
May 8, 2026
Owner
Thank you for this contribution. |
Contributor
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When a shortcode contains inline math, e.g.:
Two rendering failures occur depending on the output format.
LaTeX:
pandoc.utils.stringifyreturns the content as a plain string withliteral dollar signs.
escape_latexthen escapes$→\$and\→\textbackslash{}, producing broken output in the todo:HTML:
pandoc.Str(comment_text)inserts the text as an opaque string node.MathJax/KaTeX never sees a
pandoc.Mathnode and renders the dollar signs asliteral characters.
A secondary HTML issue:
build_html_inlineuseddisplay: inline-flexto layout the span contents. With a single
Strnode this was harmless, but onceparse_inlinessplits the text into multiple nodes (Str, Math, Space…), eachnode becomes a flex item and the comment renders as a column layout.
Fix
LaTeX (already in this PR): add
escape_latex_with_mathwhich splits on$...$regions — math is copied verbatim, surrounding text goes throughescape_latexas before.HTML (new): add
parse_inlines(text)which callspandoc.read(text, "markdown")and returns the inlines of the first block.This converts
$...$into properpandoc.Mathnodes that MathJax/KaTeXprocesses correctly. Use it in
build_html_inline(via:extend()) andbuild_html_block.Also replace
display: inline-flex/align-items/gapwithdisplay: inline-block/vertical-align: baselineinbuild_html_inlinetoprevent the column-layout artifact.
Result
LaTeX: renders correctly as:
HTML: math is rendered by MathJax/KaTeX; inline comment box has correct
rectangular border with no column artifacts.