mdBook-KaTeX

mdBook-KaTeX is a preprocessor for mdBook, using KaTeX to render LaTeX math expressions.

There are two working modes:

• Pre-render Mode (default): pre-renders math expressions at build time using KaTeX,
  • no client-side JavaScript required,
  • very fast page load,
  • customizable macros and separators.
• Escape mode (experimental): escapes math expressions to be rendered using either katex.js or MathJax in the browser. May be useful if having problems building mdBook-KaTeX with quickjs.

Pre-rendering uses the katex crate. List of LaTeX functions supported by KaTeX.

Getting Started

First, install mdBook-KaTeX

Non-Windows users

cargo install mdbook-katex

Windows users

The recommended way is to download the latest x86_64-pc-windows-gnu.zip from Releases for the full functionality, otherwise, things such matrices will not work fine. See #67 for the reasons.

Another way is Escape mode.

Basic setup

Then, add the following line to your book.toml file

[preprocessor.katex]
after = ["links"]

You can now use $ and $$ delimiters for inline and display math expressions within your .md files. If you need a regular dollar symbol, you need to escape delimiters with a backslash \$.

# Chapter 1

Here is an inline example, $ \pi(\theta) $,

an equation,

$$ \nabla f(x) \in \mathbb{R}^n, $$

and a regular \$ symbol.

Math expressions will be rendered as HTML when running mdbook build or mdbook serve as usual.

Pre-render mode (default)

Pre-rendering uses the katex crate. List of LaTeX functions supported by KaTeX.

KaTeX options

Most KaTeX options are supported via the katex crate. Specify these options under [preprocessor.katex] in your book.toml:

There are also extra options to configure the behaviour of the preprocessor:

For example, the default configuration:

[preprocessor.katex]
after = ["links"]
# KaTeX options.
output = "html"
leqno = false
fleqn = false
throw-on-error = true
error-color = "#cc0000"
min-rule-thickness = -1.0
max-size = "Infinity"
max-expand = 1000
trust = false
# Extra options.
no-css = false
include-src = false
block-delimiter = { left = "$$", right = "$$" }
inline-delimiter = { left = "$", right = "$" }
pre-render = true

Self-host KaTeX CSS and fonts

KaTeX requires a stylesheet and fonts to render correctly.

By default, mdBook-KaTeX injects a KaTeX stylesheet link pointing to a CDN.

If you want to self-host the CSS and fonts instead, you should specify in book.toml:

[preprocessor.katex]
no-css = true

and manually add the CSS and fonts to your mdBook project before building it.

See mdBook-KaTeX Static CSS Example for an automated example.

Custom macros

Custom LaTeX macros must be defined in a .txt file, according to the following pattern

\grad:{\nabla}
\R:{\mathbb{R}^{#1 \times #2}}

You need to specify the path of this file in your book.toml as follows

[preprocessor.katex]
macros = "path/to/macros.txt"

These macros can then be used in your .md files

# Chapter 1

$$ \grad f(x) \in \R{n}{p} $$

Including math source

This option is added so users can have a convenient way to copy the source code of math expressions when they view the book.

When include-src is set to true, each math block is wrapped within a <data> tag with class="katex-src" with the included math source code being its value attribute.

For example, before being fed into mdBook,

Define $f(x)$:

$$
f(x)=x^2\\
x\in\R
$$

is preprocessed into (the content of the katex spans are omitted and represented as …)

Define <data class="katex-src" value="f(x)"><span class="katex">…</span></data>:

<data class="katex-src" value="&#10;f(x)=x^2\\&#10;x\in\R&#10;"><span class="katex-display"><span class="katex">…</span></span></data>

The math source code is included in a minimal fashion, and it is up to the users to write custom CSS and JavaScript to make use of it. For more information about adding custom CSS and JavaScript in mdBook, see additional-css and additional-js.

If you need more information about this feature, please check the issues or file a new issue.

Custom delimiter

To change the delimiters for math expressions, set the block-delimiter and inline-delimiter under [preprocessor.katex]. For example, to use \(and \) for inline math and \[ and \] for math block, set

[preprocessor.katex]
block-delimiter = { left = "\\[", right = "\\]" }
inline-delimiter = { left = "\\(", right = "\\)" }

Note that the double backslash above are just used to escape \ in the TOML format.

Caveats

$\backslash$ does not work, but you can use $\setminus$ instead.

Only the x86_64 Linux, Windows GNU, and macOS builds have full functionality (matrix, ...) , all other builds have compromised capabilities. See #39 for the reasons.

Escape mode (experimental)

Escapes the string needed for a formula in advance so that it remains the original formula after the markdown processor.

Disable pre-render to use "Escape mode", and provide your client-side rendering library of choice. An example with katex.js included in head.hbs (see index.hbs) is provided below.

[preprocessor.katex]
after = ["links"]
pre-render = false
no-css = true

[output.html]
theme = "theme" # use theme/head.hbs

Note that the KaTeX Options are ignored in escape mode.

An example head.hbs:

<link rel="stylesheet" href="https://unpkg.com/katex@latest/dist/katex.min.css">
<script defer src="https://unpkg.com/katex@latest/dist/katex.min.js"></script>
<script defer src="https://unpkg.com/katex@latest/dist/contrib/auto-render.min.js"></script>

<script>
document.addEventListener("DOMContentLoaded", function () {
  renderMathInElement(document.body, {
    delimiters: [
      { left: '$$', right: '$$', display: true },
      { left: '$', right: '$', display: false },
    ],
  });
});
</script>