Asciidoctor 数学

该库的工作原理是遍历已解析文档中的每个 STEM 节点，并将其转换为图像，从而有效地用图像节点替换 STEM 节点。这减轻了转换器转换 STEM 表达式的负担。转换器看到的只是引用已生成图像的图像节点。

访问每个 STEM 节点时，扩展首先提取表达式源。如果表达式是用 AsciiMath 编写的，则扩展会使用 AsciiMath 库将其转换为 LaTeX。然后，扩展将表达式传递给 Mathematical 以将其渲染为图像。图像会自动调整大小以适应渲染的表达式，并在必要时调整大小以适应行内。图像生成后，扩展会将已解析文档中的 STEM 节点替换为一个引用已生成图像的图像节点。

当扩展完成处理所有 STEM 节点后，它会取消设置文档中的 stem 属性，以指示不应再对文档执行 STEM 处理。

由于 Asciidoctor Mathematical 将所有 STEM 节点替换为图像节点，因此它成为 STEM 处理的通用解决方案。所有转换器都知道如何处理图像节点。该扩展可与内置转换器以及 PDF 和 EPUB3 等附加转换器一起使用。

与 MathJax 相比，Asciidoctor Mathematical 的主要缺点是您对生成的图像的大小和分辨率的控制不多。它还缺乏 MathJax 提供的与表达式的交互性。因此，当您转换为 HTML 时，MathJax 会为您提供更好的结果。

与 MathJax 相比的另一个缺点是，它需要安装一个额外的库，而这个库可能难以安装。尽管如此，如果您需要它并且愿意接受挑战，那么我们接下来将继续介绍。

Asciidoctor Mathematical 分发为名为 asciidoctor-mathematical 的 gem。您可以使用 Ruby 打包工具（gem 或 bundle）来安装它。

但是，您在安装此 gem 时可能会遇到困难。Asciidoctor Mathematical 依赖于 Mathematical，这是一个原生 gem。换句话说，Mathematical 必须在安装过程中重新编译，这需要主机系统上的构建工具和原生开发库的访问权限。此外，此编译目前仅在 Linux 上有效。您无法在 Windows 上安装此 gem。请参阅 Asciidoctor Mathematical 文档中的 安装部分，了解您需要哪些系统工具和开发库才能安装它。

如果您在安装此 gem 时遇到问题，或需要在 Windows 上使用它，请考虑使用 Asciidoctor Docker 容器。Asciidoctor Docker 容器启动时预装了 asciidoctor-mathematical gem。

一旦安装了 Asciidoctor Mathematical，您就可以在使用 -r 标志调用 Asciidoctor 时激活该扩展。

如果您通过 API 调用 Asciidoctor，则必须在调用 Asciidoctor 之前 `require` 该 gem。

激活扩展后，它将自动在已解析文档中查找 STEM 节点并将其替换为图像。

为了获得最佳输出质量并最大化转换速度，您应该将 Asciidoctor Mathematical 配置为生成 SVG 文件。您可以使用 mathematical-format AsciiDoc 属性来控制此设置，如下所示：

扩展现在将生成 SVG 图像而不是 PNG 图像。

要了解有关如何使用此扩展及其提供的选项的更多信息，请参阅 项目的 README。