数学公式与可视化图表

2025-01-01 约 4800 字预计阅读 10 分钟 - 次阅读

注意

本文最后更新于 2025-01-01，文中内容可能已过时。

KaTeX 公式、Mermaid 流程与时序图、ECharts 柱状图与折线图及环形图。

本篇属于 Markdown 语法手册。按章内目录跳转，代码块提供可复制源码，其后的正文和组件展示实际效果。

行内与块级公式

1
2
3
4
5
圆的面积为 $A = \pi r^2$。

$$
\sum_{k=1}^{n} k = \frac{n(n+1)}{2}
$$

圆的面积为 $A = \pi r^2$ 。

\sum_{k=1}^{n} k = \frac{n(n+1)}{2}

单个美元符号包裹行内公式，双美元符号包裹独立公式。本站继承主题的 Goldmark passthrough，并使用 v1 的 math.enable 和 math.type: katex，公式在构建时渲染。不要使用旧版 params.page.math。

1
2
3
math:
  enable: true
  type: katex

上面是页面 front matter 的覆盖写法。本站还启用了 params.math.katex.throw_on_error，公式语法错误会使构建失败，方便发布前发现问题。

分式、根号与下标

1
2
3
4
5
$$
f(x) = \frac{x^2 + 1}{\sqrt{x + 2}}, \qquad x > -2
$$

平均值为 $\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i$。

f(x) = \frac{x^2 + 1}{\sqrt{x + 2}}, \qquad x > -2

平均值为 $\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i$ 。

\frac 接收分子和分母，\sqrt 表示平方根，_ 和 ^ 分别表示下标和上标。超过一个字符的内容要用花括号分组，例如 x_{i+1}，否则通常只有紧接着的一个字符属于下标。

多行推导与对齐

1
2
3
4
5
6
$$
\begin{aligned}
(a+b)^2 &= (a+b)(a+b) \\
        &= a^2 + 2ab + b^2
\end{aligned}
$$

\begin{aligned} (a+b)^2 &= (a+b)(a+b) \\ &= a^2 + 2ab + b^2 \end{aligned}

aligned 环境用于对齐推导，& 指定对齐位置，两个反斜杠表示换行。正文直接写 LaTeX 时不需要像 JSON 字符串一样把所有反斜杠再次转义。

分段函数与矩阵

1
2
3
4
5
6
7
8
$$
|x| = \begin{cases}
x, & x \ge 0 \\
-x, & x < 0
\end{cases}
\qquad
A = \begin{bmatrix}1 & 2 \\ 3 & 4\end{bmatrix}
$$

|x| = \begin{cases} x, & x \ge 0 \\ -x, & x < 0 \end{cases} \qquad A = \begin{bmatrix}1 & 2 \\ 3 & 4\end{bmatrix}

cases 提供左大括号，bmatrix 提供方括号。矩阵中的 & 分隔列，两个反斜杠分隔行。手机上特别长的公式应拆分，避免为了保持一行而把文字缩到难以阅读。

公式排查清单

现象	优先检查
公式原样显示	`math.enable` 和 passthrough 配置
下标只包含一个字符	是否使用花括号分组
构建报告 KaTeX 错误	命令拼写、括号闭合、环境名称
公式太宽	改用多行推导或拆成多个块
普通金额被识别为数学内容	对字面美元符号使用反斜杠转义

不要把完整 LaTeX 文档的 documentclass 等命令复制到公式块。网页公式渲染支持的是数学表达式，不能把它当成完整的 TeX 排版系统。

Mermaid 流程图

1
2
3
4
5
6
7
{{< mermaid >}}
flowchart LR
  A[写 Markdown] --> B[本地预览]
  B --> C{检查通过?}
  C -->|是| D[生产构建]
  C -->|否| A
{{< /mermaid >}}

图表代码

flowchart LR
  A[写 Markdown] --> B[本地预览]
  B --> C{检查通过?}
  C -->|是| D[生产构建]
  C -->|否| Aflowchart LR
  A[写 Markdown] --> B[本地预览]
  B --> C{检查通过?}
  C -->|是| D[生产构建]
  C -->|否| Aflowchart LR
  A[写 Markdown] --> B[本地预览]
  B --> C{检查通过?}
  C -->|是| D[生产构建]
  C -->|否| A

1
2
3
4
5
flowchart LR
  A[写 Markdown] --> B[本地预览]
  B --> C{检查通过?}
  C -->|是| D[生产构建]
  C -->|否| A

flowchart LR 表示从左到右，改为 TD 则从上到下。节点 ID 用简短英文，方括号内显示中文。短代码可设置 wrapper=false 关闭图表工具栏；默认继承站点配置。

也可使用 Mermaid 代码块：

1
2
3
4
5
6
7
```mermaid
sequenceDiagram
  participant A as 作者
  participant H as Hugo
  A->>H: 保存文章
  H-->>A: 更新预览
```

图表代码

sequenceDiagram
  participant A as 作者
  participant H as Hugo
  A->>H: 保存文章
  H-->>A: 更新预览sequenceDiagram
  participant A as 作者
  participant H as Hugo
  A->>H: 保存文章
  H-->>A: 更新预览sequenceDiagram
  participant A as 作者
  participant H as Hugo
  A->>H: 保存文章
  H-->>A: 更新预览

1
2
3
4
5
sequenceDiagram
  participant A as 作者
  participant H as Hugo
  A->>H: 保存文章
  H-->>A: 更新预览

Mermaid 在浏览器中运行，首次打开需要访问配置中的 jsDelivr 模块。没有网络时，仍可阅读相邻的图表源码和文字说明。

时序图中的成功与失败分支

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
```mermaid
sequenceDiagram
  participant W as 作者
  participant H as Hugo
  W->>H: 提交待构建的 Markdown
  alt 语法检查通过
    H-->>W: 生成静态页面
  else 存在错误
    H-->>W: 返回文件位置和错误说明
  end
```

图表代码

sequenceDiagram
  participant W as 作者
  participant H as Hugo
  W->>H: 提交待构建的 Markdown
  alt 语法检查通过
    H-->>W: 生成静态页面
  else 存在错误
    H-->>W: 返回文件位置和错误说明
  endsequenceDiagram
  participant W as 作者
  participant H as Hugo
  W->>H: 提交待构建的 Markdown
  alt 语法检查通过
    H-->>W: 生成静态页面
  else 存在错误
    H-->>W: 返回文件位置和错误说明
  endsequenceDiagram
  participant W as 作者
  participant H as Hugo
  W->>H: 提交待构建的 Markdown
  alt 语法检查通过
    H-->>W: 生成静态页面
  else 存在错误
    H-->>W: 返回文件位置和错误说明
  end

1
2
3
4
5
6
7
8
9
sequenceDiagram
  participant W as 作者
  participant H as Hugo
  W->>H: 提交待构建的 Markdown
  alt 语法检查通过
    H-->>W: 生成静态页面
  else 存在错误
    H-->>W: 返回文件位置和错误说明
  end

participant 定义参与者，英文 ID 用来连接，as 后显示中文名称。alt、else、end 描述互斥分支。实线和虚线箭头可以区分请求与响应，但这种约定应在图附近说明。

流程图分组

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
```mermaid
flowchart TD
  subgraph Draft[写作阶段]
    A[记录想法] --> B[整理结构]
    B --> C[补齐示例]
  end
  subgraph Review[检查阶段]
    D[本地预览] --> E[检查链接]
    E --> F[生产构建]
  end
  C --> D
```

图表代码

flowchart TD
  subgraph Draft[写作阶段]
    A[记录想法] --> B[整理结构]
    B --> C[补齐示例]
  end
  subgraph Review[检查阶段]
    D[本地预览] --> E[检查链接]
    E --> F[生产构建]
  end
  C --> Dflowchart TD
  subgraph Draft[写作阶段]
    A[记录想法] --> B[整理结构]
    B --> C[补齐示例]
  end
  subgraph Review[检查阶段]
    D[本地预览] --> E[检查链接]
    E --> F[生产构建]
  end
  C --> Dflowchart TD
  subgraph Draft[写作阶段]
    A[记录想法] --> B[整理结构]
    B --> C[补齐示例]
  end
  subgraph Review[检查阶段]
    D[本地预览] --> E[检查链接]
    E --> F[生产构建]
  end
  C --> D

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
flowchart TD
  subgraph Draft[写作阶段]
    A[记录想法] --> B[整理结构]
    B --> C[补齐示例]
  end
  subgraph Review[检查阶段]
    D[本地预览] --> E[检查链接]
    E --> F[生产构建]
  end
  C --> D

subgraph 把相关步骤归成一组。纵向 TD 通常更适合手机，横向 LR 适合节点较少的流程。长说明放在正文，节点里只保留简短动作。

图表写作建议

一张图回答一个问题，避免把所有细节塞进同一张图。
节点 ID 使用稳定英文，显示文字可以改为中文。
图后补一两句话解释结论，便于读屏和无网络时阅读。
不依赖颜色作为唯一标识，同时写出节点名称和分支文字。
本主题会在图进入视口后延迟绘制，刚打开页面时未绘制的图不一定代表错误。

ECharts 柱状图

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{{< echarts width="100%" height="360px" >}}
{
  "tooltip": {"trigger": "axis"},
  "legend": {"data": ["示例数"], "top": 12},
  "grid": {"left": 45, "right": 20, "bottom": 45},
  "xAxis": {"type": "category", "data": ["基础", "扩展", "短代码", "图片", "图表"]},
  "yAxis": {"type": "value", "minInterval": 1},
  "series": [{"name": "示例数", "type": "bar", "data": [6, 6, 4, 5, 4]}]
}
{{< /echarts >}}

数据仅用于演示。width="100%" 适配容器，height 必须提供适合阅读的高度。默认内容为严格 JSON：键名和字符串使用双引号，不能加注释和尾随逗号。

xAxis 定义横轴，yAxis 定义纵轴，series 定义数据系列。将 type 从 bar 改成 line 可得到折线图。主题会根据深浅色模式初始化配色，并在尺寸变化时调整图表。

折线图：观察变化

1
2
3
4
5
6
7
8
9
{{< echarts width="100%" height="340px" >}}
{
  "tooltip": {"trigger": "axis"},
  "grid": {"left": 45, "right": 20, "top": 30, "bottom": 45},
  "xAxis": {"type": "category", "boundaryGap": false, "data": ["周一", "周二", "周三", "周四", "周五"]},
  "yAxis": {"type": "value", "name": "字数"},
  "series": [{"name": "写作字数", "type": "line", "data": [300, 600, 450, 900, 750], "smooth": false}]
}
{{< /echarts >}}

这组数据只是示例。boundaryGap=false 让折线两端贴近坐标区边界，smooth=false 用直线连接观测点，避免平滑曲线让读者误以为中间过程也经过测量。为纵轴标明单位，比只显示一列数字更清楚。

环形图：展示组成

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{{< echarts width="100%" height="360px" >}}
{
  "tooltip": {"trigger": "item"},
  "legend": {"bottom": 8},
  "series": [{
    "name": "时间分配",
    "type": "pie",
    "radius": ["38%", "64%"],
    "center": ["50%", "43%"],
    "label": {"show": false},
    "data": [
      {"name": "写作", "value": 50},
      {"name": "校对", "value": 30},
      {"name": "整理", "value": 20}
    ]
  }]
}
{{< /echarts >}}

radius 的两个值分别是内、外半径；内半径大于零时形成环形图。示例隐藏外侧标签以适配小屏，通过图例和提示框读取类别。为了让不操作图表的读者也能获得数据，正文再给出一份表格：

活动	示例占比
写作	50%
校对	30%
整理	20%

参数与排查

参数或现象	说明
`tooltip.trigger`	`axis` 适合坐标轴图；`item` 适合扇区等独立图形
`grid`	控制坐标区域的留白，避免刻度被裁剪
`legend`	展示系列或类别名称，可用于切换显示
图表空白	检查浏览器脚本是否加载，以及 JSON 是否有效
图表高度为零	给短代码设置明确的 `height`
标签挤在一起	缩短标签、减少刻度或调整布局

这三个示例都使用主题本地 ECharts 资源，不需要额外启用旧版 params.page 配置。图表内部颜色承担数据区分作用，与站点正文颜色不必完全相同；仍应检查深浅模式下的对比度。

Markmap：用 Markdown 写思维导图

Markmap 适合把标题和列表转换成可展开的知识结构。本站已安装官方 cmpt-markmap 组件，普通文章使用 markmap 代码围栏即可，不需要更改文章布局。

可复制源码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
```markmap {height="360px"}
# Markdown 写作
## 组织内容
- 标题与段落
- 列表与引用
## 丰富表达
- 图片与链接
- 代码与公式
## 发布检查
- 本地预览
- 链接与移动端
```

实际效果：

标题构成主分支，列表构成子节点；点击节点圆点可以折叠或展开，工具栏支持缩放、适配视口与全屏。上图把写作分成组织内容、丰富表达、发布检查三部分。

配置	说明
围栏语言 `markmap`	将代码块渲染成思维导图
`height="360px"`	图表区域高度，省略时为 `24rem`
页面 `layout: markmap`	可选的全文分栏导图布局；普通文章无需设置
`params.markmap` 或页面 `markmap`	配置键使用 `snake_case`，如 `color_freeze_level`
围栏内 YAML 的 `markmap`	使用 Markmap 原生 `camelCase`，如 `colorFreezeLevel`

组件根据内容渲染标记加载资源；首页处理含导图文章的摘要时也可能加载 Markmap 资源。导图运行时会从 CDN 获取依赖，需要网络；因此保留上方源码和文字说明，便于复制与阅读。

收录于合集・Markdown 语法 5

富文本写作：图片、链接与代码文章模板与写作发布流程