Skip to content

feat(markdown): $…$ and $$…$$ TeX math drawn as equations, kept as written when saved - #40

Open
pierreneter wants to merge 1 commit into
mainfrom
feat/markdown-math
Open

pierreneter wants to merge 1 commit into
mainfrom
feat/markdown-math

Conversation

@pierreneter

Copy link
Copy Markdown
Member

Fixes #33.

Markdown math in the viewer:

  • Inline $…$ and display $$…$$ render as native MathML.
  • The document stays visually editable around each formula.
  • Every formula is saved back to Markdown exactly as written, delimiters and whitespace included.

There are no new dependencies: the TeX → MathML converter is our own, DOM-free code.

Design

  • Same model as Word equations. A formula is the existing atomic { t: 'ref' } inline, the one OMML equations already use, with a new math: { tex, delim } field. Caret movement, delete, undo, collaboration and write-back by source run work as they do for equations.

  • DOCX round trip.

    • A Markdown file opens as a DOCX in which each formula is real OMML: m:oMath, or m:oMathPara for display math.
    • Each formula carries oe:tex and oe:delim attributes in our own namespace. The root declares that namespace as mc:Ignorable, so Word can still open the file.
    • "Download as Word" therefore gives real equations, and reopening that file brings the TeX back.
    • Newlines are stored as 
, so whitespace inside a $$ block is kept byte for byte.
  • Recognition follows pandoc's rules (src/core/math/scan.ts):

    • an opening $ must be followed by a non-space;
    • a closing $ must be preceded by a non-space and not followed by a digit, so currency text such as "costs $5 and $10" is not math;
    • \$ is a dollar sign;
    • code spans and fenced or indented code blocks are never math;
    • a $$ block can span lines, but not a blank line.

    \(…\) and \[…\] are not supported: in Markdown they are escaped brackets. This is documented.

  • Fallback. An unknown command shows as <merror> while the rest of the formula renders. Malformed TeX shows its source as a subtle merror, with the reason in a tooltip. Work is bounded at 20,000 characters, 40 levels of nesting and 50,000 elements. The converter never throws: a fuzz test runs 3,000 random inputs plus a list of broken ones.

  • Accessibility, print and export. The TeX is kept as <annotation encoding="application/x-tex">. Formulas appear in print and PDF, in the HTML export and on the clipboard as MathML, and in plain-text export as TeX with its delimiters.

  • Pasting. Pasted MathML that carries a TeX annotation (from our own clipboard, KaTeX or Wikipedia) becomes a formula.

  • packages/markdown renders math with the same converter, behind a new math option that is on by default. Its output stays safe: every TeX string is escaped, and only a fixed allow-list of MathML elements and attributes is emitted, which a test checks. The package grows from about 39 KB to 53 KB gzip.

Main files

  • src/core/math/ (new):
    • tex.ts: the converter;
    • symbols.ts: symbol tables, and the math alphabets mapped to Unicode;
    • scan.ts: recognition in Markdown;
    • omml.ts: MathML → OMML.
  • convert.ts, html.ts, the DOCX parser, spec, writer and types, plainmerge.ts, render.tsx (MathView), styles.css, file/text.ts, DocxEditor.copy.
  • Docs: README.md, a new "Math in Markdown" section in docs/features.md (what is supported, what falls back, what the DOCX download contains, limitations), docs/api.md, docs/development.md, packages/markdown/README.md.
  • An incidental fix in convert.ts: the lazy list-continuation .replace() now uses a function, so a $& in text is no longer read as a replacement pattern.

Tests

  • test/math.test.ts (31 tests): the MathML structure for each construct family, errors, limits, the fuzz test, and OMML.
  • test/markdown-math.test.ts (21 tests):
    • recognition;
    • the round trip: an unedited save is identical, an edit beside a formula keeps its TeX, CRLF files, edits through the worker, pasted formulas;
    • the DOCX contents and the escaping of $;
    • the text, HTML and clipboard exports;
    • the package.
  • e2e/markdown-math.spec.ts (6 tests in Chromium):
    • rendering, with the document not dirty after open;
    • typing next to a formula, then saving;
    • caret, Delete and Undo, copy and paste;
    • a formula typed in the source pane;
    • print and the HTML, text and Markdown exports;
    • TeX that tries to inject markup stays text.

Results

In the Linux test VM with Bun 1.4.4:

Check Result
typecheck clean
bun test 1244 pass, 0 fail
e2e markdown-math 6/6
e2e viewer 27/27
e2e docx 23/23
e2e file-menu 29/29
e2e security 7/7
e2e sdk 1/1
e2e docx-qa2 13/13
bun run build ok
bun run build:packages ok

After rebasing onto af19290, which only changes package.json, I re-ran typecheck and the math unit tests.

Limitations

These are documented in docs/features.md.

  • Not supported:
    • GitHub ```math blocks and $`…`$;
    • \(…\) and \[…\];
    • macros (\newcommand), \href, \ce.
  • Lists and quotes: in the viewer, a multi-line $$ block inside a list item or a quote is not recognised. One-line formulas work there.
  • Rewritten paragraphs: when an edited paragraph is written back, a few things can change:
    • an unneeded \$ escape becomes $;
    • emphasis around a formula (*$x$*) is dropped;
    • an inline formula followed directly by a digit would not read back as math.
  • Shell-like text: $HOME/$USER is read as math, as pandoc does.
  • Equations from Word files are still shown as linear text. That is out of scope here.
  • Not checked in Word: the generated DOCX was not opened in Word. Its OMML and namespace declaration are checked structurally and by re-reading them with our own parser.
  • Chromium rendering:
    • \boxed and \cancel draw nothing;
    • column alignment comes from CSS;
    • letter shapes depend on the system math font.

A merge conflict with the syntax-highlighting branch (#32) is likely in convert.ts markdownToHtml and in text.ts mdInline.

🤖 Generated with Claude Code

…itten when saved

A zero-dependency TeX → MathML converter (src/core/math) draws the formulas of a Markdown file with the browser's own
MathML: selectable, read by screen readers, printed and exported. Each formula is one object of the document (the
equation model Word files already use), holding its TeX and delimiters, so an edit around it saves the formula back
byte for byte; currency, \$ and code are left alone (pandoc's rules). A command it does not know, or TeX it cannot
read, shows its source and never breaks the page. Download as Word gives real Office Math equations carrying the TeX
in ignorable attributes; copy / paste keeps formulas (MathML holding TeX on the clipboard). @p10node/markdown renders
math too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
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.

Markdown: render inline and display LaTeX math

1 participant