[v3.0.0] Add mathDelimiterMode option: strict-by-default double-backslash delimiters#418
Open
OlgaRedozubova wants to merge 2 commits into
Open
[v3.0.0] Add mathDelimiterMode option: strict-by-default double-backslash delimiters#418OlgaRedozubova wants to merge 2 commits into
OlgaRedozubova wants to merge 2 commits into
Conversation
New mathDelimiterMode?: 'strict' | 'legacy' (default 'strict') controls whether double-backslash delimiters \( ... \) / \[ ... \] are treated as math. strict: only single-backslash \( \[ (and $) are math; legacy: also accept \( \[ (pre-3.0.0 behavior). - threaded onto md.options across all option-assembly sites - multiMath rejects doubled openers in strict (fall through to escape) - lstlisting[mathescape]: verbatim backslash rule keeps \( literal in strict; single \( still renders as math - browser auto-render (renderMathInElement) honors the mode for parity - golden tests for both modes (tests/_math-delimiter-mode.js, _auto_render.js) - breaking renderer-behavior change: semver major 3.0.0 See pr-specs/2026-06-math-delimiter-mode.md
- Add strict edge-case tests: mixed prose (literal \\( + real \( math), lstlisting doubled opener abutting a single opener, and unknown mode value treated as strict (fail-safe), in both the server and auto-render suites; default-equals-strict and double display \\[ ... \\] checks too. - README: note any value other than 'legacy' is treated as 'strict'; list $/$$ alongside \( as always-math. - parse-math-escape-inline.ts: clarify rule-precedence and options-cache docstrings for the verbatim-backslash listing parser. - pr-spec: drop the N>=3 backslash non-goal.
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
1 participant
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.
Summary
Adds
mathDelimiterMode?: 'strict' | 'legacy'(default'strict') controlling whether DOUBLE-backslash delimiters\\( ... \\)and\\[ ... \\]are treated as math.'strict'(default): only single-backslash\(/\[(and$/$$) open math.\\(is not a math delimiter — it follows CommonMark escape semantics (\\→ literal\) and renders as literal text.'legacy': also accept\\(/\\[as math openers — the behavior inherited frommarkdown-it-mathjax, default in all versions ≤ 2.x.The doubled form was never a deliberate feature (forked from
markdown-it-mathjax). It (1) renders corrupted pipeline output as plausible math, masking regressions in QA views, and (2) removes the plain-text escape hatch for a literal\(. Single-backslash\(/\[and$/$$are unchanged.Breaking change (semver major → 3.0.0)
A renderer-behavior change is a format-spec change. Versions ≤ 2.x rendered
\\( ... \\)as math; under the new'strict'default such content renders as literal\(...\).Migration: consumers that rely on double-backslash delimiters (pasted / legacy MathJax-era content) must pass
mathDelimiterMode: 'legacy'explicitly. Recommended per-surface choice: user-content surfaces (editors, desktop bundle, website, document conversion) →'legacy'; pipeline-output / QA surfaces (API console, render diff/preview) →'strict'(default).What changed
optionsMathpixMarkdown/TMarkdownItOptions: newmathDelimiterMode?: 'strict' | 'legacy', threaded ontomd.optionsacross all option-assembly sites (parity withdefaultCellVerticalAlign).multiMath(mdPluginRaw.ts): in'strict'the doubled openers\\(/\\[return false, falling through to theescaperule (literal\(). Generic — no context logic.[mathescape=true](parse-math-escape-inline.ts): code is verbatim, so the math-only parser has noescaperule. It now installs a verbatim backslash rule (instead of the default escape) that keeps\\literal and consumes the pair together, so the second backslash cannot re-open a single\(. Result in'strict': every non-math backslash (\\,\n,\textbf,\\(, …) stays verbatim; single\(is still math (whatmathescapeenables).'legacy'keeps\\(as math.browser/auto-render.ts):MathpixRenderConfig.mathDelimiterMode(default'strict');stripOuterMathDelimitersIfWholeaccepts\\(...\\)/\\[...\\]only in'legacy'— symmetry with the server parser.Testing
tests/_math-delimiter-mode.js: prose + lstlisting × strict/legacy/default, for single\(/\[, doubled\\(/\\[, and$/$$; literal-preservation (prose escape-collapse vs lstlisting verbatim); legacy doubled ≡ single math.tests/_auto_render.js: strict does not render doubled\\(; legacy renders\\(/\\[; single\(renders in both modes.'strict'is a no-op on single-backslash content.Spec
pr-specs/2026-06-math-delimiter-mode.md