NexT 主题数学公式渲染完全指南：MathJax 与 KaTeX 的配置、编号引用与按需加载原理

前端【免费下载链接】hexo-theme-nextElegant and powerful theme for Hexo.项目地址https://gitcode.com/gh_mirrors/hex/hexo-theme-next点击查看免费下载本篇技术指南基于 docs/MATH.md 展开系统讲解 NexT 主题hexo-theme-next内置的数学公式渲染能力如何选择并启用 MathJax 与 KaTeX 两大渲染引擎、如何配套安装对应的 Hexo Markdown 渲染器、如何实现公式自动编号与\ref{}/\eqref{}交叉引用以及math.per_page按需加载机制的底层实现原理。读完本文你将能够在自己的 Hexo NexT 博客中一键开启数学公式支持并理解渲染脚本在页面中加载与跳过的完整逻辑。一、NexT 数学公式功能概览NexT 主题为数学公式展示提供了开箱即用的两种渲染引擎MathJax 与 KaTeX。启用该功能后无需手动向页面引入任何 JS 或 CSS——你只需要在next/_config.yml中选择一个渲染引擎并将其enable选项打开即可主题会在渲染页面时自动注入对应的脚本与样式。需要特别强调的是仅仅打开enable并不能保证公式被正确显示。公式能否显示还取决于 Hexo 将 Markdown 渲染为 HTML 的环节——你还需要为所选引擎安装配套的 Hexo RendererMarkdown 渲染器本文第二章将给出每种引擎对应的渲染器清单与完整安装步骤。从源码角度看该功能的全部逻辑集中在主题的四个位置配置解析入口_config.yml 中的math配置段加载决策layout/_third-party/math/index.swig 根据per_page与 Front-matter 决定是否加载引擎注入layout/_third-party/math/mathjax.swig 与 layout/_third-party/math/katex.swig 分别注入两种引擎的脚本/样式挂载位置layout/_layout.swig 在页面布局中直接include数学渲染模块且位于 pjax 容器内。二、渲染引擎选择与 Hexo Renderer 安装2.1 MathJax功能最全的传统方案MathJax 是老牌数学排版引擎功能支持最为全面。若选用 MathJax需要从以下两个 Hexo Markdown 渲染器中选择其一后者 kramed 不被推荐hexo-renderer-pandochexo-renderer-kramed不推荐安装步骤分三步走。第一步卸载默认渲染器并安装目标渲染器。npm uninstall hexo-renderer-marked npm install hexo-renderer-pandoc # 或 hexo-renderer-kramed第二步在next/_config.yml中打开mathjax的enable开关。math: ... mathjax: enable: true第三步重新生成站点。hexo clean hexo g -d # 或本地预览hexo clean hexo s从模板源码看启用 MathJax 后mathjax.swig 会注入一段内联配置脚本默认通过 jsDelivr CDN 加载mathjax3/es5/tex-mml-chtml.js并设置inlineMath: [[$, $]]即$...$触发行内公式、tags: amsAMS 标签规则这是公式编号功能的前提等核心选项。另外源码中还包含一段renderActions逻辑用于把 HTML 中以script[type^math/tex]形式存在的 LaTeX 源文本提取出来交给 MathJax 处理并给包含公式的li列表项追加has-jaxclass——这保证了即便公式出现在列表环境中也能正确排版。2.2 KaTeX极速轻量、可无 JS 存活KaTeX 相比 MathJax渲染速度要快得多且渲染结果可以在不依赖 JavaScript的情况下保留服务端即输出最终的 HTML/CSS。代价是KaTeX 对 LaTeX 语法的支持范围不如 MathJax 完整具体支持矩阵可查阅官方 Function Support 页面见本文第五章 Useful Links。若选用 KaTeX需要从以下两个渲染器中选择其一hexo-renderer-markdown-it-plushexo-renderer-markdown-it安装步骤同样是三步。第一步卸载默认渲染器并安装目标渲染器。npm uninstall hexo-renderer-marked npm install hexo-renderer-markdown-it-plus # 或 npm install hexo-renderer-markdown-it第二步在next/_config.yml中打开katex的enable开关。math: ... katex: enable: true第三步重新生成站点。hexo clean hexo g -d # 或 hexo clean hexo s从模板源码看katex.swig 默认注入katex0/dist/katex.min.cssKaTeX 样式表若启用copy_tex还会额外注入 KaTeX 官方 contrib 的copy-tex.min.js与copy-tex.min.css实现「复制公式时同时复制 LaTeX 源码」的能力。2.2.1 使用 hexo-renderer-markdown-it 时的额外配置如果你选择的是hexo-renderer-markdown-it还需要额外安装markdown-it-katex插件并挂载到该渲染器上npm install markdown-it-katex然后在Hexo 根目录的hexo/_config.yml中把markdown-it-katex添加为hexo-renderer-markdown-it的插件# hexo-renderer-markdown-it 的配置 markdown: render: html: true xhtmlOut: false breaks: true linkify: true typographer: true quotes: “”‘’ plugins: - markdown-it-katex注意这段配置写在 Hexo 的站点配置hexo/_config.yml中而不是主题的next/_config.yml中——因为它是渲染器级Hexo 全局的配置与主题无关。三、MathJax 公式编号与交叉引用NexT 新版为 MathJax 增加了公式自动编号与公式引用两大特性。要点如下自动编号必须将 LaTeX 公式放入equation环境传统的两侧双美元符$$...$$写法不会触发自动编号。引用方式在公式中打上\label{}标签然后在正文中用\ref{}或\eqref{}引用。推荐使用\eqref{}因为\ref{}输出的编号不带括号而\eqref{}会自动为编号加上圆括号。下面给出几个常见场景的完整示例。3.1 单行公式的编号与引用$$\begin{equation}\label{eq1} emc^2 \end{equation}$$随后即可在正文中轻松引用the famous matter-energy equation $\eqref{eq1}$ proposed by Einstein ...3.2 多行公式aligned环境在equation环境内部使用aligned环境可以把一个公式拆成多行整个 equation 仍然只占一个编号$$\begin{equation}\label{eq2} \begin{aligned} a b c \\ d e f g \\ h i \end{aligned} \end{equation}$$3.3 多公式对齐align环境使用align环境可以让多个公式对齐排列每个公式各自获得一个编号$$\begin{align} a b c \label{eq3} \\ x yz \label{eq4}\\ l m - n \label{eq5} \end{align}$$3.4 跳过编号\nonumber在align环境中如果希望某一行不参与编号只需在该行末尾加上\nonumber$$\begin{align} -4 5x 2y \nonumber \\ w2 -1w \\ ab cb \end{align}$$以上示例中第一行不会获得编号后两行会各自编号。3.5 自定义标签\tag{}如果需要「非常规」的引用样式可以用\tag{}自定义公式编号例如用罗马数字$$x1\over\sqrt{1-x^2} \tag{i}\label{eq_tag}$$该公式会以(i)作为编号并可通过\label{eq_tag}引用。这些编号/引用行为由 MathJax 的tags: ams配置驱动该选项已在 mathjax.swig 模板中预置。更深入的编号规则可查阅 MathJax 官方文档中关于 equation numbering 的章节或主题官网的 math-equations 说明页。四、KaTeX 的已知问题清单由于 KaTeX 渲染链路依赖 Markdown 渲染器且当前 KaTeX 相关渲染器支持的版本停留在 0.11.1NexT 存在以下已知限制。使用前请先对照 KaTeX 官方 Common Issues 检查你的公式块级公式$$...$$必须以全新的空行开头。也就是说$$之前不能有任何字符空白符除外$$之后也不能有任何字符——否则不会被正确解析为块级公式。不支持 Unicode字符。行内公式$...$在开头的$之后、结尾的$之前不得有空白。标题中的公式会污染 TOC如果在标题如## Heading中使用数学对应目录项的文本会重复显示 3 次 LaTeX 代码。文章标题post title中的公式不会被渲染。NexT 当前使用 KaTeX 0.11.1上述部分 Bug 可能正是由这个偏旧的 KaTeX 版本引起。NexT 团队会持续关注相应渲染器的更新一旦有支持更新版本 KaTeX 的渲染器出现就会同步升级内置 KaTeX。因此如果你遇到相关 Bug最快的规避方式是检查是否触发了上述任一已知限制。五、Useful Links官方参考资料以下是文档附带的官方参考资料均为引擎官方站点供进一步查阅KaTeX 与 MathJax 的速度对比测试KaTeX 函数支持清单关于 MathJax 的公式编号规则、KaTeX 的 copy-tex 插件与 mhchem 化学公式扩展也可以在各自官方文档中获取更详细信息见文末配置段注释中的链接。六、配置规格详解math配置段编辑配置时请务必遵守以下规则不要改动缩进目前 NexT 的所有配置统一使用2 空格缩进如果配置值直接写在配置名之后冒号与配置内容之间必须有一个空格例如enable: true。next/_config.yml中完整的math配置段如下源码位置# Math Formulas Render Support math: # Default (true) will load mathjax / katex script on demand. # That is it only render those page which has mathjax: true in Front-matter. # If you set it to false, it will load mathjax / katex srcipt EVERY PAGE. per_page: true # hexo-renderer-pandoc (or hexo-renderer-kramed) required for full MathJax support. mathjax: enable: false # See: https://mhchem.github.io/MathJax-mhchem/ mhchem: false # hexo-renderer-markdown-it-plus (or hexo-renderer-markdown-it with markdown-it-katex plugin) required for full Katex support. katex: enable: false # See: https://github.com/KaTeX/KaTeX/tree/master/contrib/copy-tex copy_tex: false各参数含义与取值范围如下参数取值默认值作用math.per_pagetrue/falsetrue控制是否在每一页都渲染公式见下文「按需加载」math.mathjax.enabletrue/falsefalse启用 MathJax 渲染引擎math.mathjax.mhchemtrue/falsefalse加载 MathJax-mhchem 扩展支持化学方程式math.katex.enabletrue/falsefalse启用 KaTeX 渲染引擎math.katex.copy_textrue/falsefalse启用 KaTeX copy-tex 扩展复制公式时附带 LaTeX 源码在 mathjax.swig 中可以看到mhchem参数的实际效果当mhchem: true时MathJax 配置会额外加载[tex]/mhchem包并将其加入packages同理在 katex.swig 中当copy_tex: true时会注入copy-tex的 JS 与 CSS。这两个开关都是「锦上添花」型扩展与主引擎互不冲突。6.1 按需加载per_pageper_page接受true或false默认true。该选项用于控制是否在每一页都渲染数学公式。默认值true的行为是按需渲染on demand只在 Front-matter 中带mathjax: true的文章页加载渲染脚本设为false时数学公式将在每一页EVERY PAGE被渲染。以默认行为为例以下三种 Front-matter 写法对应的渲染结果完全不同!-- 这篇文章会渲染公式 -- --- title: Will Render Math mathjax: true --- ....!-- 这篇文章不会渲染公式 -- --- title: Not Render Math mathjax: false --- ....!-- 这篇文章同样不会渲染公式 -- --- title: Not Render Math Either --- ....可以看到只有显式声明mathjax: true的文章才会加载数学渲染脚本mathjax: false与完全省略该字段的文章都不会加载。七、源码级原理per_page按需加载的实现per_page的按需加载并非简单的「页面级开关」其真实决策逻辑位于 layout/_third-party/math/index.swig我们可以逐行拆解{%- if theme.math.mathjax.enable or theme.math.katex.enable %} {%- set is_index_has_math false %} {# 首页检查是否存在带 mathjax: true 的文章 #} {%- if is_home() and theme.math.per_page %} {%- for post in page.posts.toArray() %} {%- if post.mathjax and not is_index_has_math %} {%- set is_index_has_math true %} {%- endif %} {%- endfor %} {%- endif %} {%- if not theme.math.per_page or is_index_has_math or page.mathjax %} {%- if theme.math.mathjax.enable %} {% include _third-party/math/mathjax.swig %} {% elif theme.math.katex.enable %} {% include _third-party/math/katex.swig %} {%- endif %} {%- endif %} {%- endif %}该模板揭示了三层逻辑引擎启用判断只有mathjax.enable或katex.enable至少一个为true时整个模块才进入处理流程首页聚合判断当处于首页is_home()且per_page: true时会遍历首页文章列表只要存在任意一篇带mathjax: true的文章就把is_index_has_math置为true——这是为了让首页摘要中若包含公式或文章列表页需要加载脚本也能正确渲染最终加载条件满足以下任一条件即注入引擎脚本per_page为false全局渲染首页存在含公式的文章is_index_has_math当前页面 Front-matter 声明了mathjax: truepage.mathjax。另外front-matter.js 中展示了 Hexo 主题的通用 Front-matter 合并机制template_locals过滤器把theme与page的配置合并这保证了page.mathjax等字段在模板层可以稳定读取。该模块最终通过 layout/_layout.swig 被挂载到页面骨架中且位于 pjax 容器内——这意味着启用 pjax 后无刷新切换页面时数学脚本也能随局部刷新被正确处理。7.1 脚本资源的自定义vendors 配置两种引擎的 CDN 地址均可在next/_config.yml的vendors段自定义源码位置vendors: # MathJax # mathjax: //cdn.jsdelivr.net/npm/mathjax3/es5/tex-mml-chtml.js mathjax: # KaTeX # katex: //cdn.jsdelivr.net/npm/katex0/dist/katex.min.css # katex: //cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/katex.min.css # copy_tex_js: //cdn.jsdelivr.net/npm/katex0/dist/contrib/copy-tex.min.js # copy_tex_css: //cdn.jsdelivr.net/npm/katex0/dist/contrib/copy-tex.min.css katex: copy_tex_js: copy_tex_css:模板中的mathjax_uri与katex_uri正是从这些 vendors 取值未配置时回落到 jsDelivr 默认地址见 mathjax.swig 与 katex.swig。如果你身处中国大陆默认 jsDelivr 通常已可用也可以按注释切换到 CDNJS 等其它 CDN或改为自建静态资源路径。八、常见问题速查公式不显示但配置都开了几乎可以肯定是 Markdown 渲染器问题。MathJax 需要hexo-renderer-pandoc推荐或hexo-renderer-kramedKaTeX 需要hexo-renderer-markdown-it-plus或hexo-renderer-markdown-itmarkdown-it-katex插件。先卸载默认的hexo-renderer-marked再安装对应渲染器并执行hexo clean重新生成。$$...$$块级公式不生效KaTeX检查$$前后是否紧贴了其它字符——块级公式必须独占一行前后仅允许空白。行内公式$...$渲染异常KaTeX检查$内侧是否留了空格行内公式的开头$之后、结尾$之前不允许有空白。公式没有编号MathJax 下必须使用equation/align环境包裹公式单纯$$...$$不会自动编号编号样式由tags: ams提供。想让所有页面都支持公式把math.per_page设为false即可全局加载反之保持true并给文章 Front-matter 加mathjax: true实现按需加载。赞分享前端【免费下载链接】hexo-theme-nextElegant and powerful theme for Hexo.项目地址https://gitcode.com/gh_mirrors/hex/hexo-theme-next点击查看免费下载相关推荐hexo-theme-next主题数学公式渲染优化KaTeX vs MathJaxhexo theme next主题数学公式渲染优化KaTeX vs MathJax 作为Hexo最受欢迎的主题之一hexo theme next提供了两种强前端YOLOv10 多领域泛化一次评透RF100Roboflow 10022 万张图目标检测基准实战YOLOv10 多领域泛化一次评透RF100Roboflow 10022 万张图目标检测基准实战 COCO 上 mAP 很高换到医疗影像、无人机航拍就翻人工智能深度学习计算机视觉Quartz 数学公式渲染插件 Latex 完全指南KaTeX / MathJax / Typst 三引擎配置与实战Quartz 数学公式渲染插件 Latex 完全指南KaTeX / MathJax / Typst 三引擎配置与实战 本篇指南聚焦于 Quartz 静态站点生前端开发工具CLI上一篇Fabric Carpet与社区生态系统carpet-extra和scarpet app store完全指南 下一篇OpenCart 开源电商系统推荐创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考