docs-website/themes/next/docs/zh-CN/MATH.md

In epiforecasts/crowdforecastr: Eliciting crowd forecasts in R shiny

数学公式

NexT 内部提供数学公式渲染的引擎，这样你就不需要自己手动在模板中引入 JS 或者 CSS； 只需要选择对应的渲染引擎，并在 next/_config.yml 中将其 enable 选项改为 true 即可。

需要注意的是，仅仅将 enable 打开并不能让你看到数学公式，你还需要使用对应的 Hexo 渲染器(Renderer) 才能真正在博客页面中显示出数学公式。引擎对应使用的 Hexo 渲染器会在引擎相关的部分介绍。

提供的渲染引擎

目前，NexT 提供两种数学公式渲染引擎，分别为 MathJax 和 Katex。

MathJax

如果你选择使用 MathJax 进行数学公式渲染，你需要使用 hexo-renderer-pandoc 或者 hexo-renderer-kramed （不推荐）作为 Hexo 的 Markdown 渲染器。

首先，卸载原有的渲染器 hexo-renderer-marked，并安装这两种渲染器的其中一个：

npm uninstall hexo-renderer-marked
npm install hexo-renderer-pandoc # 或者 hexo-renderer-kramed

然后在 next/_config.yml 中将 mathjax 的 enable 打开。

math:
  ...
  mathjax:
    enable: true

执行 Hexo 生成，部署，或者启动服务器：

hexo clean && hexo g -d
# 或者 hexo clean && hexo s

使用 MathJax 给公式编号并引用公式

在新版本的 NexT 主题中，我们加入了公式自动编号和引用功能。下面简要介绍一下如何使用这项功能。

为了使用这项功能，一般来说，你必须把所使用的 LaTeX 公式放在 equation 环境里面，采用旧的方法（也就是说，仅仅把公式的每一边用两个 $ 符号包含起来）是无效的。如何引用公式？你只需要在书写公式的时候给公式一个 \label{} 标记（tag），然后在正文中，可以使用 \ref{} 或者 \eqref{} 命令来引用对应的公式。使用 \eqref{} 是推荐的方式，因为如果你使用 \ref{}，公式在文中的引用编号将没有圆括号包围。下面介绍几种常见的公式编号例子。

对于简单的公式，使用下面的方式给公式一个标记，

$$\begin{equation}\label{eq1}
e=mc^2
\end{equation}$$

然后，在正文中，你可以轻松引用上述公式，一个简单的例子如下：

著名的质能方程 $\eqref{eq1}$ 由爱因斯坦提出 ...

对于多行公式，在 equation 环境中，你可以使用 aligned 环境把公式分成多行，

$$\begin{equation}\label{eq2}
\begin{aligned}
a &= b + c \\
  &= d + e + f + g \\
  &= h + i
\end{aligned}
\end{equation}$$

要对齐多个公式，我们需要使用 align 环境。align 环境中的每个公式都有自己的编号：

$$\begin{align}
a &= b + c \label{eq3} \\
x &= yz \label{eq4}\\
l &= m - n \label{eq5}
\end{align}$$

在 align 环境中，如果你不想给某个或某几个公式编号，那么在这些公式后面使用 \nonumber 命令即可。例如：

$$\begin{align}
-4 + 5x &= 2+y \nonumber  \\
 w+2 &= -1+w \\
 ab &= cb
\end{align}$$

有时，你可能会希望采用更加奇特的方式来标记和引用你的公式，你可以通过使用 \tag{} 命令来实现，例如：

$$x+1\over\sqrt{1-x^2} \tag{i}\label{eq_tag}$$

如果你想要了解更多信息，请访问 MathJax 关于公式编号的官方文档。同时，你也可以阅读 这篇文档 来获取更多细节信息。

Katex

Katex 渲染引擎相对于 MathJax 来说大大提高了速度，而且在关掉 JavaScript 时也能渲染数学公式。

但是 Katex 所支持的东西没有 MathJax 全面，你可以从下面的相关链接中获取更多的信息。

如果你选择使用 Katex 进行数学公式渲染，你需要使用 hexo-renderer-markdown-it-plus 或者 hexo-renderer-markdown-it 这两种渲染器的其中一个。

首先，卸载原有的渲染器 hexo-renderer-marked，并安装这两种渲染器的其中一个：

npm uninstall hexo-renderer-marked
npm install hexo-renderer-markdown-it-plus
# 或者 hexo-renderer-markdown-it

然后在 next/_config.yml 中将 katex 的 enable 打开。

math:
  ...
  katex:
    enable: true

执行 Hexo 生成，部署，或者启动服务器：

hexo clean && hexo g -d
# 或者 hexo clean && hexo s

如果你使用 hexo-renderer-markdown-it

如果你使用 hexo-renderer-markdown-it，你还需要为其加上 markdown-it-katex 作为插件：

npm install markdown-it-katex

然后在 hexo/_config.yml 中将 markdown-it-katex 作为插件写入 hexo-renderer-markdown-it 的配置中：

markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: true
    linkify: true
    typographer: true
    quotes: '“”‘’'
  plugins:
    - markdown-it-katex

已知的问题

1. 首先请查阅 Katex 的 Common Issue
2. 块级公式(例如 $$...$$)必须位于空行。\ 即在开头的 $$ 前和在结尾的 $$ 后不能有除了空白字符以外的其他字符。(#32comment)
3. 不支持 Unicode。(#32comment)
4. 行内公式(例如 $...$)在开头的 $ 后面和结尾的 $ 前面不能含有空格。(#32comment)
5. 如果你在文章的各级标题中(例如 ## 标题)使用公式。\ 那么文章目录中的这个标题会出现 3 次未渲染的公式代码(#32comment)
6. 如果你在文章 Title 中使用公式，那么公式将不会被渲染。(#32comment)

我们目前使用的 Katex 版本为 0.11.1，这里面可能有某些问题是因为 Katex 版本老旧导致的；

但是，就像上面所说的，数学公式的渲染必须依靠渲染器来支持，目前的 Katex 相关的渲染器仅支持到 Katex 0.11.1；

我们会持续关注相关渲染器的更新，如果有渲染器支持更高版本的 Katex，我们会及时更新我们的 Katex 版本。

相关链接

• Katex 与 MathJax 渲染速度对比
• Katex 支持的功能列表

相关配置说明

注意，在修改配置选项时，不要更改配置的缩进；

目前，NexT 的所有配置都采用2 空格的缩进；

如果配置的内容接在冒号后面，那么内容和冒号之间必须有一个空格(例如enable: true)

# 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: true
    # 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

per_page

true 或者 false，默认为 true。

这个选项是控制是否在每篇文章都渲染数学公式；

默认(true) 的行为是只对 Front-matter 中含有 mathjax: true 的文章进行数学公式渲染。

如果 Front-matter 中不含有 mathjax: true，或者 mathjax: false，那么 NexT 将不会对这些文章进行数学公式渲染。

例如：

<!-- 这篇文章会渲染数学公式 -->
---
title: 'Will Render Math'
mathjax: true
---
....

<!-- 这篇文章不会渲染数学公式 -->
---
title: 'Not Render Math'
mathjax: false
---
....

<!-- 这篇文章也不会渲染数学公式 -->
---
title: 'Not Render Math Either'
---
....

当你将它设置为 false 时，它就会在每个页面都加载 MathJax 或者 Katex 来进行数学公式渲染。

epiforecasts/crowdforecastr documentation built on June 23, 2021, 10:30 p.m.