--- title: "Markdown superscript: carets tested with pandoc" slug: markdown-superscript excerpt: "Markdown superscript in pandoc: the section The superscript extension in pandoc names the reader flags that produced a sup element in this test." quickAnswer: "Under Carets in plain CommonMark, spec searches sit beside one commonmark run on a caret test file. The section The superscript extension in pandoc lists the reader flags that turned superscript on and off in this test. Two spacing tries and how two readers handled them are in the section Spaces inside the carets. The section Subscript with tildes covers the tilde form and its reader flags. The numbered how-to sits under Test your own superscript line." keyTakeaways: - "Typed tag results for sup and sub, from two readers, fill the section Raw HTML sup tags." - "Under When the carets stay as text, three test cases kept their carets in pandoc's output." - "Pandoc output for tilde pairs sits in the section Subscript with tildes." - "Results for a bare space and an escaped space are in the section Spaces inside the carets." - "Numbered steps with a grep count are under Test your own superscript line." publishedDate: 2026-10-20 dateModified: 2026-10-20 author: Bobby Huang cluster: B role: post status: published faq: - q: Does CommonMark have superscript syntax? a: "The section Carets in plain CommonMark shows spec grep counts and the commonmark output for a caret test line." - q: Which pandoc reader flag turns superscript on? a: "Reader flags from this test are listed in the section The superscript extension in pandoc." - q: What happens with a space inside the carets? a: "Test output for a bare space and an escaped space is in the section Spaces inside the carets." - q: Can I type a sup tag instead? a: "Under Raw HTML sup tags, pandoc output for a typed tag is shown for two readers." related: - markdown-footnotes - raw-html-in-markdown - markdown-escape-characters --- 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 `` 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: ```markdown E = mc^2^ and x^10^ ``` For `pandoc -f commonmark -t html sup-basic.md`, pandoc printed `

E = mc^2^ and x^10^

`. Both pairs of carets stayed in the text, and no `` 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: ```sh pandoc -f commonmark+superscript -t html sup-basic.md ``` Pandoc gave `

E = mc2 and x10

`. The two-digit `10` landed inside a single `` 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 `

E = mc^2^ and x^10^

`, 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](markdown-footnotes.md). ## 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: ```markdown a^b c^ and a^b\ c^ ``` For `pandoc -f markdown -t html sup-space.md`, the output was `

a^b c^ and ab c

`. The bare space left its carets as text. The escaped space turned into a plain space inside ``, and the backslash was gone. Switching the reader to `commonmark+superscript` (`pandoc -f commonmark+superscript -t html sup-space.md`) gave `

ab c and ab\ c

`. This time the bare space worked. The backslash stayed inside the second `` 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 `` 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`: ```html mc2 ``` Both readers, `commonmark` and `markdown`, returned `

mc2

`. The tag came through unchanged, and no flag was needed. The subscript tag behaved the same way. For `sub-x-html.md`, which held `H2O`, both readers gave `

H2O

`. For inline tags versus HTML blocks, and what happens to the HTML after pandoc, see the [guide to raw HTML](raw-html-in-markdown.md). ## 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 `

E = mc^2^

`. 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](markdown-escape-characters.md) has more. 2. **A code span.** In `sup-x-code.md`, backticks wrap `mc^2^`. Both readers gave `mc^2^`, 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: ```markdown H~2~O ``` Under `commonmark`, pandoc gave `

H~2~O

`. Under both `commonmark+subscript` and `markdown`, it gave `

H2O

`. 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 `

H2O and mc2

`. With only `commonmark+superscript`, the tildes stayed and the carets worked: `

H~2~O and mc2

`. ## 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 `` element. 4. Count with grep. Piping `pandoc -f markdown -t html sup-basic.md` into `grep -c ''` printed `1` here, and the same pipe with `-f commonmark` printed `0`. The `-c` flag counts matching lines, so one line holding two `` 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 `` 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](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands. Bookmark [sashmark.com](https://www.sashmark.com/) to see the work move along.