pandoc-katex

A pandoc filter to render math equations using KaTeX. It is powered by the katex Rust crate.

Install

cargo install pandoc-katex

When building from the source, the following dependencies are required:

• gcc and patch for Linux, macOS, and MinGW/MSYS2.
• msvc for Windows.

Alternatively, you can download the pre-built binaries from releases.

Usage

pandoc -t html --filter pandoc-katex \
  --css "https://cdn.jsdelivr.net/npm/katex@$(pandoc-katex --katex-version)/dist/katex.min.css" \
  --css "https://pandoc.org/demo/pandoc.css" \
  --standalone -o output.html /path/to/input.md

You can also pass additional flags to custom KaTeX rendering. For example, to use custom LaTeX macros:

pandoc -t json /path/to/input.md | \
  pandoc-katex --macro '\RR:\mathbb{R}' | \
  pandoc -f json -t html \
    --css "https://cdn.jsdelivr.net/npm/katex@$(pandoc-katex --katex-version)/dist/katex.min.css" \
    --css "https://pandoc.org/demo/pandoc.css" \
    --standalone -o output.html

For more flags, see pandoc-katex --help.

Configuration File

Options can also be read from an external configuration file. The configuration file should be in .toml format. For example:

fleqn = true

[macros]
"\\RR" = "\\mathbb{R}"

The configuration file path can either be passed as a command line argument --config-file /path/to/config.toml or set by environment variable PANDOC_KATEX_CONFIG_FILE.

The configuration file accepts the following options. Please refer to https://katex.org/docs/options.html for more information.

Option	Meaning	Accepted values
output_type	Set KaTeX output type.	"html", "mathml", "htmlAndMathml"
leqno	Whether to have \tags rendered on the left instead of the right.	Boolean
fleqn	Whether to make display math flush left.	Boolean
throw_on_error	Whether to let KaTeX throw a ParseError for invalid LaTeX.	Boolean
error_color	Color used for invalid LaTeX.	String
min_rule_thickness	Minimum thickness, in ems.	Float
max_size	Max size for user-specified sizes.	Float
max_expand	Limit for the number of macro expansions.	Int
trust	Whether to trust users' input.	Boolean
macros	Custom macros.	Dictionary

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}