Superscript raises text above the baseline, as in an exponent, and subscript lowers it below the baseline, as in a chemical formula. To write superscript, wrap text in carets (^). To write subscript, wrap it in tildes (~).

Comrak’s superscript and subscript follow the superscript and subscript extensions of commonmark-hs, which Pandoc also uses. This document describes both extensions, and Differences from commonmark-hs lists where they differ. GitLab Flavored Markdown doesn’t support either syntax.

To enable superscript, pass -e superscript on the command line, or set extension.superscript in the options struct. For subscript, pass -e subscript, or set extension.subscript.

Here’s typical superscript and subscript:

Example 1
$ comrak -e superscript -e subscript
E = mc^2^, and water is H~2~O.

Syntax

Superscript and subscript work like CommonMark’s emphasis, with carets or tildes in place of asterisks, except that punctuation doesn’t affect where they begin and end.

A caret run is a sequence of carets that isn’t preceded or followed by another caret. A tilde run is a sequence of one or two tildes that isn’t preceded or followed by another tilde. A caret run, or a tilde run of one tilde, can open superscript or subscript if it isn’t followed by whitespace, and can close it if it isn’t preceded by whitespace. The beginning and end of a line count as whitespace.

Superscript begins with a caret that can open it, and ends with a later caret that can close it. Subscript begins with a tilde run of one tilde that can open it, and ends with a later tilde run of one tilde that can close it. Comrak pairs runs with CommonMark’s process emphasis procedure, the same procedure that pairs emphasis delimiters.

Caret runs

Each caret in a caret run pairs separately, so a run of two carets can begin two superscripts:

Example 2
$ comrak -e superscript -e subscript
^^a^^ and ^^^b^^^

The caret runs at each end needn’t be the same length. Carets left over are literal text:

Example 3
$ comrak -e superscript -e subscript
^a^^ and ^^b^

As with emphasis, if either of two caret runs can both open and close superscript, the two don’t pair when their lengths add up to a multiple of three, unless both lengths are multiples of three. A caret run inside a word can both open and close:

Example 4
$ comrak -e superscript -e subscript
x^^y^z

Tilde runs

Tilde runs follow strikethrough’s rules, whether or not strikethrough is enabled. A tilde run of one tilde forms subscript. A tilde run of two tildes forms strikethrough if strikethrough is enabled, and is literal text if it isn’t. Three or more tildes are always literal text, as are tilde runs of different lengths:

Example 5
$ comrak -e subscript
~~a~~ and ~~~b~~~ and ~c~~

Flanking

Punctuation doesn’t affect whether a caret run, or a tilde run of one tilde, can open or close. Superscript and subscript may begin before punctuation and end after it, even inside a word:

Example 6
$ comrak -e superscript -e subscript
i^-2^ and x~(1)~y and a^b.^c

Whitespace does affect whether a run can open or close. A run followed by whitespace can’t open, and one preceded by whitespace can’t close:

Example 7
$ comrak -e superscript -e subscript
a^ b^ and a^b ^ and ^ ^

a~ b~ and a~b ~ and ~ ~

Superscript and subscript may begin and end inside a word, and may contain spaces and other inline content:

Example 8
$ comrak -e superscript -e subscript
a^b^c and a~b~c

E = mc^2 or *3*^

Nesting

Superscript and subscript may contain each other, or themselves:

Example 9
$ comrak -e superscript -e subscript
^a ^b^ c^ and ~a ^b^ c~

Superscript, subscript and emphasis may contain each other:

Example 10
$ comrak -e superscript -e subscript
^*a*^ and *~a~*

When superscript or subscript overlaps emphasis, the first to close wins, and the other’s delimiters are literal text:

Example 11
$ comrak -e superscript -e subscript
*a ^b* c^ and ^a *b^ c*

Precedence

Code spans and links take precedence over superscript and subscript, so runs pair only within or around them:

Example 12
$ comrak -e superscript -e subscript
^a `b^` c^
Example 13
$ comrak -e superscript -e subscript
^a [b^ c]/u

[a^2^]/u and ~[b]/u~

Brackets that don’t form a link don’t affect pairing:

Example 14
$ comrak -e superscript -e subscript
[x^2^] and [ y~2~

Superscript and subscript may span lines, but not paragraphs:

Example 15
$ comrak -e superscript -e subscript
^a
b^ and ~c
d~
Example 16
$ comrak -e superscript -e subscript
^a

b^

A backslash escape or an entity reference is literal text, not a run:

Example 17
$ comrak -e superscript -e subscript
\^a^ and \~b~

^a^ and ~b~

Output

HTML output renders superscript as a <sup> element, and subscript as a <sub> element. In an image description, which becomes the image’s alt attribute, superscript and subscript contribute only their text:

Example 18
$ comrak -e superscript -e subscript
![E = mc^2^]/e.png

CommonMark output writes superscript with a caret on each side, and subscript with a tilde on each side. It escapes other tildes (\~) and, with superscript enabled, other carets (\^), to prevent reading them back as runs:

Example 19
$ comrak -e superscript -e subscript
^^a^^ and \^b^ and c~d

In XML output, superscript is a superscript element, and subscript is a subscript element. Without strikethrough, a pair of two-tilde runs is an escaped_tag element, with the tildes in its tag attribute.

In the AST, superscript is a NodeValue::Superscript, and subscript is a NodeValue::Subscript, each with its content as children. Without strikethrough, a pair of two-tilde runs is a NodeValue::EscapedTag holding "~~".

The source position of superscript or subscript covers its runs:

Example 20
$ comrak -e superscript -e subscript --sourcepos
x ^a^ ~b~

Interactions

With strikethrough, a tilde run of one tilde forms subscript, and a tilde run of two tildes forms strikethrough:

Example 21
$ comrak -e strikethrough -e subscript
H~2~O is ~~not~~ water.
Example 22
$ comrak -e strikethrough -e subscript
~~H~2~O~~

Strikethrough keeps its own flanking rules, in which punctuation matters. Here, the two-tilde run after a and before ( can’t open strikethrough, but the one-tilde run can open subscript:

Example 23
$ comrak -e strikethrough -e subscript
a~~(b)~~ c and a~(b)~ c

With footnotes, a footnote reference’s caret doesn’t begin superscript. A [^ that doesn’t form a reference isn’t special: its bracket is literal text, and its caret pairs like any other:

Example 24
$ comrak -e superscript -e footnotes
a[^1] b^2^ [^x] c^d^

[^1]: A note.

With inline footnotes, ^[ begins an inline footnote, not superscript:

Example 25
$ comrak -e superscript -e footnotes -e inline-footnotes
a^[A note.] and b^2^

With autolinks, a www autolink doesn’t form straight after a caret, because a www autolink must begin at the start of a line, after whitespace, or after one of *, _, ~, or (. A URL autolink may end in a caret: a closing caret straight after a URL belongs to the URL:

Example 26
$ comrak -e superscript -e subscript -e autolink
^www.example.com^ and ^https://example.com^ and ~www.example.com~

With maths, the content of maths is literal text, so carets and tildes in it don’t form superscript or subscript:

Example 27
$ comrak -e superscript -e subscript -e math-dollars
$x^2^$ and $y~1~$

CJK-friendly emphasis doesn’t change superscript or subscript, since punctuation doesn’t affect their flanking:

Example 28
$ comrak -e superscript -e subscript -e cjk-friendly-emphasis
「^a」^b and あ~い~う

With OFM block IDs, a caret on a block’s last line begins a block ID, unless a later caret closes it as superscript:

Example 29
$ comrak -e superscript -e ofm-block-ids
a ^b^ c ^abc

a ^abc^

With description lists, a line beginning with a tilde and a space marks a description, not a tilde run:

Example 30
$ comrak -e subscript -e description-lists
Term

~ a~2~

Differences from commonmark-hs

Pandoc’s commonmark reader uses commonmark-hs. This section compares Comrak with Pandoc 3.7, run as pandoc -f commonmark+superscript+subscript. Since Pandoc’s other extensions differ from Comrak’s, the examples under Interactions aren’t comparable, and nor is example 20, which shows source positions. On every other example above, the two agree on superscript and subscript, except for tilde runs. Without strikethrough, Pandoc pairs each tilde separately, as Comrak pairs carets. Two or three tildes form nested subscripts, and tilde runs of different lengths pair (example 5).

Pandoc’s own Markdown reader doesn’t allow spaces in superscript or subscript, and isn’t compared here.

Regressions

The following examples guard against regressions.

Superscript and subscript may begin before punctuation (#592):

Example 31
$ comrak -e superscript -e subscript
i^-2^ = -1.

f~i~ = f~-2 + i~ + f~-1 + i~.

A footnote reference doesn’t stop superscript elsewhere in the document (#274):

Example 32
$ comrak -e superscript -e footnotes
Here is a footnote reference.[^1]

e = mc^2^.

[^1]: Here is the footnote.