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:
$ comrak -e superscript -e subscript -t commonmark -t xml
E = mc2, and water is H2O.
E = mc2, and water is H2O.
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:
$ comrak -e superscript -e subscript -t commonmark -t xml
a and b
a and b
a
and
b
The caret runs at each end needn’t be the same length. Carets left over are literal text:
$ comrak -e superscript -e subscript -t commonmark -t xml
a^ and ^b
a^ and ^b
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:
$ comrak -e superscript -e subscript -t commonmark -t xml
x^^y^z
x^^y^z
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:
$ comrak -e subscript -t commonmark -t xml
~~a~~ and ~~~b~~~ and ~c~~
~~a~~ and ~~~b~~~ and ~c~~
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:
$ comrak -e superscript -e subscript -t commonmark -t xml
i-2 and x(1)y and ab.c
i-2 and x(1)y and ab.c
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:
$ comrak -e superscript -e subscript -t commonmark -t xml
a^ b^ and a^b ^ and ^ ^
a~ b~ and a~b ~ and ~ ~
a^ b^ and a^b ^ and ^ ^
a~ b~ and a~b ~ and ~ ~
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:
$ comrak -e superscript -e subscript -t commonmark -t xml
abc and abc
E = mc2 or 3
abc and abc
E = mc2 or 3
a
b
c and a
b
c
E = mc
2 or
3
Nesting
Superscript and subscript may contain each other, or themselves:
$ comrak -e superscript -e subscript -t commonmark -t xml
a b c and a b c
a b c and a b c
a
b
c
and
a
b
c
Superscript, subscript and emphasis may contain each other:
$ comrak -e superscript -e subscript -t commonmark -t xml
a and a
a and a
a
and
a
When superscript or subscript overlaps emphasis, the first to close wins, and the other’s delimiters are literal text:
$ comrak -e superscript -e subscript -t commonmark -t xml
a ^b c^ and a *b c*
a ^b c^ and a *b c*
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:
$ comrak -e superscript -e subscript -t commonmark -t xml
a b^ c
a b^ c
a
b^
c
$ comrak -e superscript -e subscript -t commonmark -t xml
Brackets that don’t form a link don’t affect pairing:
$ comrak -e superscript -e subscript -t commonmark -t xml
[x2] and [ y2
[x2] and [ y2
[x
2
] and [ y
2
Superscript and subscript may span lines, but not paragraphs:
$ comrak -e superscript -e subscript -t commonmark -t xml
a b and c d
a
b and c
d
a
b
and
c
d
$ comrak -e superscript -e subscript -t commonmark -t xml
^a
b^
^a
b^
^a
b^
A backslash escape or an entity reference is literal text, not a run:
$ comrak -e superscript -e subscript -t commonmark -t xml
^a^ and ~b~
^a^ and ~b~
^a^ and ~b~
^a^ and ~b~
^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:
$ comrak -e superscript -e subscript -t commonmark -t xml

E = mc
2
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:
$ comrak -e superscript -e subscript -t commonmark -t xml
a and ^b^ and c~d
a and ^b^ and c~d
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:
$ comrak -e superscript -e subscript --sourcepos -t commonmark -t xml
x a b
x a b
x
a
b
Interactions
With strikethrough, a tilde run of one tilde forms subscript, and a tilde run of two tildes forms strikethrough:
$ comrak -e strikethrough -e subscript -t commonmark -t xml
H2O is not water.
H2O is not water.
H
2
O is
not
water.
$ comrak -e strikethrough -e subscript -t commonmark -t xml
H2O
H2O
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:
$ comrak -e strikethrough -e subscript -t commonmark -t xml
a~~(b)~~ c and a(b) c
a~~(b)~~ c and a(b) c
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:
$ comrak -e superscript -e footnotes -t commonmark -t xml
With inline footnotes, ^[ begins an inline footnote, not superscript:
$ comrak -e superscript -e footnotes -e inline-footnotes -t commonmark -t xml
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:
$ comrak -e superscript -e subscript -e autolink -t commonmark -t xml
www.example.com and ^https://example.com^ and www.example.com
www.example.com and ^https://example.com^ and www.example.com
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:
$ comrak -e superscript -e subscript -e math-dollars -t commonmark -t xml
x^2^ and y~1~
x^2^ and y~1~
x^2^
and
y~1~
CJK-friendly emphasis doesn’t change superscript or subscript, since punctuation doesn’t affect their flanking:
$ comrak -e superscript -e subscript -e cjk-friendly-emphasis -t commonmark -t xml
「a」b and あいう
「a」b and あいう
「
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:
$ comrak -e superscript -e ofm-block-ids -t commonmark -t xml
a b c
a abc
a b c
a abc
a
b
c
a
abc
With description lists, a line beginning with a tilde and a space marks a description, not a tilde run:
$ comrak -e subscript -e description-lists -t commonmark -t xml
- Term
-
a2
Term
a2
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):
$ comrak -e superscript -e subscript -t commonmark -t xml
i-2 = -1.
fi = f-2 + i + f-1 + i.
i-2 = -1.
fi = f-2 + i + f-1 + i.
i
-2
= -1.
f
i
= f
-2 + i
+ f
-1 + i
.
A footnote reference doesn’t stop superscript elsewhere in the document (#274):
$ comrak -e superscript -e footnotes -t commonmark -t xml