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
-
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. See #67 for the reasons.
Then, add the following line to your book.toml
file
[]
= ["links"]
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.
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 supported arguments are:
Argument | Type |
---|---|
output |
string |
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 |
---|---|---|
no-css |
false |
Do not inject KaTeX stylesheet link (See Self-host KaTeX CSS and fonts) |
macros |
None |
Path to macros file (see Custom macros) |
include-src |
false |
Include math expressions source code (See Including math Source) |
block-delimiter |
{left = "$$", right = "$$"} |
See Custom delimiter |
inline-delimiter |
{left = "$", right = "$"} |
See Custom delimiter |
static-css |
false |
(Deprecated) Generates fully static html pages with katex styling |
For example:
[]
= ["html"]
= false
= false
= { = "$$", = "$$"}
= { = "$", = "$"}
Self-host KaTeX CSS and fonts
KaTeX requires a stylesheet and fonts to render correctly.
By default, mdbook-katex
inject 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
:
[]
= true
and manually add the CSS and fonts to your mdBook project before build.
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
[]
= "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
span
s are omitted and represented as …
)
Define <data class="katex-src" value="f(x)"><span class="katex">…</span></data>:
<data class="katex-src" value="
f(x)=x^2\\
x\in\R
"><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
[]
= { = "\\[", = "\\]"}
= { = "\\(", = "\\)"}
Notice 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, all other builds have compromised capabilities. See #39 for the reasons.
If you specify [output.katex]
, 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.