Jektex 0.2.0 发布，LaTeX渲染速度提升约10倍

背景

Jekyll 是广泛使用的静态网站生成器，尤其适合技术博客和文档站点。许多作者需要在文章中嵌入 LaTeX 公式，传统的做法是依赖客户端 JavaScript（如 MathJax 或 KaTeX）在浏览器中动态渲染，但这会带来页面加载延迟和额外的脚本开销。Jektex 是一个 Jekyll 插件，在构建阶段（服务器端）完成 LaTeX 公式的渲染，生成纯 HTML 输出，无需任何前端 JavaScript。该项目由 KaTeX.org 官方背书。最新的 0.2.0 版本将渲染速度提升了约 10 倍，同时提供了更完善的缓存机制和配置选项。

核心内容

Jektex 0.2.0 是一款 Jekyll 插件，用于在站点构建时快速渲染 LaTeX 数学公式，支持用户自定义全局宏，并内置高效的 I/O 缓存系统。其核心特性包括：

• 渲染时机：在 Jekyll 生成静态页面时完成 LaTeX 公式的转换，输出纯 HTML，不依赖任何客户端 JavaScript。
• 性能：官方声称比任何其他服务器端 Jekyll LaTeX 渲染器更快，0.2.0 版本相比之前提升了约 10 倍速度。
• 宏支持：可通过 _config.yml 定义全局宏，包括带参数的宏，模拟 LaTeX 的 \newcommand 行为。
• 缓存系统：默认启用磁盘缓存，缓存目录位于 .jekyll-cache（与 Jekyll 默认缓存路径一致）。可通过 cache_dir 选项自定义缓存位置，或通过 disable_disk_cache: true 禁用缓存。缓存会检测配置变更并自动失效重建。
• 错误处理：渲染过程中会动态显示表达式数量；无效公式会在构建时标记位置，且不影响构建过程。
• 不影响 Jekyll 工作流：对代码块和行内代码中的 LaTeX 内容保持原样，不会干扰 Markdown 解析。
• 两种 LaTeX 记号法：
  1. Kramdown 内建记号法：行内公式用 $$...$$（注意是双美元符号包裹在段落内）；展示公式用双美元符号前后加空行。
  2. LaTeX-only 记号法：行内公式用 \(...\)；展示公式用 \[...\]。位置自由，不受段落结构限制。
• 原始 HTML 块内的渲染：Kramdown 会跳过块级 HTML 标签内的 Markdown 解析，Jektex 能自动找到这些被跳过的 $$ 公式并在渲染后处理。支持行内和展示模式自动判断。此功能仅作用于 Markdown 源文件，不会影响 <pre>、<code>、<script> 等标签内的内容。可通过 \$$ 转义或放入代码段来阻止特定公式渲染。若希望 Kramdown 处理 HTML 块内容，可给标签添加 markdown="1" 属性。
• 内置 Logo 宏：可使用 \jektex 宏输出 Jektex 图标。
• 高度可配置：所有选项通过 _config.yml 设置，未知选项和无效值会在构建时报告并回退默认值。
• KaTeX 选项透传：通过 katex_options 键可以传递任何 KaTeX 渲染选项（如 trust、output、strict、maxExpand 等）。Jektex 自己控制 displayMode、macros、throwOnError、globalGroup 选项，故这些键被忽略（宏应通过顶层 macros 定义）。选项值会进行校验，不合法则使用 KaTeX 默认值。新版本引入的未知选项会直接透传。
• 文件忽略：默认处理所有 Jekyll 渲染的文件，可通过 ignore 选项（支持通配符）忽略特定文件（如 RSS feed 中的 XML 文件）。也可在文章 Front Matter 中设置 jektex: false 来忽略特定文章。
• 静默输出：可通过 silent: true 关闭构建过程中的方程计数提示信息（默认 false）。
• 安装与使用：
  • 作为 RubyGem 发布，可通过 Bundler 添加 gem "jektex" 到 Gemfile，或直接运行 gem install jektex。
  • 安装后需在 _config.yml 的 plugins 列表中添加 - jektex。
  • 需要手动引入 KaTeX 的 CSS：<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" ...>，建议下载到本地服务器。

关键要点

• 10倍性能提升：Jektex 0.2.0 相比旧版本渲染速度快约 10 倍，成为最快的服务器端 Jekyll LaTeX 渲染器。
• 零客户端脚本：所有 LaTeX 渲染在构建时完成，最终页面无需加载任何 JavaScript 库，大幅提升页面加载速度和无障碍性。
• 双重记号支持：同时兼容 Kramdown 原生 $$...$$ / $$（空行包围）记号和 LaTeX 标准 \(...\) / \[...\] 记号，用户可根据习惯选择。
• 智能缓存机制：默认启用磁盘缓存，自动识别配置变更并重建；缓存可自定义位置或完全禁用。
• 自定义全局宏：支持定义无参或有参宏，模拟 LaTeX 的 \newcommand，减少重复输入。
• KaTeX 选项全透传：几乎所有的 KaTeX 渲染参数都可以通过 katex_options 设置，如信任（trust）、输出格式（output）、严格模式（strict）等。
• 细粒度文件忽略：可通过全局通配符或文章级 Front Matter 灵活控制哪些文件需要渲染。
• 对原始 HTML 块的特殊处理：弥补 Kramdown 在块级 HTML 标签内的解析空缺，自动渲染其中的公式。
• 错误反馈友好：构建时显示渲染表达式总数，并指出无效公式所在位置，便于调试。
• 与 Jekyll 工作流无缝集成：不干扰原有项目结构，缓存目录默认被 jekyll clean 清理，代码块中的 LaTeX 内容不受影响。

意义与影响

• 加速学术与技术写作：对于使用 Jekyll 构建的技术博客、数学课程教材或科研笔记的作者，Jektex 提供了无 JavaScript 的 LaTeX 渲染方案，显著提升页面性能，同时保持书写习惯。
• 降低前端依赖：消除了对客户端 MathJax/KaTeX 脚本的加载依赖，对于注重首屏速度、SEO 或离线阅读的站点尤为重要。这也减少了浏览器计算负担，尤其利于移动端。
• 标准化服务器端渲染生态：Jektex 被 KaTeX.org 官方认可，有望成为 Jekyll 生态中服务器端 LaTeX 渲染的事实标准。其缓存和配置设计可作为其他静态站点生成器类似插件的参考。
• 简化部署与维护：构建时渲染意味着无需在 CDN 或服务器上配置额外运行时，部署更简单。缓存机制避免了重复渲染，节省构建时间。
• 兼容性与灵活性：同时支持两种主流 LaTeX 记号法，且能处理 Kramdown 的解析盲区，降低了迁移成本。用户可以通过丰富的配置（宏、KaTeX 选项、忽略规则等）精确控制渲染行为，满足从简单博客到复杂文档的不同需求。
• 开源协作推动：项目接受 issue 和 pull request，开放的开发模式鼓励社区贡献，有助于持续改进和适应未来 KaTeX 版本的更新。