mdbook-katex 0.2.23

mdbook-katex is a preprocessor for mdBook, pre-rendering LaTex equations to HTML at build time. It allows for very fast page loading, compared to rendering equations in the browser.

This preprocessor uses the katex crate; see this page for the list of supported LaTex functions.

Getting Started

First, install mdbook-katex

cargo install mdbook-katex

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

[output.katex]

[preprocessor.katex]
renderers = ["html"]

You can now use $ and $$ delimiters for inline and display equations within your .md files. If you need a regular dollar symbol, you can 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.

LaTex equations will be rendered as HTML when running mdbook build or mdbook serve as usual.

Katex options

The preprocessor supports passing options to the katex-rs crate in order to configure its behaviour. These options are specified under the [preprocessor.katex] directive.

The currently spported arguments are:

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

For example:

[preprocessor.katex]
static-css = false
include-src = false

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, the included math source code is appended to each rendered math expression. Math expressions are span elements with class="katex. Appended math source code is wrapped in span elements with class="katex-src".

For example,

Define $f(x)$:

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

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

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

<span class="katex-display"><span class="katex">…</span></span><span class="katex-src"><br>f(x)=x^2\\\\<br>x\\in\\R<br></span>

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.

Caveats

The build artifact of the book will be in a folder named html inside the directory you specify instead of being directly there. Consider this when you use mdbook_katex in your CIs.

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