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.
First, install mdbook-katex
shell
cargo install mdbook-katex
Then, add the following lines to your book.toml file
```toml [output.katex]
[preprocessor.katex] ```
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 \$.
```
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.
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:
| Argument | Type |
| :- | :- |
| leqno | boolean |
| fleqn | boolean |
| throw-on-error | boolean |
| error-color | string |
| min-rule-thickness | number |
| max-size | number |
| max-expand | number |
| trust | boolean |
There are also options to configure the behaviour of the preprocessor:
| Option | Default | Description |
| :- | :- | :- |
| static-css | false | Generates fully static html pages with katex styling |
| macros | None | Path to macros file (see Custom macros) |
Custom LaTex macros must be defined in a .txt file, according to the following pattern
txt
\grad:{\nabla}
\R:{\mathbb{R}^{#1 \times #2}}
You need to specify the path of this file in your book.toml as follows
toml
[preprocessor.katex]
macros = "path/to/macros.txt"
These macros can then be used in your .md files
```
$$ \grad f(x) \in \R{n}{p} $$ ```
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.