Markdown math: dollar signs and pandoc test results

You typed $a^2 + b^2$ into a note and ran it through pandoc's commonmark reader. The dollar signs, the caret and the plus sign came back exactly as you typed them, inside a plain paragraph.

The tests for this post on markdown math ran once, on a single Mac, using pandoc release 3.8.3, and span four areas: dollar-sign math, lines where dollar signs stayed as text, backslash delimiters and MathML output. Each result quoted here names its test file. Rebuild the file and repeat the command to check it yourself.

Math in plain CommonMark

CommonMark's 0.31.2 spec lists no math syntax. Searched without regard to case, grep -ci 'math' on the spec counted 0 lines, and grep -ci 'equation' counted 0 as well. As a control, grep -c 'block quote' on that file counted 54. For what the spec does cover, the core syntax guide goes through it piece by piece.

The test file math-dollars.md held an inline formula and a display block:

Area is $a^2 + b^2$ here.

$$
E = mc^2
$$

Two paragraphs of text came back from pandoc -f commonmark -t html math-dollars.md:

<p>Area is $a^2 + b^2$ here.</p>
<p>$$ E = mc^2 $$</p>

The dollar signs stayed in place. The three lines of the display block were joined into one paragraph, with spaces where the line breaks had been. Pandoc's extension list for commonmark showed -tex_math_dollars, and the minus sign means that extension is off for that reader.

Turning on dollar sign math

This syntax goes by the name tex_math_dollars in pandoc. The extension list printed in this test showed +tex_math_dollars for the markdown reader, so it's switched on there from the start. For commonmark, you add it to the reader name with a plus sign.

Two runs on the same math-dollars.md file:

• pandoc -f commonmark+tex_math_dollars -t html math-dollars.md
• pandoc -f markdown -t html math-dollars.md

Both returned the same HTML. The inline formula came out inside <span class="math inline"> and the display block inside <span class="math display">. Inside each span, pandoc wrote the letters with <em> and the exponents with <sup>. Here is the inline part as an ASCII-normalized copy, split over three lines. Pandoc put the character U+2005 on each side of the plus sign, and this copy shows a plain space in each of those spots:

<p>Area is <span
class="math inline"><em>a</em><sup>2</sup> + <em>b</em><sup>2</sup></span>
here.</p>

And here is the display block from the same run, also ASCII-normalized. Around the equals sign, pandoc used U+2004, and this copy shows plain spaces there:

<p><span
class="math display"><em>E</em> = <em>m</em><em>c</em><sup>2</sup></span></p>

To switch it back off under markdown, put a minus sign before the name. In an extra run, pandoc -f markdown-tex_math_dollars -t html math-dollars.md returned the same two text paragraphs that plain commonmark gave.

Dollar signs that stay as text

Two dollar signs on one line did not make math in every test. The extra file math-x-signs.md held one sentence with $5 and $10 in it. Under commonmark+tex_math_dollars and under markdown, pandoc returned the sentence unchanged inside a <p> element, with $5 and $10 still in place. No math span appeared. Plain commonmark gave the same paragraph. This test did not look into the rule pandoc applied, so check your own lines before you rely on them.

The file math-escaped.md put a backslash before each dollar sign, as in \$5. Pandoc's markdown reader dropped the backslash and printed $5. An extra plain commonmark run on that file gave the same paragraph. In the spec, line 481 allows a backslash before any ASCII punctuation character, and the list at lines 332 to 337 includes the dollar sign. The guide to backslash escapes covers the rest of the escapable characters.

Two more extra files tested the edges of the inline form:

• A space inside each dollar sign. The file math-x-space.md held Area is $ a^2 $ here. Both markdown and commonmark+tex_math_dollars returned the line as typed, with no math span.
• Backticks around the formula. In math-x-code.md, the formula $a^2$ sat between backticks. Both settings returned <code>$a^2$</code>. For more on backtick spans and fenced blocks, read the code blocks guide.

Backslash parentheses and brackets

Pandoc also has an extension for math between backslash delimiters. The test file math-parens.md held this line, with two backslashes before each delimiter:

Inline \\(x^2\\) and \\[y\\]

Three runs:

• pandoc -f commonmark -t html math-parens.md returned <p>Inline \(x^2\) and \[y\]</p>.
• pandoc -f markdown -t html math-parens.md returned that same paragraph.
• pandoc -f markdown+tex_math_double_backslash -t html math-parens.md returned <span class="math inline"> around the parentheses part and <span class="math display"> around the brackets part.

In the first two runs, each pair of backslashes turned into one backslash in the output. That lines up with the spec: the backslash is on the ASCII punctuation list at line 336, so under line 481 one backslash can escape another. The extension list for markdown showed -tex_math_double_backslash, so that extension stays off until you add it. The same list showed -tex_math_single_backslash. This test did not run that one.

MathML output from pandoc

The runs under Turning on dollar sign math wrapped each formula in a span. The --mathml flag swaps that for MathML. This test ran pandoc -f markdown -t html --mathml math-dollars.md.

The inline formula came out as a <math display="inline"> element and the display block as <math display="block">. Both carried the MathML namespace. Inside, pandoc wrote <mi> for letters, <mn> for numbers, <mo> for the plus and equals signs and <msup> for exponents. It also kept the source formula in an <annotation encoding="application/x-tex"> element.

An extra run passed pandoc -f commonmark+tex_math_dollars -t html --mathml math-dollars.md output through grep -c '<math', which printed 2. In this file, that's one line per formula.

Check a file for math output

If a formula doesn't come out as math, test it on its own.

1. Paste the formula line into a new test file.
2. Use pandoc -f commonmark -t html to convert the test file. If the output still shows the dollar signs, that matches what plain commonmark gave for math-dollars.md.
3. Run it again with -f commonmark+tex_math_dollars, or with -f markdown.
4. Pipe the output into grep. In the extra run, pandoc -f markdown -t html math-dollars.md | grep -c 'class="math' printed 2. The same pipe after pandoc -f commonmark -t html math-dollars.md printed 0.
5. If grep still prints 0 with the extension on, compare your line with the test files under Dollar signs that stay as text.
6. For delimiters made of two backslashes, add +tex_math_double_backslash to the markdown reader and repeat step 4.
7. To get MathML in place of spans, add --mathml to the command.

Where Sashmark fits

The v1 plan for Sashmark covers editing right on the rendered page. Under its planned clean Round-Trip, any line you never changed would keep its exact bytes. Next to that sits a planned Changes View, set to flag edits added since your last read. Its plan calls for no git. It is in development and has not been released. The app itself has no AI features. See the planned features, the help pages and the roadmap for where each part stands.

Follow the build at sashmark.com.