0.2.12 |
|
---|---|
0.2.11 |
|
#20 in #katex
35KB
629 lines
mdbook-katex2
aims to be a maintained version of mdbook-katex
, providing equivalent functionality.
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-katex2
cargo install mdbook-katex2
Then, add the following lines to your book.toml
file
[output.katex2]
[preprocessor.katex2]
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.
Coming from mdbook-katex
In terms of using the preprocessor, there will be no difference except you add a 2
after katex
as specified above in Getting Started.
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.katex2]
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 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.katex2]
macros = "path/to/macros.txt"
These macros can then be used in your .md
files
# Chapter 1
$$ \grad f(x) \in \R{n}{p} $$
Caveats
The build artifact of the book will be in a folder named html
inside the directory you specify instead of being directly there.
This is the same behaviour mdbook_katex
has. Consider this when you use mdbook_katex2
in your CIs.
$\backslash$
does not work, but you can use $\setminus$
instead.
Acknowledgements
mdbook-katex
was developed by Lucas Zanini et. al., see the original repository for all the individual contributions.
Dependencies
~20–35MB
~587K SLoC