This crate demonstrates an approach to including KaTeX in Rust docs. It tries to balance readable source code, attractive rendered output, and ease of use.

Docs with KaTeX can be generated locally and on docs.rs.

You'll only need one file: just grab katex-header.html from this project and put it into the root of your project.

This project can be documented locally with the following commands. Dependencies are documented separately because you probably don't want your dependencies' docs to use KaTeX. Also, dependencies would not build correctly because of relative paths.

cargo doc RUSTDOCFLAGS="--html-in-header katex-header.html" cargo doc --no-deps --open

Include the following snippet in your Cargo.toml :

[package.metadata.docs.rs] rustdoc-args = [ "--html-in-header", "katex-header.html" ]

Here is some inline $\KaTeX$.

And now for a fancy math expression:

$$ f(x) = \int_{-\infty}^\infty \hat f(\xi)e^{2 \pi i \xi x} d\xi $$

If your math expression has lots of Markdown special characters like _ or *, it may not render correctly because those characters will be processed by Markdown:

$$ \sum^{T-1}{t=1}x{ij} $$

To fix this, you can escape each special character by preceding it with a backslash:

$$ \sum^{T-1}_{t=1}x_{ij} $$

Somehow the section on how to not write KaTeX is longer and more complex than that on how to write KaTeX! I think it's worth it, because being able to use a single dollar sign for inline math expressions makes the source code a lot more readable.

If you try to write two dollar signs in one paragraph, your text will render as KaTeX! An example: $1.00 + $2.00 = $3.00

Dollar signs inside of code blocks are safe: $1.00 + $2.00 = $3.00 .

It's safe to write a single $ as long as there are no other dollar signs in the same HTML element. This translates to approximately one Markdown paragraph or bullet item.

If you're the kind of person who likes to write many dollar signs all in the same paragraph, you can surround each one in a <span> element: $1.00 + $2.00 = $3.00.

If you want to use your own set of delimiters, you can change that in katex-header.html . The order of the delimiters is important, so you may wish to consult the KaTeX auto-render docs and source code.

This project currently depends on KaTeX's official CDN, jsDelivr. I would also like to describe a way to bundle the JS and CSS resources into the project.