mdBook-KaTeX

mdBook-KaTeX 是一个用于 mdBook 的预处理器，使用 KaTeX 渲染 LaTeX 数学表达式。

有两种工作模式

• 预渲染模式（默认）：在构建时使用 KaTeX 预渲染数学表达式，
  • 无需客户端 JavaScript，
  • 非常快速的页面加载，
  • 可自定义宏和分隔符。
• 转义模式（实验性）：将数学表达式转义，以便在浏览器中使用 katex.js 或 MathJax 进行渲染。如果在构建 mdBook-KaTeX 时遇到 quickjs 问题，这可能很有用。

预渲染使用 katex crate。 KaTeX 支持的 LaTeX 函数列表。

入门指南

首先，安装 mdBook-KaTeX

非 Windows 用户

cargo install mdbook-katex

Windows 用户

推荐的方法是从 发布版 下载最新的 x86_64-pc-windows-gnu.zip，以获得完整的功能，否则，如矩阵等事物可能无法正常工作。有关原因，请参阅 #67。

另一种方法是 转义模式。

基本设置

然后，将以下行添加到您的 book.toml 文件中

[preprocessor.katex]
after = ["links"]

现在您可以在.md文件中使用$和$$作为行内和显示数学表达式的定界符。如果您需要普通的美元符号，您需要用反斜杠转义定界符\$。

# Chapter 1

Here is an inline example, $ \pi(\theta) $,

an equation,

$$ \nabla f(x) \in \mathbb{R}^n, $$

and a regular \$ symbol.

在运行mdbook build或mdbook serve时，数学表达式将像往常一样被渲染为HTML。

预渲染模式（默认）

预渲染使用 katex crate。 KaTeX 支持的 LaTeX 函数列表。

KaTeX选项

大多数KaTeX选项通过katex包支持。在您的book.toml文件中的[preprocessor.katex]下指定这些选项

还有额外的选项来配置预处理器的行为

例如，默认配置

[preprocessor.katex]
after = ["links"]
# KaTeX options.
output = "html"
leqno = false
fleqn = false
throw-on-error = true
error-color = "#cc0000"
min-rule-thickness = -1.0
max-size = "Infinity"
max-expand = 1000
trust = false
# Extra options.
no-css = false
include-src = false
block-delimiter = { left = "$$", right = "$$" }
inline-delimiter = { left = "$", right = "$" }
pre-render = true

自托管KaTeX CSS和字体

KaTeX需要样式表和字体才能正确渲染。

默认情况下，mdBook-KaTeX会注入指向CDN的KaTeX样式表链接。

如果您想自托管CSS和字体，请在book.toml

[preprocessor.katex]
no-css = true

中指定，并在构建之前手动将CSS和字体添加到您的mdBook项目中。

见mdBook-KaTeX静态CSS示例以获取自动化的示例。

自定义宏

自定义LaTeX宏必须在遵循以下模式的.txt文件中定义

\grad:{\nabla}
\R:{\mathbb{R}^{#1 \times #2}}

您需要按照以下方式在您的book.toml中指定该文件的路径

[preprocessor.katex]
macros = "path/to/macros.txt"

然后，这些宏可以在您的.md文件中使用

# Chapter 1

$$ \grad f(x) \in \R{n}{p} $$

包含数学源

此选项添加是为了让用户在查看书籍时能够方便地复制数学表达式的源代码。

当include-src设置为true时，每个数学块都包裹在一个带有class="katex-src"的<data>标签中，其中包含的数学源代码是其value属性。

例如，在喂入mdBook之前

Define $f(x)$:

$$
f(x)=x^2\\
x\in\R
$$

被预处理成（省略了katex span的内容，并以…表示）

Define <data class="katex-src" value="f(x)"><span class="katex">…</span></data>:

<data class="katex-src" value="&#10;f(x)=x^2\\&#10;x\in\R&#10;"><span class="katex-display"><span class="katex">…</span></span></data>

数学源代码以最小化方式包含，用户需要自行编写自定义CSS和JavaScript以利用它。有关在mdBook中添加自定义CSS和JavaScript的更多信息，请参阅additional-css 和 additional-js。

如果您需要更多关于此功能的信息，请检查问题或提交新的问题。

自定义分隔符

要更改数学表达式的分隔符，请在 [preprocessor.katex] 下设置 block-delimiter 和 inline-delimiter。例如，要使用 \( 和 \) 进行行内数学和 \[\) 和 \] 进行数学块，设置

[preprocessor.katex]
block-delimiter = { left = "\\[", right = "\\]" }
inline-delimiter = { left = "\\(", right = "\\)" }

注意，上面的双反斜杠仅用于在TOML格式中转义 \。

注意事项

$\backslash$ 不起作用，但您可以使用 $\setminus$ 代替。

只有 x86_64 Linux、Windows GNU 和 macOS 构建具有完整功能（矩阵等），所有其他构建都功能受限。有关原因，请参阅#39。

逃逸模式（实验性）

提前转义公式所需的字符串，以便在Markdown处理器之后保持原始公式。

禁用预渲染以使用“逃逸模式”，并为您提供首选的客户端渲染库。以下是一个示例，其中包含 katex.js 并包含在 head.hbs 中（请参阅index.hbs）：

[preprocessor.katex]
after = ["links"]
pre-render = false
no-css = true

[output.html]
theme = "theme" # use theme/head.hbs

请注意，在逃逸模式下忽略KaTeX 选项。

一个 head.hbs 示例

<link rel="stylesheet" href="https://unpkg.com/katex@latest/dist/katex.min.css">
<script defer src="https://unpkg.com/katex@latest/dist/katex.min.js"></script>
<script defer src="https://unpkg.com/katex@latest/dist/contrib/auto-render.min.js"></script>

<script>
document.addEventListener("DOMContentLoaded", function () {
  renderMathInElement(document.body, {
    delimiters: [
      { left: '$$', right: '$$', display: true },
      { left: '$', right: '$', display: false },
    ],
  });
});
</script>