Skip to content

A preprocessor for mdBook, rendering LaTex equations to HTML at build time.

Notifications You must be signed in to change notification settings

Matthewacon/mdbook-katex

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

98 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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 the mdbook-katex crate

cargo install mdbook-katex

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

[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 \$.

# 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:

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.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} $$

About

A preprocessor for mdBook, rendering LaTex equations to HTML at build time.

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Rust 100.0%