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: TransformerFunction name:ExternalPlugin.Latex()默认状态:enabled: true开箱即用、required: false可按需移除也就是说任何通过默认模板创建的新 Quartz 项目数学公式渲染能力是默认开启的。这一点可以从模板配置得到直接印证在 quartz/cli/templates/default.yaml 中LaTeX 插件位于 transformers 段内默认启用并指定了renderEngine: katexorder: 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配置项类型说明默认值renderEnginekatex|mathjax|typst渲染引擎KaTeX、MathJaxSVG 输出或 TypstkatexcustomMacros键值对对象为所有 LaTeX 块定义自定义宏键为新命令名值为宏展开式无katexOptions对象透传给 KaTeX 渲染器的额外选项无mathJaxOptions对象透传给 MathJax 渲染器的额外选项无typstOptions对象透传给 Typst 渲染器的额外选项无3.1 renderEngine三引擎选型katex默认基于 KaTeX以 HTMLCSS 方式排版速度快、体积小是 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: 803.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 titlesrc/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 速查项目值CategoryTransformerFunction nameExternalPlugin.Latex()Sourcequartz-community/latex社区插件仓库Installnpx quartz plugin add github:quartz-community/latex七、实战小结在 Quartz 中启用 LaTeX 数学公式渲染本质上是三步确认插件存在默认模板已内置并启用renderEngine: katex、order: 80见 quartz/cli/templates/default.yaml缺失时执行npx quartz plugin add github:quartz-community/latex或克隆项目后在 CI 中执行npx quartz plugin install --from-config按需配置在quartz.config.yaml中通过renderEngine选择 KaTeX / MathJax / Typst用customMacros定义常用符号宏用katexOptions/mathJaxOptions/typstOptions透传引擎级选项规范写作块级公式的$$必须独占一行行内公式用$出现多个美元符号时用\$转义化学式通过 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考