Markdown superscript: carets tested with pandoc

You typed mc^2^ to lift the 2 above the line, and the output still showed both carets. Maybe one pandoc command raised the 2 while a second left the carets in the text.

Here is markdown superscript in pandoc 3.8.3, tested once on macOS: the caret form with pandoc's superscript extension, spaces inside the carets, a typed <sup> tag, and the tilde form for subscript. Each test file is named where it first appears, so you can rebuild it and rerun the same command.

Carets in plain CommonMark

Superscript syntax is absent from CommonMark spec 0.31.2. Running grep -ci 'superscript' commonmark-spec-0.31.2.txt on the spec file matched 0 lines, and the same search for subscript matched 0 as well. For a control, block quote matched 57 lines in the same file.

The first test file, sup-basic.md, held one line:

E = mc^2^ and x^10^

For pandoc -f commonmark -t html sup-basic.md, pandoc printed <p>E = mc^2^ and x^10^</p>. Both pairs of carets stayed in the text, and no <sup> element came out.

The superscript extension in pandoc

In pandoc, this syntax is the superscript extension. The extension list pandoc printed for its commonmark reader showed -superscript, which means it starts switched off there. The list for the markdown reader showed +superscript, so that reader starts with it on.

Put +superscript after the reader name and commonmark picks up the extension:

pandoc -f commonmark+superscript -t html sup-basic.md

Pandoc gave <p>E = mc<sup>2</sup> and x<sup>10</sup></p>. The two-digit 10 landed inside a single <sup> element.

With no flag added, the markdown reader produced that same line. To switch the extension off there, prefix its name with a minus sign. Running pandoc -f markdown-superscript -t html sup-basic.md returned <p>E = mc^2^ and x^10^</p>, carets and all.

A footnote marker such as [^1] also puts a caret in your text, and in sup-footnote.md pandoc's markdown reader handled it as a footnote. For how footnotes are written and placed, read the footnotes guide.

Spaces inside the carets

The test file sup-space.md held two tries on one line. The first has a bare space between the carets, and the second puts a backslash before the space:

a^b c^ and a^b\ c^

For pandoc -f markdown -t html sup-space.md, the output was <p>a^b c^ and a<sup>b c</sup></p>. The bare space left its carets as text. The escaped space turned into a plain space inside <sup>, and the backslash was gone.

Switching the reader to commonmark+superscript (pandoc -f commonmark+superscript -t html sup-space.md) gave <p>a<sup>b c</sup> and a<sup>b\ c</sup></p>. This time the bare space worked. The backslash stayed inside the second <sup> element as a visible character.

The two readers wanted opposite spellings for a space in this test. In sup-basic.md, where the carets held no spaces, both markdown and commonmark+superscript gave <sup> elements.

Raw HTML sup tags

Typing the tag works as well, with no carets at all. In the spec, lines 8179 and 8180 of the Raw HTML section say that text inside angle brackets shaped like an HTML tag gets parsed as raw HTML and is output without escaping.

The tag test, sup-html.md:

mc<sup>2</sup>

Both readers, commonmark and markdown, returned <p>mc<sup>2</sup></p>. The tag came through unchanged, and no flag was needed.

The subscript tag behaved the same way. For sub-x-html.md, which held H<sub>2</sub>O, both readers gave <p>H<sub>2</sub>O</p>.

For inline tags versus HTML blocks, and what happens to the HTML after pandoc, see the guide to raw HTML.

When the carets stay as text

These three cases kept their carets as text in pandoc's output.

1. Escaped carets. For E = mc\^2\^ in sup-x-escape.md, both markdown and commonmark+superscript gave <p>E = mc^2^</p>. The backslashes dropped out and the carets stayed. A backslash may precede any ASCII punctuation character per spec line 481, and the example on line 485 includes the caret. The post on escaping characters has more.
2. A code span. In sup-x-code.md, backticks wrap mc^2^. Both readers gave <code>mc^2^</code>, with the carets inside.
3. Superscript turned off. As shown under The superscript extension in pandoc, markdown-superscript gave the carets of sup-basic.md back as text.

Subscript with tildes

Subscript works through a separate pandoc extension named subscript, with single tildes around the text. Pandoc's lists showed -subscript for the commonmark reader and +subscript for markdown.

The test file sub-basic.md held one line:

H~2~O

Under commonmark, pandoc gave <p>H~2~O</p>. Under both commonmark+subscript and markdown, it gave <p>H<sub>2</sub>O</p>. With markdown-subscript, the tildes came back as text.

The two extensions are separate switches. For sub-x-both.md, which held H~2~O and mc^2^, the reader setting commonmark+superscript+subscript gave <p>H<sub>2</sub>O and mc<sup>2</sup></p>. With only commonmark+superscript, the tildes stayed and the carets worked: <p>H~2~O and mc<sup>2</sup></p>.

Test your own superscript line

If a superscript misbehaves, isolate the line first.

1. Put the line you're checking in a file of its own, the way sup-basic.md holds one line here.
2. Convert that file as plain CommonMark: pandoc -f commonmark -t html. If the carets remain in the output, that matches what sup-basic.md gave in this test.
3. Repeat with commonmark+superscript or plain markdown as the reader, and look for a <sup> element.
4. Count with grep. Piping pandoc -f markdown -t html sup-basic.md into grep -c '<sup>' printed 1 here, and the same pipe with -f commonmark printed 0. The -c flag counts matching lines, so one line holding two <sup> elements still printed 1.
5. On a zero, look for a space inside the carets, a backslash before a caret, or backticks around the text.
6. To keep the file plain CommonMark, swap the carets for a typed <sup> tag, then repeat step 2 and confirm the tag came through.

Where Sashmark fits

Sashmark's plan has you editing straight on the rendered page; its clean Round-Trip is meant to leave each untouched line byte-for-byte identical. Also on the v1 plan: a Changes View that would highlight edits since your last look at the file, planned to work without 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.

Bookmark sashmark.com to see the work move along.