给Pelican增加数学公式和图表的显示

2026年05月15日星期五

AI时代，我觉得数学在我接下来的学习和工作中太重要了，所以我决定给Pelican加上显示数学表达式的功能。

MathJax 数学公式

方案选择

Pelican显示数学公式，大概有三种实现方式：

方案	插件	方式
KaTeX预渲染	pelican-katex	生成时将公式转为HTML/MathML
MathJax浏览器渲染	pelican-render-math	浏览器加载MathJax.js动态渲染
LaTeX转SVG	pelican-math-svg	调用LaTeX将公式编译为SVG图片嵌入页面

我比较了一下，第二个pelican-render-math的实现起来比较简单，利用Pelican原有的运行环境就能跑。

安装配置

使用pip安装：

pip install pelican-render-math

如果是用了uv就用：

uv add pelican-render-math

然后在pelicanconf.py中添加：

PLUGINS = ["render_math"]
MATH_JAX = {
    "align": "center",
    "auto_insert": True,
    "process_escapes": True,
    "latex_preview": "TeX",
    "color": "inherit",
    "linebreak_automatic": False,
    "responsive": True,
    "responsive_break": 768,
    "process_summary": True,
}

各参数注解

"align": "center"
- 对应 MathJax 的 displayAlign 设置。
- 作用：控制块级公式（$$...$$）的水平对齐方式。
- 可选值："left", "center", "right"。这里设置为居中显示。
"auto_insert": True
- 作用：是否由插件自动在需要渲染数学公式的页面 <head> 中插入 MathJax 的 JavaScript 引用和配置。
- 效果：
  - 设为 True：你无需手动修改主题模板，插件会智能判断文章是否包含公式，只在有公式的页面加载 MathJax。
  - 设为 False：你需要自行在模板中添加 MathJax 的加载代码，适合希望完全手动控制资源加载的场景。
"process_escapes": True
- 作用：开启后，MathJax 会先处理 HTML 中由 Markdown 产生的转义字符。例如，Markdown 将 \$ 转义为 $ 字面量，但实际你可能是想写 LaTeX 命令。
- 典型影响：
  - 当在 Markdown 中写 \$x$ 时，开启该选项会先将 \$ 还原成 $，从而正确解析行内公式。
  - 关闭时，$ 可能被 Markdown 转义而失效，导致公式无法渲染。
- 建议：保持 True，尤其当你需要在文章里使用美元符号本身而不表示公式时，可以用 \$ 来区分。
"latex_preview": "TeX"
- 作用：在 MathJax 完全渲染出精美公式之前，页面上临时显示的占位内容样式。
- 可选值：
  - "TeX"：显示原始的 LaTeX 源码（如 \frac{a}{b}），直到渲染完成才替换为漂亮公式。这能避免页面布局跳动，且让读者知道这里有公式正在处理。
  - "none"：不显示任何预览，公式区域可能短暂留白或显示占位符。
  - 其他值可能无效，插件通常只处理这两个选项。
- 效果：设置为 "TeX" 能提供更好的视觉体验。
"color": "inherit"
- 作用：设置渲染后数学公式的整体颜色。
- 解释："inherit" 表示公式颜色继承其所在 HTML 元素的前景色。这意味着公式会自动适配网页的字体颜色，比如正文为深灰色时公式也是深灰色，暗色模式下也能自动变色。
- 如果设为具体颜色：如 "black" 或 "#333"，则公式颜色固定，不再跟随文本颜色。
"linebreak_automatic": False
- 对应 MathJax 的自动换行功能。
- 作用：控制过长的块级公式是否允许在行内自动换行。
- 效果：
  - False：长公式超出容器宽度时会出现水平滚动条，公式保持单行。
  - True：数学公式会在合适的运算符（如 +, =）处自动换行，避免破坏页面布局，但可能影响公式语义的直观性。这里你选择禁用，通常是希望公式完整展示。
"responsive": True
- 作用：启用 MathJax 的响应式渲染。开启后，公式会根据屏幕或容器宽度动态调整显示策略（例如缩放、重排），在小屏幕移动设备上避免公式被截断。
- 依赖：通常与 responsive_break 配合使用，当视口宽度小于某个值时触发特殊处理。
"responsive_break": 768
- 作用：设置响应式触发的断点宽度（单位：像素）。
- 效果：当浏览器视口宽度 ≤ 768px 时，MathJax 会尝试让公式适应窄屏幕（比如采用缩放或允许公式内部换行等策略）。数值可根据你的主题移动端适配方案调整。
- 注意：该参数仅在 "responsive": True 时生效。
"process_summary": True
- 作用：是否在文章的摘要（文章列表页显示的前几行内容）中也处理数学公式。
- 效果：
  - 设为 True：插件会解析摘要中的 $...$ 或 $$...$$，并在列表页同样插入 MathJax 渲染它们。这可以保证首页或分类页的摘要不会显示原始 LaTeX 代码。
  - 设为 False：摘要中的公式不会被处理，可能直接显示未渲染的代码，影响阅读体验。推荐保持 True。

效果示例

现在我们试试效果：

同一行数学公式：$\dfrac{1}{1+x^2}$

代码是：

同一行数学公式：$\dfrac{1}{1+x^2}$

独立行复杂数学公式：

$$ \begin{pmatrix} a_{11} & a_{12} & \cdots & a_{1n} \\ a_{21} & a_{22} & \cdots & a_{2n} \\ \vdots & \vdots & \ddots & \vdots \\ a_{n1} & a_{n2} & \cdots & a_{nn} \end{pmatrix} \begin{pmatrix} x_1 \\ x_2 \\ \vdots \\ x_n \end{pmatrix} = \lambda \begin{pmatrix} x_1 \\ x_2 \\ \vdots \\ x_n \end{pmatrix} $$

代码是：

独立行复杂数学公式：

$$
\begin{pmatrix}
a_{11} & a_{12} & \cdots & a_{1n} \\
a_{21} & a_{22} & \cdots & a_{2n} \\
\vdots & \vdots & \ddots & \vdots \\
a_{n1} & a_{n2} & \cdots & a_{nn}
\end{pmatrix}
\begin{pmatrix}
x_1 \\ x_2 \\ \vdots \\ x_n
\end{pmatrix}
=
\lambda
\begin{pmatrix}
x_1 \\ x_2 \\ \vdots \\ x_n
\end{pmatrix}
$$

Graphviz 图表

除了数学公式，我还加了 Graphviz 图表的功能，因为我感觉也很重要。

安装 Graphviz 程序

首先需要安装 Graphviz 程序本身。

Windows

scoop install graphviz

macOS

brew install graphviz

Linux

apt install graphviz

安装 pelican-graphviz 插件

如果使用pip安装：

pip install pelican-graphviz

如果是用了uv就用：

uv add pelican-graphviz

在pelicanconf.py中修改：

PLUGINS = ["graphviz", "render_math"]

效果示例

一个比较复杂的例子：

看看效果，它的代码是：

一个比较复杂的例子：

..graphviz dot
digraph finite_state_machine {
    rankdir=LR;
    size="8,5";
    fontsize=10;
    ranksep=1.5;
    nodesep=1.0;
    overlap=false;
    splines=true;
    node [fontsize=14];
    edge [fontsize=12];
    node [shape = doublecircle]; S3 [color=red, style=filled, fillcolor=lightpink];
    node [shape = circle];
    S1 [color=blue, style=filled, fillcolor=lightblue];
    S2 [color=darkgreen, style=filled, fillcolor=lightgreen];
    subgraph cluster_guard {
        label = "守护条件：计数 < 3";
        style=dashed;
        fontsize=10;
        color=purple;
        C1 [shape=box, label="错误计数器", style=filled, fillcolor=gold, fontsize=8];
    }
    S1 -> S2 [ label = "开始", xlabel="动作：重置计数器", fontsize=10, color=blue ];
    S2 -> S1 [ label = "停止", fontsize=10, color=darkgreen ];
    S2 -> S3 [ label = "错误", xlabel="条件：增加计数器", fontsize=10, color=red ];
    S3 -> S2 [ label = "恢复", fontsize=10, color=red ];
    S2 -> C1 [style=dotted, arrowhead=none, color=purple];
}

注意：..graphviz dot代码块里不能有空行。

funcman's blog

给Pelican增加数学公式和图表的显示

MathJax 数学公式

方案选择

安装配置

各参数注解

效果示例

Graphviz 图表

安装 Graphviz 程序

安装 pelican-graphviz 插件

效果示例