企业官网建设流程全解析

Quartz 数学公式渲染插件 Latex 完全指南：KaTeX / MathJax / Typst 三引擎配置与实战

【免费下载链接】quartz🌱 a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz

本篇指南聚焦于 Quartz 静态站点生成器的Latex 社区插件（@quartz-community/latex），它负责在构建期将 Markdown 内容中的 LaTeX 数学公式排版为网页可渲染的 HTML/SVG。读完本文，你将掌握：如何在quartz.config.yaml中启用并配置该插件、三种渲染引擎（KaTeX、MathJax、Typst）的取舍与选项透传方法、块级与行内公式的写作语法与转义规则，以及通过 mhchem 扩展化学式的进阶玩法。文中的所有配置项与命令均以当前仓库（Quartz v5 插件体系）的实际实现为准，并附源码佐证。

一、插件定位：作为 Transformer 的 LaTeX 渲染器

Latex 插件属于 Quartz 插件体系中的Transformer（转换器）类别。Quartz 将插件视为对内容的系列变换（参见 configuration.md 中的 Plugins 章节）：Transformer 负责对内容做"映射"式处理，而 LaTeX 解析与排版正是在这一阶段完成的——它在构建时把$...$/$$...$$包裹的数学表达式转换为最终的网页输出，运行时无需再加载重型 JS。

在插件文档 docs/plugins/Latex.md 中，该插件被标注为：

• Category: Transformer
• Function name:ExternalPlugin.Latex()
• 默认状态:enabled: true（开箱即用）、required: false（可按需移除）

也就是说，任何通过默认模板创建的新 Quartz 项目，数学公式渲染能力是默认开启的。这一点可以从模板配置得到直接印证：在 quartz/cli/templates/default.yaml 中，LaTeX 插件位于 transformers 段内，默认启用并指定了renderEngine: katex，order: 80控制其在同类插件中的执行顺序：

# quartz/cli/templates/default.yaml (节选) - source: "@quartz-community/latex" enabled: true options: renderEngine: katex order: 80

同样的配置片段也出现在blog.yaml、obsidian.yaml、ttrpg.yaml等其余模板中（quartz/cli/templates/），说明无论使用哪种模板初始化项目，LaTeX 能力都已内置。

二、安装与启用：从模板预置到手动管理

虽然模板已默认启用该插件，但在以下场景你仍需要手动安装：

• 从旧版本升级后配置中缺少该插件；
• 克隆他人项目时.quartz/plugins/目录尚未就绪；
• 希望固定到特定分支或本地开发版本。

2.1 通过 CLI 安装

插件文档给出的安装命令为：

npx quartz plugin add github:quartz-community/latex

该命令会将插件加入quartz.config.yaml并安装到.quartz/plugins/目录（详见 docs/cli/plugin.md）。add子命令还支持：

# 指定分支/引用（写入 quartz.lock.json，后续 install/prune 自动遵循） npx quartz plugin add github:quartz-community/latex#my-branch # 从本地目录添加（符号链接，改动即时生效，适合本地开发/离线环境） npx quartz plugin add ./path/to/my-plugin

安装的插件统一存放在.quartz/plugins/，版本信息记录在quartz.lock.json中。

2.2 从配置批量同步

当quartz.config.yaml已包含该插件条目、但尚未安装时（例如克隆项目或 CI 构建环境），使用：

npx quartz plugin install --from-config

该命令会依据配置安装缺失插件并清理不再引用的"孤儿"插件，--dry-run可先预览将要发生的变更。安装流程的底层实现在 quartz/plugins/loader/install-plugins.ts 中：它会读取quartz.js导出的externalPlugins或quartz.config.yaml中的plugins列表，逐一解析来源（Git 仓库 / 本地路径 / npm 包），随后克隆、构建并重新生成插件索引。

[!note] 关于插件的添加、移除与配置的完整说明，请参见 configuration.md 的 Plugins 章节 与 cli/plugin.md。Quartz 将插件区分为随仓库内置的 internal 插件与独立安装的 community 插件，Latex 属于后者。

三、配置选项详解：五个核心参数

在quartz.config.yaml中，该插件接受如下配置选项（来自 docs/plugins/Latex.md）：

3.1 renderEngine：三引擎选型

• "katex"（默认）：基于 KaTeX，以 HTML+CSS 方式排版，速度快、体积小，是 Quartz 默认采用的引擎；
• "mathjax"：基于 MathJax 的 SVG 输出模式，渲染质量高、兼容性极佳，适合对排版细节要求更高的场景；
• "typst"：基于 Typst 排版 LaTeX 公式，代表了新一代公式排版方案。

一个完整的配置示例：

plugins: - source: "@quartz-community/latex" enabled: true options: renderEngine: katex # 可选: katex | mathjax | typst customMacros: "\\R": "\\mathbb{R}" "\\Z": "\\mathbb{Z}" katexOptions: throwOnError: false strict: false # mathJaxOptions: # svg: # fontCache: global order: 80

3.2 customMacros：自定义宏

customMacros采用"新命令名 → 宏展开式"的键值对形式。例如文档中的{"\\R": "\\mathbb{R}"}定义后，你在正文中写$\R$即可渲染为 $\mathbb{R}$（实数集符号）。这比在每篇笔记里重复写\mathbb{R}高效得多，适合数学笔记中频繁使用的符号。

3.3 引擎专属选项透传

• katexOptions直接透传给 KaTeX 渲染器，可用选项参考 KaTeX 官方 options 文档。常见实用项包括throwOnError: false（遇到无法解析的公式时不抛错、改为显示原始文本）、strict: false（放宽语法警告）等；
• mathJaxOptions透传给 MathJax 渲染器，例如可通过svg.fontCache调整 SVG 字体缓存策略；
• typstOptions透传给 Typst 渲染器。

3.4 配置的代码级落点

从源码结构看，外部插件通过 quartz.ts（内部调用loadQuartzConfig）加载，而quartz.config.yaml中的options会在插件安装/索引重建阶段被读取。值得注意的是，quartz/cli/plugin-git-handlers.js 中的regeneratePluginIndex会扫描每个已安装插件的dist/index.d.ts，将可覆盖的导出（overridable exports）包装为plugins["插件名"].导出名的形式注册到组件注册表中——这从机制上保证了不同插件间的同名导出可以被安全隔离。因此，如果你需要以 TypeScript 方式精细覆写插件配置，也可以在 quartz.ts 中通过loadQuartzConfig({...})覆盖对应字段（参见 configuration.md 的进阶说明）。

四、写作语法：块级公式、行内公式与转义

公式的写作语法定义在 docs/features/Latex.md 中。Quartz 默认使用 KaTeX 在构建期同时排版行内（inline）与块级（block）数学表达式。

4.1 块级公式（Block Math）

用双美元符号$$定界：

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

渲染效果：

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

支持aligned环境的多行对齐：

$$ \begin{aligned} a &= b + c \\ &= e + f \\ \end{aligned} $$

$$ \begin{aligned} a &= b + c \ &= e + f \ \end{aligned} $$

也支持矩阵（bmatrix）与复杂的物理推导（如薛定谔方程求解过程）：

$$ \begin{bmatrix} 1 & 2 & 3 \\ a & b & c \end{bmatrix} $$ $$ $$ \begin{bmatrix} 1 & 2 & 3 \\ a & b & c \end{bmatrix} $$ > [!warn] > 由于底层解析库 [remark-math](https://github.com/remarkjs/remark-math) 的限制，**Quartz 中的块级公式要求 `$$` 定界符各占独立一行**，如上例所示，不能写成 `$$f(x)=...$$` 的单行形式。 ### 4.2 行内公式（Inline Math） 用单个美元符号 `$` 定界，例如 `` `$e^{i\pi} = -1$` `` 渲染为 $e^{i\pi} = -1$。行内公式与正文混排时注意与中文标点保持适当的空白。 ### 4.3 转义符号（Escaping `$`） 当一段文字中同时出现多个 `$`（例如价格、货币符号）时，可能意外触发 KaTeX/MathJax 的解析。此时用 `\$` 转义即可： - ❌ 错误：`I have $1 and you have $2` 会被误判为公式上下文； - ✅ 正确：`I have \$1 and you have \$2`，渲染为"I have $1 and you have $2"。 ### 4.4 使用 mhchem（化学式支持） 若需要渲染化学方程式，可以利用 mhchem 扩展。做法是 **fork 插件仓库**，在 `src/index.ts` 文件顶部（早于所有其他 import）添加： ```ts title="src/index.ts" import "katex/contrib/mhchem"

之后便可在公式中使用 mhchem 语法（如\ce{H2O}、\ce{CO2 + C -> 2CO}）。该扩展的加载位置要求"早于其他 import"，是为了确保 KaTeX 注册 mhchem 宏定义之后再处理公式渲染。

五、样式与主题适配：源码中的渲染器样式落点

公式渲染的样式在 Quartz 全局样式中得到适配，这从 quartz/styles/base.scss 中可以确认：

• 第 45-57 行：.katex、.math、.typst-doc、g[class~="typst-text"]、path[class~="typst-shape"]等选择器被统一纳入正文颜色变量--darkgray与换行处理，保证公式文本在亮/暗色主题下与正文视觉一致——这印证了三种引擎（KaTeX 的.katex类、Typst 的.typst-doc/typst-text/typst-shape类）都在主题适配范围内；
• 第 59-63 行：.math.math-display被设置为text-align: center，即块级公式默认居中显示；
• 第 66-69 行：对 MathJax 的 SVG 输出（mjx-container.MathJax）做了 flex 布局适配；
• 第 661 行附近：.katex-display的块级展示样式。

这意味着无论你切换renderEngine为哪种引擎，其产物都能自动继承站点的主题与排版规范，无需额外编写 CSS。

六、API 速查

七、实战小结

在 Quartz 中启用 LaTeX 数学公式渲染，本质上是三步：

1. 确认插件存在：默认模板已内置并启用（renderEngine: katex、order: 80，见 quartz/cli/templates/default.yaml）；缺失时执行npx quartz plugin add github:quartz-community/latex，或克隆项目后在 CI 中执行npx quartz plugin install --from-config；
2. 按需配置：在quartz.config.yaml中通过renderEngine选择 KaTeX / MathJax / Typst，用customMacros定义常用符号宏，用katexOptions/mathJaxOptions/typstOptions透传引擎级选项；
3. 规范写作：块级公式的$$必须独占一行，行内公式用$，出现多个美元符号时用\$转义，化学式通过 fork 插件引入 mhchem 扩展实现。

以此为基础，你的 Quartz 站点即可在构建期产出高质量、与主题一致的数学排版内容，无论是数学笔记、物理推导还是化学方程式都能流畅呈现。

【免费下载链接】quartz🌱 a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites项目地址: https://gitcode.com/GitHub_Trending/qua/quartz