Math / Latex (/ Mermaid?) in Rustdoc

I'd like to inquire about the state of rendering math in rust documentation.

I'm still a bit confused after clicking my way through many different GitHub issues, but it seems that there were various requests for this over time and some attempts to make it happen but as far as I can tell none of them have panned out and all issues related to this seem to be closed? I also could not find an RFC on this. Please correct me if I missed something!! I am not sure if I truly looked everywhere (e.g. Zulip?).

From what I can gather the current solution is to inject an html header containing Katex via an environment variable (for building locally via cargo doc) and a flag in Cargo.toml like so (for crates.io):

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

Where katex-header.html is a file like referenced here. I took that crate as an example in general to make rendering math in docs work because I didn't find this process intuitive at all. Someone has mentioned katex_doc (repo) but that repo has been archived.

I'm a bit surprised at how hard it is to display math given how praised the state of documentation is in Rust, as in my opinion math is absolutely necessary to document code. Granted, the crate I would like to publish is in the space of crates that absolutely cannot be documented without using math, and I respect that not all crates are like this.

Is this still being worked on / explored?

There are efforts such as Typst and Tectonic which might offer a Rust-based solution as I got the impression that a Javascript dependency was spooking people while I was clicking through old GitHub issues.

I should give a quick mention to Mermaid.js here because while rendering math is definitely the priority, visualizing (e.g. architectural) concepts with diagrams is also very nice-to-have, although you could get away with just embedding an image here which seems to be actively worked on (Issue) (RFC)

2 Likes

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.