Maths extensions mark up mathematical notation, written in TeX, for a renderer such as KaTeX or MathJax to typeset in the browser. Comrak doesn’t typeset maths itself. It finds the maths in a document, keeps its content as literal text, and marks it in the HTML output with a data-math-style attribute.
Comrak supports four maths syntaxes, each with its own extension:
math-dollars:$…$and$$…$$, following Pandoc;math-dollars-block:$$on lines of their own, for display maths that contains blank lines or lines that look like Markdown;math-latex: LaTeX’s\(…\)and\[…\]; and,math-code:$`…`$and code blocks markedmath, following GitLab and GitHub.
This document describes all four. GitLab uses Comrak’s dollar maths and code maths, so this document is also the canonical spec for GitLab Flavored Markdown maths.
To enable a maths syntax, pass -e math-dollars, -e math-dollars-block, -e math-latex or -e math-code on the command line, or set extension.math_dollars, extension.math_dollars_block, extension.math_latex or extension.math_code in the options struct. Block maths also needs math-dollars.
Here’s some typical dollar maths:
$ comrak -e math-dollars -t commonmark -t xml
Let x and y be integers such that x = y + 2
Let x and y be integers such that
x = y + 2
Let
x
and
y
be integers such that
x = y + 2
Each syntax produces inline maths, which sits within a line of text, or display maths, which a renderer sets apart on a line of its own. In this document, whitespace means a space, a tab, a line ending, a vertical tab or a form feed.
Dollar maths
With math-dollars, a single dollar sign ($) delimits inline maths, and two ($$) delimit display maths. A run of three or more dollar signs can’t begin maths.
Inline dollar maths
Inline dollar maths begins with a $ that isn’t followed by whitespace. Its content runs to the next unescaped $, which closes it:
$ comrak -e math-dollars -t commonmark -t xml
a^2 + b^2 = c^2
a^2 + b^2 = c^2
a^2 + b^2 = c^2
A $ followed by whitespace can’t begin inline maths:
$ comrak -e math-dollars -t commonmark -t xml
$ x$
$ x$
$ x$
The $ that would close inline maths must not be preceded by whitespace, or followed by an ASCII digit (0–9). Otherwise, the opening $ is literal text:
$ comrak -e math-dollars -t commonmark -t xml
$x $
$x $
$x $
$ comrak -e math-dollars -t commonmark -t xml
$a$1
$a$1
$a$1
$ comrak -e math-dollars -t commonmark -t xml
It costs $20,000 or $30,000.
It costs $20,000 or $30,000.
It costs $20,000 or $30,000.
Only the next unescaped $ can close inline maths. If it can’t, a later $ doesn’t either. Here, the first $ is literal, and the second begins inline maths:
$ comrak -e math-dollars -t commonmark -t xml
$a b
$a b
$a
b
Inline maths may begin and end inside a word:
$ comrak -e math-dollars -t commonmark -t xml
axb
axb
a
x
b
The first $ of a $$ run can close inline maths. The second is literal text:
$ comrak -e math-dollars -t commonmark -t xml
x$
x$
x
$
Inline maths may span lines, and keeps its line endings, but can’t span paragraphs:
$ comrak -e math-dollars -t commonmark -t xml
a b
a
b
a
b
$ comrak -e math-dollars -t commonmark -t xml
$a
b$
$a
b$
$a
b$
Display dollar maths
Display dollar maths begins with $$ and ends at the next unescaped $$:
$ comrak -e math-dollars -t commonmark -t xml
x = y + 2
x = y + 2
x = y + 2
Its content may begin or end with whitespace, and may contain a single $:
$ comrak -e math-dollars -t commonmark -t xml
x = \$1
x = \$1
x = \$1
$ comrak -e math-dollars -t commonmark -t xml
a$b
a$b
a$b
Display maths may span lines, but can’t span paragraphs. Without block maths, it remains inside its paragraph:
$ comrak -e math-dollars -t commonmark -t xml
Hence x = y
Hence
x = y
Hence
x = y
$ comrak -e math-dollars -t commonmark -t xml
$$ x
y $$
$$
x
y
$$
$$
x
y
$$
A run of three or more dollar signs can’t begin maths:
$ comrak -e math-dollars -t commonmark -t xml
$$$x$$$
$$$x$$$
$$$x$$$
A $$ run begins only display maths. If no $$ closes it, it’s literal text, instead of a dollar sign followed by inline maths:
$ comrak -e math-dollars -t commonmark -t xml
$$x$
$$x$
$$x$
Content
The content of dollar maths is literal text. Comrak doesn’t parse Markdown, raw HTML or entity references in it, and keeps any backslashes as-is:
$ comrak -e math-dollars -t commonmark -t xml
*a* <b> & \alpha
*a* <b> &amp; \alpha
*a* <b> &amp; \alpha
A backslash before a dollar sign stops that dollar sign closing the maths. The backslash stays in the content, for the renderer to interpret:
$ comrak -e math-dollars -t commonmark -t xml
\text{\$}5
\text{\$}5
\text{\$}5
$ comrak -e math-dollars -t commonmark -t xml
\$
\$
\$
A backslash escapes a dollar sign only if the backslash isn’t itself escaped. \\ is a line break in TeX; \\$ closes maths:
$ comrak -e math-dollars -t commonmark -t xml
a\\ b$
a\\ b$
a\\
b$
Precedence
Dollar maths and code spans take precedence by position: whichever begins first wins:
$ comrak -e math-dollars -t commonmark -t xml
x `y z`
x `y z`
x `y
z`
$ comrak -e math-dollars -t commonmark -t xml
a $b c$
a $b c$
a $b
c$
Dollar maths takes precedence over emphasis and links that begin before it but end inside it:
$ comrak -e math-dollars -t commonmark -t xml
x*
x*
x*
$ comrak -e math-dollars -t commonmark -t xml
[x](/u)
[x](/u)
[
x](/u)
Raw HTML that begins first takes precedence over dollar maths:
$ comrak -e math-dollars --unsafe -t commonmark -t xml
A backslash escape or an entity reference is a literal dollar sign, which can’t begin or end maths:
$ comrak -e math-dollars -t commonmark -t xml
$x$
$x$
$x$
$ comrak -e math-dollars -t commonmark -t xml
$x$
$x$
$x$
Block maths
With math-dollars-block, a line holding only $$ begins and ends display maths that may contain blank lines, and lines that would otherwise be Markdown. Block maths needs math-dollars.
Block maths came from #880. Display dollar maths lives inside a paragraph, so a line of = in it underlines a setext heading:
$ comrak -e math-dollars -t commonmark -t xml
$$ 1
2 $$
$$
1
2
$$
$$
1
2
$$
With block maths, the same lines are display maths:
$ comrak -e math-dollars -e math-dollars-block -t commonmark -t xml
1
=
2
1
=
2
A maths fence is a line holding $$, after up to three spaces of indentation, followed by nothing but spaces and tabs. Block maths begins with a maths fence, and ends with the next maths fence, or at the end of its container. Its content is literal:
$ comrak -e math-dollars -e math-dollars-block -t commonmark -t xml
-
# x
- y &amp; z
-
# x
- y &amp; z
Comrak removes as much indentation from each content line as the opening fence had, up to the amount the line has:
$ comrak -e math-dollars -e math-dollars-block -t commonmark -t xml
$$
x
x
y
z
$$
x
z
$$
x
y
z
Four spaces of indentation begin an indented code block instead:
$ comrak -e math-dollars -e math-dollars-block -t commonmark -t xml
$$
x
$$
$$
x
$$
$$
x
$$
A line with anything else after $$ isn’t a maths fence. This includes a run of three or more dollar signs:
$ comrak -e math-dollars -e math-dollars-block -t commonmark -t xml
x
$$ y
x
$$ y
$ comrak -e math-dollars -e math-dollars-block -t commonmark -t xml
$$$ x $$$
$$$
x
$$$
$$$
x
$$$
A maths fence may interrupt a paragraph:
$ comrak -e math-dollars -e math-dollars-block -t commonmark -t xml
a
b
a
x
b
a
x
b
A maths fence always begins block maths, even where it would otherwise close display dollar maths. Here, the last line begins block maths, so $$ x stays literal text, and the block maths runs to the end of the document:
$ comrak -e math-dollars -e math-dollars-block -t commonmark -t xml
$$ x y
$$ x
y
$$ x
y
Without a closing fence, block maths ends with its container. Unlike a paragraph, it has no lazy continuation lines:
$ comrak -e math-dollars -e math-dollars-block -t commonmark -t xml
x
y
x
y
x
y
A line holding display dollar maths and nothing else isn’t a maths fence, so the display maths stays in its paragraph:
$ comrak -e math-dollars -e math-dollars-block -t commonmark -t xml
x
x
x
LaTeX delimiters
With math-latex, \( and \) delimit inline maths, and \[ and \] delimit display maths, as in LaTeX. The extension came from #469.
LaTeX maths begins with \( or \[, and ends at the next unescaped \) or \] respectively. Its content is literal text, and may begin or end with whitespace:
$ comrak -e math-latex -t commonmark -t xml
x and y = 2
x and y = 2
x
and
y = 2
Without math-latex, \( and \[ are backslash escapes. With it, text that escapes brackets may become maths:
$ comrak -e math-latex -t commonmark -t xml
x(/u)
x(/u)
x
(/u)
When LaTeX maths can’t form, its opening \( or \[ is a backslash escape after all. This happens when the content would be empty, or when there’s no closing delimiter of the same kind:
$ comrak -e math-latex -t commonmark -t xml
() and []
() and []
() and []
$ comrak -e math-latex -t commonmark -t xml
(x]
(x]
(x]
A backslash escapes a closing delimiter only if the backslash isn’t itself escaped. \\ is a line break in TeX, and so doesn’t close maths:
$ comrak -e math-latex -t commonmark -t xml
a\\)b
a\\)b
a\\)b
LaTeX maths doesn’t nest. The first closing delimiter closes it:
$ comrak -e math-latex -t commonmark -t xml
a\(bc)
a\(bc)
a\(b
c)
LaTeX maths may span lines, but can’t span paragraphs:
$ comrak -e math-latex -t commonmark -t xml
a
a
a
$ comrak -e math-latex -t commonmark -t xml
(a
b)
(a
b)
(a
b)
LaTeX maths and code spans take precedence by position, as dollar maths does:
$ comrak -e math-latex -t commonmark -t xml
a `b c`
a `b c`
a `b
c`
Code maths
With math-code, a code span or a fenced code block can hold maths. GitLab and GitHub both support this syntax.
Inline code maths
Inline code maths is a code span with a dollar sign immediately before its opening backtick string and immediately after its closing backtick string:
$ comrak -e math-code -t commonmark -t xml
a^2 + b^2 = c^2
a^2 + b^2 = c^2
a^2 + b^2 = c^2
Its content follows the rules for code spans. Comrak turns line endings into spaces, and strips one space from each end if both ends have one:
$ comrak -e math-code -t commonmark -t xml
x and a b
x and a b
x
and
a b
Longer backtick strings let the content contain backticks:
$ comrak -e math-code -t commonmark -t xml
a`b
a`b
a`b
Without a dollar sign on both sides, a code span isn’t code maths, and its dollar signs are literal text. Here, the code span ends at the first backtick, so no dollar sign follows it:
$ comrak -e math-code -t commonmark -t xml
$ab`$
$ab`$
$
a
b`$
$ comrak -e math-code -t commonmark -t xml
$x and y$
$x and y$
$
x
and
y
$
$ comrak -e math-code -t commonmark -t xml
$ x$
$ x$
$
x
$
Maths code blocks
A fenced code block whose info string begins with the word math is display maths. The rest of the info string doesn’t affect whether the block is maths:
$ comrak -e math-code -t commonmark -t xml
a^2 + b^2 = c^2
a^2 + b^2 = c^2
a^2 + b^2 = c^2
$ comrak -e math-code -t commonmark -t xml
x
x
x
The word is case-sensitive:
$ comrak -e math-code -t commonmark -t xml
x
x
x
Without math-code, a code block marked math is an ordinary code block:
$ comrak -e math-dollars -t commonmark -t xml
x
x
x
Output
HTML output marks each kind of maths with a data-math-style attribute, whose value is inline or display:
- dollar maths and LaTeX maths use a
<span>; - inline code maths uses a
<code>; - block maths uses a
<div>, with its content starting on the line after the opening tag; and, - a maths code block uses
<pre><code class="language-math">, with the attribute on the<code>.
In each case, Comrak escapes the content as HTML text. The rendered examples on this page use KaTeX to typeset it.
With --github-pre-lang, a maths code block puts both lang and data-math-style on the <pre>:
$ comrak -e math-code --github-pre-lang -t commonmark -t xml
x
x
x
Otherwise, a maths code block takes the same attributes as any other code block. With --full-info-string, the rest of the info string becomes a data-meta attribute beside data-math-style, and fenced code attributes go on the <pre>:
$ comrak -e math-code -e fenced-code-attributes --full-info-string --attributes --unsafe -t commonmark -t xml
a^2 + b^2 = c^2
a^2 + b^2 = c^2
a^2 + b^2 = c^2
With math-code, Comrak renders maths code blocks itself, ignoring any codefence renderer for math. Without it, a codefence renderer for math handles those blocks as it would any other.
CommonMark output writes dollar maths with dollar signs, block maths with maths fences, and code maths with enough backticks to hold its content. The AST doesn’t record whether maths came from dollar signs or LaTeX delimiters. When math-latex is enabled, CommonMark output uses LaTeX delimiters if math-dollars isn’t enabled, or if dollar signs wouldn’t read back as the same maths, such as inline maths that begins with a space:
$ comrak -e math-dollars -e math-latex -t commonmark -t xml
x and y
x and y
x
and
y
CommonMark output also escapes dollar signs in text, to stop them reading back as maths:
$ comrak -e math-dollars -t commonmark -t xml
x costs $5.
x costs $5.
x
costs $5.
In XML output, dollar maths, LaTeX maths and inline code maths are math elements, with a math_style attribute of inline or display. Block maths is a math_block element. A maths code block is a code_block element with math_style="display".
In the AST, dollar maths, LaTeX maths and inline code maths are a NodeValue::Math. Its NodeMath holds the content, display_math, and dollar_math, which is false for code maths and true otherwise. Block maths is a NodeValue::MathBlock, and a maths code block is a NodeValue::CodeBlock.
The source position of maths covers its delimiters:
$ comrak -e math-dollars -e math-code --sourcepos -t commonmark -t xml
a x and y
a x and y
a
x
and
y
Interactions
The maths extensions work together:
$ comrak -e math-dollars -e math-code -e math-latex -t commonmark -t xml
x and y and z
x and y and z
x
and
y
and
z
With both math-dollars and math-code, a dollar sign followed by a backtick can only begin code maths:
$ comrak -e math-dollars -e math-code -t commonmark -t xml
$x + y$
$x + y$
$
x
+ y$
--gfm doesn’t enable any maths syntax:
$ comrak --gfm -t commonmark -t xml
$x$
$x$
$x$
With tables, a pipe in maths still ends a cell, unless it’s escaped. The tables page covers this.
With smart punctuation, maths content stays as it is:
$ comrak -e math-dollars --smart -t commonmark -t xml
a--b "c" – “d”
a--b "c" – “d”
a--b "c"
– “d”
With autolinks, dollar signs in a URL are part of it:
$ comrak -e math-dollars -e autolink -t commonmark -t xml
In image descriptions, maths contributes its content to the alt text:
$ comrak -e math-dollars -t commonmark -t xml

x
squared
With attributes, inline code maths doesn’t take attributes, but a maths code block does, as Output shows. The attributes page covers both.
Differences from Pandoc and GitHub
Pandoc 3.7 supports dollar maths in its commonmark reader (commonmark+tex_math_dollars), LaTeX delimiters in its markdown reader (markdown+tex_math_single_backslash), and code maths in its gfm reader. It has no block maths. Setting aside how each writes line breaks and code blocks in HTML, Comrak and Pandoc produce the same HTML for every example above that Pandoc supports, except in these cases:
- A closing
$followed by a digit doesn’t close inline maths in Comrak (example 5). Pandoc’smarkdownreader has this rule, but itscommonmarkreader doesn’t. - In Comrak, a run of three or more dollar signs can’t begin maths, and a
$$run can begin only display maths (example 17, example 18). Pandoc reads$$$x$$$as a dollar sign, display maths and a dollar sign, and$$x$as a dollar sign followed by inline maths. - Comrak reads
$$a$b$$as display maths that containsa$b(example 14). Pandoc reads a dollar sign, inline maths that containsa, and the textb$$. - Pandoc’s code maths keeps its content as written, and ends at the first backtick followed by a dollar sign (example 51, example 53, example 54). Comrak follows the rules for code spans, as GitHub does.
- With dollar maths and code maths both enabled, a dollar sign followed by a backtick can only begin code maths in Comrak (example 65). Pandoc reads it as the start of dollar maths.
Pandoc also trims whitespace from both ends of inline LaTeX maths, so \( x \) holds x. Comrak keeps the spaces.
GitHub supports dollar maths and code maths. Its dollar maths differs too much from Comrak’s for a useful comparison: it parses Markdown inside dollar maths, and renders $$…$$ within a line as inline maths. Its code maths matches Comrak’s on every example above, except example 54, where GitHub turns the text between the two code spans into maths.
Regressions
The following examples guard against regressions.
Inline maths may immediately follow inline maths (#533):
$ comrak -e math-dollars -t commonmark -t xml
\alpha\beta
\alpha\beta
\alpha
\beta
Source positions are correct for maths that spans lines (#855):
$ comrak -e math-dollars --sourcepos -t commonmark -t xml
a x y b
a x
y b
a
x
y
b
CommonMark output escapes literal dollar signs, and literal brackets when math-latex is enabled (#917):
$ comrak -e math-dollars -t commonmark -t xml
a $x$ b
a $x$ b
a $x$ b
$ comrak -e math-latex -t commonmark -t xml
x [y]
x [y]
x
[y]