KaTeX is a fast, easy-to-use JavaScript library for TeX math rendering on the web. It supports much (but not all) of LaTeX and many LaTeX packages. See the list of supported functions.

Usage

Equations are generally written between $ token, or between \( and \) tokens:

The formula $E=mc^2$ defines the energy $E$ of a particle in its rest frame as the product of mass ($m$) with the speed of light squared ($c^2$).

The formula \(E=mc^2\) defines the energy \(E\) of a particle in its rest frame as the product of mass (\(m\)) with the speed of light squared (\(c^2\)).

Which will render to:

To display stand-alone equations on their own line, use $$ token, or \[ and \] tokens:

$$ a^{2a} + b^{2b} + c^{2c} \ge a^{2b} + b^{2c} + c^{2a} $$

\[ a^{2a} + b^{2b} + c^{2c} \ge a^{2b} + b^{2c} + c^{2a} \]

Which will render to:

Common Issues

HTML

Be careful when writing literal &, <, and > characters in HTML. Those characters are reserved in HTML syntax. Be sure to encode them into &, <, and > so that they won’t have the potential to damage the document:

<ul>
  <li>The notation $a &lt; b$ means that $a$ is <strong>less than</strong> $b$.</li>
  <li>The notation $a &gt; b$ means that $a$ is <strong>greater than</strong> $b$.</li>
</ul>

Another way is to use the alternative expressions of those characters in KaTeX:

<ul>
  <li>The notation $a \lt b$ means that $a$ is <strong>less than</strong> $b$.</li>
  <li>The notation $a \gt b$ means that $a$ is <strong>greater than</strong> $b$.</li>
</ul>

In Markdown syntax (and perhaps in other HTML pre-processor syntax as well), those characters are usually automatically encoded if they are not properly tokenized into HTML elements. However, HTML pre-processors usually also have certain writing rules for special characters that do not necessarily need to be encoded when written in a raw HTML document.

Markdown

The $ and $$ delimiters are currently safe delimiters to write as it is in Markdown because they have no special role in Markdown syntax. However, it is highly recommended that characters such as \ and _ be escaped by preceding them with the \ character so that they will appear as their literal character when successfully converted to HTML:

- The notation $a \\lt b$ means that $a$ is **less than** $b$.
- The notation $a \\gt b$ means that $a$ is **greater than** $b$.

But it wouldn’t hurt to escape the $ character as well, because we don’t consider it to be part of the Markdown syntax, but rather just a piece of plain text in a HTML element that will later be parsed by KaTeX on the client side:

- The notation \$a \\lt b\$ means that \$a\$ is **less than** \$b\$.
- The notation \$a \\gt b\$ means that \$a\$ is **greater than** \$b\$.

Some external Markdown parsers may have special extensions that treat $…$ token as KaTeX token, so that the text in it does not need to be escaped as in Markdown’s code syntax. However, Mecha has chosen to use its own Markdown parser, which is more stable and conforms to the CommonMark specification, so it does not support the creation of new Markdown syntax.

It can be tuned with a hook that can automatically double encode the special characters between the KaTeX tokens before they are converted to HTML, but this requires a pretty complicated tokenization because we need to ignore special characters in the code syntax, and we also need to ignore those that appear in the lines just below the raw HTML block tokens ¹

There are some ways to write the KaTeX syntax as it is (and to escape the KaTeX syntax in Markdown properly), but not by writing it in Markdown’s code syntax (the text in it will be ignored by KaTeX, so it won’t turn into mathematical equations):

Markdown Escapes

Special characters in Markdown can be rendered as they are when converted to HTML by preceding each character with the back-slash character:

- The notation \$a \\lt b\$ means that \$a\$ is **less than** \$b\$.
- The notation \$a \\gt b\$ means that \$a\$ is **greater than** \$b\$.

HTML Escapes

HTML entities that are equivalent to those characters can also be used, as they will be converted to their character literals in HTML (at least by my Markdown parser):

- The notation $a \lt b$ means that $a$ is **less than** $b$.
- The notation $a \gt b$ means that $a$ is **greater than** $b$.

- The notation $a \lt b$ means that $a$ is **less than** $b$.
- The notation $a \gt b$ means that $a$ is **greater than** $b$.

HTML Blocks

By writing the KaTeX syntax right after the HTML block token, it is not considered as part of the Markdown ², so you can write KaTeX syntax as it is in this situation:

<ul>
<li>The notation $a \lt b$ means that $a$ is <strong>less than</strong> $b$.</li>
<li>The notation $a \gt b$ means that $a$ is <strong>greater than</strong> $b$.</li>
</ul>

<ul>
<li>
The notation $a \lt b$ means that $a$ is <strong>less than</strong> $b$.
</li>
<li>
The notation $a \gt b$ means that $a$ is <strong>greater than</strong> $b$.
</li>
</ul>

This one is ugly, but it conforms to this CommonMark specification:

- The notation
  <span>
  $a \lt b$</span> means that <span>$a$</span> is <strong>less than</strong> <span>$b$</span>.
- The notation
  <span>
  $a \gt b$</span> means that <span>$a$</span> is <strong>greater than</strong> <span>$b$</span>.