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:

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:

Example 1
$ comrak -e math-dollars
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:

Example 2
$ comrak -e math-dollars
$a^2 + b^2 = c^2$

A $ followed by whitespace can’t begin inline maths:

Example 3
$ comrak -e math-dollars
$ 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:

Example 4
$ comrak -e math-dollars
$x $
Example 5
$ comrak -e math-dollars
$a$1
Example 6
$ comrak -e math-dollars
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:

Example 7
$ comrak -e math-dollars
$a $b$

Inline maths may begin and end inside a word:

Example 8
$ comrak -e math-dollars
a$x$b

The first $ of a $$ run can close inline maths. The second is literal text:

Example 9
$ comrak -e math-dollars
$x$$

Inline maths may span lines, and keeps its line endings, but can’t span paragraphs:

Example 10
$ comrak -e math-dollars
$a
b$
Example 11
$ comrak -e math-dollars
$a

b$

Display dollar maths

Display dollar maths begins with $$ and ends at the next unescaped $$:

Example 12
$ comrak -e math-dollars
$$x = y + 2$$

Its content may begin or end with whitespace, and may contain a single $:

Example 13
$ comrak -e math-dollars
$$ x = \$1 $$
Example 14
$ comrak -e math-dollars
$$a$b$$

Display maths may span lines, but can’t span paragraphs. Without block maths, it remains inside its paragraph:

Example 15
$ comrak -e math-dollars
Hence
$$
x = y
$$
Example 16
$ comrak -e math-dollars
$$
x

y
$$

A run of three or more dollar signs can’t begin maths:

Example 17
$ comrak -e math-dollars
$$$x$$$

A $$ run begins only display maths. If no $$ closes it, it’s literal text, instead of a dollar sign followed by inline maths:

Example 18
$ comrak -e math-dollars
$$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:

Example 19
$ comrak -e math-dollars
$*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:

Example 20
$ comrak -e math-dollars
$\text{\$}5$
Example 21
$ comrak -e math-dollars
$$\$$$

A backslash escapes a dollar sign only if the backslash isn’t itself escaped. \\ is a line break in TeX; \\$ closes maths:

Example 22
$ comrak -e math-dollars
$a\\$ b$

Precedence

Dollar maths and code spans take precedence by position: whichever begins first wins:

Example 23
$ comrak -e math-dollars
$x `y$ z`
Example 24
$ comrak -e math-dollars
`a $b` c$

Dollar maths takes precedence over emphasis and links that begin before it but end inside it:

Example 25
$ comrak -e math-dollars
*$x*$*
Example 26
$ comrak -e math-dollars
[$x]/u$

Raw HTML that begins first takes precedence over dollar maths:

Example 27
$ comrak -e math-dollars --unsafe
<a title="$x">$</a>

A backslash escape or an entity reference is a literal dollar sign, which can’t begin or end maths:

Example 28
$ comrak -e math-dollars
\$x$
Example 29
$ comrak -e math-dollars
&#36;x&#36;

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:

Example 30
$ comrak -e math-dollars
$$
1
=
2
$$

With block maths, the same lines are display maths:

Example 31
$ comrak -e math-dollars -e math-dollars-block
$$
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:

Example 32
$ comrak -e math-dollars -e math-dollars-block
$$
# 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:

Example 33
$ comrak -e math-dollars -e math-dollars-block
  $$
  x
    y
z
  $$

Four spaces of indentation begin an indented code block instead:

Example 34
$ comrak -e math-dollars -e math-dollars-block
    $$
    x
    $$

A line with anything else after $$ isn’t a maths fence. This includes a run of three or more dollar signs:

Example 35
$ comrak -e math-dollars -e math-dollars-block
$$
x
$$ y
$$
Example 36
$ comrak -e math-dollars -e math-dollars-block
$$$
x
$$$

A maths fence may interrupt a paragraph:

Example 37
$ comrak -e math-dollars -e math-dollars-block
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:

Example 38
$ comrak -e math-dollars -e math-dollars-block
$$ x
y
$$

Without a closing fence, block maths ends with its container. Unlike a paragraph, it has no lazy continuation lines:

Example 39
$ comrak -e math-dollars -e math-dollars-block
> $$
> x
y

A line holding display dollar maths and nothing else isn’t a maths fence, so the display maths stays in its paragraph:

Example 40
$ comrak -e math-dollars -e math-dollars-block
$$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:

Example 41
$ comrak -e math-latex
\(x\) and \[ y = 2 \]

Without math-latex, \( and \[ are backslash escapes. With it, text that escapes brackets may become maths:

Example 42
$ comrak -e math-latex
\[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:

Example 43
$ comrak -e math-latex
\(\) and \[\]
Example 44
$ comrak -e math-latex
\(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:

Example 45
$ comrak -e math-latex
\(a\\)b\)

LaTeX maths doesn’t nest. The first closing delimiter closes it:

Example 46
$ comrak -e math-latex
\(a\(b\)c\)

LaTeX maths may span lines, but can’t span paragraphs:

Example 47
$ comrak -e math-latex
\[
a
\]
Example 48
$ comrak -e math-latex
\(a

b\)

LaTeX maths and code spans take precedence by position, as dollar maths does:

Example 49
$ comrak -e math-latex
\(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:

Example 50
$ comrak -e math-code
$`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:

Example 51
$ comrak -e math-code
$` x `$ and $`a
b`$

Longer backtick strings let the content contain backticks:

Example 52
$ comrak -e math-code
$``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:

Example 53
$ comrak -e math-code
$`a`b`$
Example 54
$ comrak -e math-code
$`x` and `y`$
Example 55
$ comrak -e math-code
$ `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:

Example 56
$ comrak -e math-code
```math
a^2 + b^2 = c^2
```
Example 57
$ comrak -e math-code
~~~math foo
x
~~~

The word is case-sensitive:

Example 58
$ comrak -e math-code
```Math
x
```

Without math-code, a code block marked math is an ordinary code block:

Example 59
$ comrak -e math-dollars
```math
x
```

Output

HTML output marks each kind of maths with a data-math-style attribute, whose value is inline or display:

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>:

Example 60
$ comrak -e math-code --github-pre-lang
```math
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>:

Example 61
$ comrak -e math-code -e fenced-code-attributes --full-info-string --attributes --unsafe
```math numbered {#pythagoras}
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:

Example 62
$ comrak -e math-dollars -e math-latex
\(x\) and \( y\)

CommonMark output also escapes dollar signs in text, to stop them reading back as maths:

Example 63
$ comrak -e math-dollars
$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:

Example 64
$ comrak -e math-dollars -e math-code --sourcepos
a $x$ and $`y`$

Interactions

The maths extensions work together:

Example 65
$ comrak -e math-dollars -e math-code -e math-latex
$x$ and $`y`$ and \(z\)

With both math-dollars and math-code, a dollar sign followed by a backtick can only begin code maths:

Example 66
$ comrak -e math-dollars -e math-code
$`x` + y$

--gfm doesn’t enable any maths syntax:

Example 67
$ comrak --gfm
$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:

Example 68
$ comrak -e math-dollars --smart
$a--b "c"$ -- "d"

With autolinks, dollar signs in a URL are part of it:

Example 69
$ comrak -e math-dollars -e autolink
https://example.com/$x$

In image descriptions, maths contributes its content to the alt text:

Example 70
$ comrak -e math-dollars
![$x$ squared]/x2.png

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:

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):

Example 71
$ comrak -e math-dollars
$\alpha$$\beta$

Source positions are correct for maths that spans lines (#855):

Example 72
$ comrak -e math-dollars --sourcepos
a $x
y$ b

CommonMark output escapes literal dollar signs, and literal brackets when math-latex is enabled (#917):

Example 73
$ comrak -e math-dollars
a \$x$ b
Example 74
$ comrak -e math-latex
\[x\] [y]