为Pelican提供的数学渲染插件

此插件使Pelican能够在帖子内容中渲染数学公式。它是通过使用MathJax JavaScript引擎来实现的。

该插件还确保Typogrify与数学内容良好兼容，通过确保Typogrify不会更改数学内容。

支持Markdown和reStructuredText。

要求

• 需要Pelican版本4.5或更高版本。
• 为了使Typogrify与该插件正确配合，需要Typogrify版本2.0.7或更高版本。如果此版本不可用，整个站点的Typogrify将被禁用。
• 为了纠正摘要，需要BeautifulSoup 4+。如果BeautifulSoup未安装，即使在用户设置中指定，也将忽略摘要处理。

安装

可以通过以下方式安装此插件

python -m pip install pelican-render-math

现在，您的站点应该能够使用MathJax JavaScript引擎渲染数学内容。无需更改模板——只需使用并享受即可！

但是，如果您愿意，可以将auto_insert设置设置为False，这将禁用MathJax脚本自动插入到内容中。只有当您控制模板并希望手动插入脚本时，才应这样做。

Typogrify

过去，使用Typogrify会更改数学内容，导致无法由MathJax渲染的数学。唯一的选项是确保在设置中禁用Typogrify。

在此插件中已修复了此问题，但至少需要Typogrify版本2.0.7或更高版本。如果此版本不存在，插件将禁用整个站点的Typogrify。

BeautifulSoup

Pelican通过截断到指定用户长度的帖子内容来创建摘要。截断过程对任何数学一无所知，因此可能会破坏摘要中的数学输出。

为了恢复数学，使用BeautifulSoup。如果未安装，则不会进行摘要处理。

用法

模板

无需对模板进行任何更改即可使此插件正常工作。只需安装插件并开始编写您的数学内容。

设置

可以在Pelican设置文件中设置某些MathJax渲染选项。这些选项位于名为MATH_JAX的字典变量中。

可以使用以下键设置字典

• align: [字符串]控制显示的数学如何对齐。可以设置为'left'、'right'或'center'。 默认值: 'center'。
• auto_insert: [布尔值]将在检测到包含数学的内容中插入MathJax脚本。不建议将其设置为false。 默认值: True
• indent: [字符串]如果align未设置为'center'，则此选项控制缩进级别。 默认值: '0em'。
• show_menu: [布尔值]控制是否显示MathJax上下文菜单。 默认值: True
• process_escapes: [布尔值]控制MathJax是否处理转义序列。 默认值: True
• MathJax_font: [字符串]将强制MathJax使用所选字体。当前可选的字体是sanserif、typewriter或fraktur。如果未设置，它将使用默认的字体设置。 默认值: default
• latex_preview: [字符串]控制MathJax渲染LaTeX时用户看到的预览消息。如果设置为'Tex'，则将使用TeX代码作为预览（直到它被MathJax处理）。 默认值: 'Tex'
• color: [字符串]控制MathJax渲染字体的颜色。 默认值: 'inherit'
• linebreak_automatic: [布尔值] 如果设置，MathJax 将尝试智能地分割显示的数学公式（注意：对于内联数学公式不起作用）。这对于响应式网站非常有用。默认关闭，因为可能占用CPU资源较多。默认值: False
• tex_extensions: [列表] MathJax 接受的 LaTeX 扩展 列表。默认值: []（空列表）
• responsive: [布尔值] 尝试使显示的数学公式呈现响应式。它通过确定宽度是否小于 responsive_break（见下文）来实现，如果是，则将 align 设置为 left，将 indent 设置为 0em，将 linebreak_automatic 设置为 True。默认值: False（为向后兼容默认为 False）
• responsive_break: [整数] 一个数字（以像素为单位），表示设置 responsive_align 为 True 时使用的宽度断点。默认值: 768
• process_summary: [布尔值] 确保数学公式在摘要中渲染并修复被截断的数学公式。需要安装 BeautifulSoup。 默认值: True
• message_style: [字符串] 此值控制左下角消息的详细程度。将其设置为 None 以消除所有消息。默认值: normal

设置示例

使数学以蓝色渲染并使显示的数学公式左对齐

MATH_JAX = {'color':'blue','align':left}

使用 color 和 mhchem 扩展

MATH_JAX = {'tex_extensions': ['color.js','mhchem.js']}

生成的HTML

内联数学被包裹在 span 标签中，而显示的数学被包裹在 div 标签中。这些标签将有一个类属性，被设置为 math，模板设计者可以使用它来修改数学的显示。

Markdown

此插件实现了 Markdown 的自定义扩展，使数学成为 Pelican 的“第一公民”。

内联数学

例如，数学公式 $x^2$ 之间的数学公式将以内联方式渲染，相对于当前 HTML 块。注意：要使用内联数学，结束的 $ 前不能有任何空白。例如

• 相关的内联数学: $e=mc^2$
• 将不会作为内联数学渲染: $40 vs $50

显示的数学

例如，数学公式 $$..$$ 之间的数学公式将以“块样式”渲染，例如，$$x^2$$ 将在新的段落中居中渲染。

其他 LaTeX 显示数学命令

支持通常从文本模式调用显示数学模式的其他 LaTeX 命令，并且它们将被自动处理为 $$-样式的显示数学，在它们自己的行上以“块”样式渲染。例如，\begin{equation} x^2 \end{equation} 将在其自己的块中渲染，在块的顶部有右对齐的方程编号。此方程编号可以在文档中引用。为此，在方程格式中使用 label，然后使用 ref 引用该标签。例如：\begin{equation} \label{eq} X^2 \end{equation}。现在通过 $\ref{eq}$ 引用该方程编号。

reStructuredText

如果在 reStructuredText 内容中检测到数学，插件将自动将 math_output 配置设置设置为 mathjax。

内联数学

内联数学需要使用 math 角色

The area of a circle is :math:`A_\text{c} = (\pi/4) d^2`.

显示的数学

显示的数学使用 math 块

.. math::

   α_t(i) = P(O_1, O_2, … O_t, q_t = S_i λ)

贡献

欢迎并非常感谢贡献。每一份贡献都很有帮助。您可以通过改进文档、添加缺失的功能和修复错误来贡献。您还可以通过审查和评论 现有问题 来提供帮助。

要开始为此插件贡献，请查阅为 Pelican 贡献 文档，从 贡献代码 部分 开始。