rustdoc-katex-demo

这个crate演示了在Rust文档中包含KaTeX的方法。有关如何在您的crate中添加KaTeX的示例和说明，请参阅docs.rs上的这个crate。

许可证: MIT/Apache-2.0

lib.rs:

这个crate演示了在Rust文档中包含KaTeX的方法。它试图在可读的源代码、吸引人的渲染输出和易用性之间取得平衡。

使用KaTeX生成的文档可以在本地生成，并在docs.rs上。

设置

您只需要一个文件：只需从本项目获取katex-header.html并将其放入您项目的根目录。

本地渲染

可以使用以下命令在本项目本地生成文档。依赖项的文档是分开生成的，因为您可能不希望依赖项的文档使用KaTeX。另外，由于相对路径，依赖项可能无法正确构建。

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

在Docs.rs上渲染

在您的Cargo.toml中包含以下片段

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

如何编写KaTeX

这里有一些内联$\KaTeX$。

现在是一个花哨的数学表达式

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

如果您的数学表达式包含很多Markdown特殊字符，如_或*，它可能无法正确渲染，因为这些字符将被Markdown处理

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

要修复此问题，您可以在每个特殊字符前加一个反斜杠来转义它

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

如何不编写KaTeX

关于如何不编写KaTeX的部分似乎比如何编写KaTeX的部分更长且更复杂！我认为这是值得的，因为能够使用单个美元符号进行内联数学表达式可以使源代码更加易读。

如果您在一段文字中尝试写两个美元符号，您的文本将渲染为KaTeX！例如：$1.00 + $2.00 = $3.00

代码块内的美元符号是安全的：$1.00 + $2.00 = $3.00。

只要同一个HTML元素中没有其他美元符号，写一个美元符号就是安全的。这相当于大约一个Markdown段落或项目符号。

如果您喜欢在同一个段落中写很多美元符号，您可以在每个美元符号周围加上一个<span>元素：$1.00 + $2.00 = $3.00。

更多

如果您想使用自己的定界符集合，您可以在 katex-header.html 中进行更改。定界符的顺序很重要，因此您可能需要查阅 KaTeX 自动渲染 文档 和 源代码。

此项目目前依赖于 KaTeX 的官方 CDN，jsDelivr。我还想描述一种将 JS 和 CSS 资源打包到项目中的方法。

资源

• 在 docs.rs 上的 xss-probe：一个 Rust 包，通过使用 build.rs 在 docs.rs 构建机器上重写一些文件，将 JS 和 CSS 注入到渲染后的 docs.rs 文档中。
• curve25519-dalek 包在其自托管文档网站上包含了 精美的渲染 KaTeX。
• 在 docs.rs 上的 pwnies：一个 Rust 包，使用 --html-in-header 参数将 JS 和 CSS 注入到渲染后的 docs.rs 文档中。
• pwnies 的 GitHub 问题
• rust-num PR #226：一个使用 --html-in-header 进行 KaTeX 注入的不错示例。在该线程中，cuviper 指出了 rustdoc 中 KaTeX 几个问题
  • 我更喜欢所有资源都保持本地化，尤其是对于离线使用。KaTeX 宣称它是一个自包含的库，允许打包，因此应该可以这样做。
  • 注入有点脆弱，依赖于环境变量，并且 RUSTDOCFLAGS 甚至在稳定的 cargo 中也不受支持。这将注入到当时所有包中，而不仅仅是 num。
  • 这对于独立生成的子包（as-is）将不起作用。这对于 docs.rs 非常重要，因为在 docs.rs 中所有内容都是独立的。
  • 即使是从主包生成，如果作为其他人的文档中的依赖项生成，也可能不起作用。
• katex-doc，一个使用类似技术但实现上略有不同的包。