1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
//! 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](https://docs.rs/rustdoc-katex-demo).
//!
//! Setup
//! =====
//!
//! You'll only need one file: just grab `katex-header.html` from this project and put it into the
//! root of your project.
//!
//! ## Rendering Locally
//!
//! 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.
//!
//! ```bash
//! cargo doc
//! RUSTDOCFLAGS="--html-in-header katex-header.html" cargo doc --no-deps --open
//! ```
//!
//! ## Rendering on Docs.rs
//!
//! Include the following snippet in your `Cargo.toml`:
//!
//! ```toml
//! [package.metadata.docs.rs]
//! rustdoc-args = [ "--html-in-header", "katex-header.html" ]
//! ```
//!
//! How to Write KaTeX
//! ==================
//!
//! 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}
//! $$
//!
//!
//!
//! How to Not Write KaTeX
//! ======================
//!
//! 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: <span>$1.00</span> + <span>$2.00</span> =
//! <span>$3.00</span>.
//!
//! More
//! ====
//!
//! 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](https://katex.org/docs/autorender.html) and
//! [source code](https://github.com/Khan/KaTeX/blob/master/contrib/auto-render/auto-render.js).
//!
//! 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.
//!
//! Resources
//! =========
//!
//! - [xss-probe on docs.rs](https://docs.rs/xss-probe): a Rust crate that injects JS and CSS into
//! rendered docs.rs documentation by using `build.rs` to rewrite some files on the docs.rs build
//! machine.
//! - The curve25519-dalek crate includes
//! [lovely rendered KaTeX](https://doc-internal.dalek.rs/curve25519_dalek/curve_models/index.html)
//! on their self-hosted docs site.
//! - [pwnies on docs.rs](https://docs.rs/pwnies): a Rust crate that injects JS and CSS into
//! rendered docs.rs documentation using the `--html-in-header` argument.
//! - [GitHub issue for pwnies](https://github.com/rust-lang-nursery/docs.rs/issues/167)
//! - [rust-num PR #226](https://github.com/rust-num/num/pull/226): a nice example of KaTeX
//! injection with `--html-in-header`. In that thread, cuviper highlights a few problems with
//! KaTeX in rustdoc:
//! * I would prefer all resources stay local, especially for offline use. KaTeX advertises that
//! it is self-contained to allow bundling, so that should be possible.
//! * The injection is a bit fragile, leaning on an environment variable, and RUSTDOCFLAGS isn't
//! even supported in stable cargo. This also injects into all crates at the time, not just
//! num's.
//! * This won't work (as-is) for the sub-crates when generated independently. That's important
//! for docs.rs where everything is independent.
//! * Even from the main crate, it won't work if generated as a dependency in someone else's docs.
//! - [katex-doc](https://docs.rs/katex-doc), a crate that uses a similar technique but with a few
//! differences in implementation.