songlin.me

当前博客基于 Markdown-it 与 KaTeX，公式高亮表格语法 Markdown 高级排版新特性

Zen Architecture v9 核心文档：本指南深度解析了本站所采用的增强型 Markdown 语法。通过本指南，您可以掌握从基础排版到复杂科学绘图的所有技术细节，轻松实现“写得顺手、看得美观”的创作体验，无论是技术博客、学术笔记还是日常分享，都能快速提升排版质感。

目录

  1. 警告框提示：分类传递信息，提升阅读效率
  2. 任务列表： 渲染逻辑与避坑
  3. KaTeX 科学写作：公式样式详解
  4. 表格用法：规范排版，清晰呈现结构化数据
  5. Shiki 语法高亮：30 种常用语言速查
  6. 系统级元数据：SEO 与文章控制
  7. 实用技巧汇总：高效排版秘籍

1. 警告框提示

在博客创作中，我们常常需要突出重点、传递不同类型的信息——比如补充说明、操作技巧、重要提醒或风险警告。本站完整集成了 GitHub 风格的所有 5 种提示框，每种都有独特的视觉语义和配色，既能区分信息优先级，又能让页面更具层次感，避免大段文字的单调感。

提示框的核心价值的是“分类引导”：让读者在快速浏览时，能瞬间捕捉到关键信息类型，无需逐字阅读就能 get 重点。以下是完整写法、效果演示及适用场景，方便你直接复制使用。

标准写法（直接复制可用）

> [!NOTE]
> 这是一个普通笔记 (Note)。
> 可用于补充背景信息、相关参考资料，或对正文内容进行补充说明。

> [!TIP]
> 这是一个技巧提示 (Tip)。
> 适合分享高效操作方法、小窍门，帮助读者更便捷地完成相关操作。

> [!IMPORTANT]
> 这是一个重要声明 (Important)。
> 用于强调读者在继续阅读或操作前，必须了解的关键信息。

> [!WARNING]
> 这是一个避坑警告 (Warning)。
> 提醒读者注意潜在问题，防止出现非预期结果。

> [!CAUTION]
> 这是一个危险警告 (Caution)。
> 极其严重的警告，涉及数据丢失、安全风险等。

效果演示

NOTENote: 用于补充背景信息或相关参考。例如：本文中所有语法示例均基于 Zen Architecture v9 版本。

TIPTip: 帮助用户更高效地完成任务的小窍门。例如：在编写提示框时，可在开头添加 emoji 符号。

IMPORTANTImportant: 读者在继续之前必须了解的关键信息。例如：所有 Markdown 语法需在编辑器中切换至“预览模式”查看效果。

WARNINGWarning: 类型不区分大小写（如 NOTE、note 均可），渲染器会自动将其标准化为大写。

CAUTIONCaution: 修改文章元数据中的 hidden: true 后，文章将从列表页隐藏。

实用技巧

  • 提示框支持多行文本，换行时需保持>前缀，否则会中断提示框样式。

  • 可在提示框内嵌套代码、链接等语法，例如：

    > [!TIP]
> 推荐使用 `Ctrl+S` 快速保存编辑内容。

  • 避免过度使用提示框，重点内容用 Important/Warning/Caution，次要内容用 Note/Tip，保持页面整洁。

2. 任务列表

任务列表是博客创作中常用的排版元素，适合用于记录待办事项、步骤清单、需求列表等场景。本站基于markdown\-it\-task\-lists 插件实现任务列表渲染，支持交互效果（点击复选框切换完成状态），但该插件对语法要求极其严苛，稍有疏忽就会导致渲染失败，变成普通文本。

本节将详细讲解渲染原理、正确写法、避坑指南，帮你快速掌握任务列表的使用技巧，避免踩坑。

渲染原理

任务列表想要成功渲染为可交互的复选框，必须同时满足以下 3 个条件，缺一不可：

  1. 必须是一个列表项：以 - （短横线+空格）或* （星号+空格）开头，空格不可省略（必须是 1 个空格）。
  2. 复选框标识符规范：[ 与 ] 之间必须是小写x（表示已完成）或 单个空格（表示未完成），不可有多个空格、大写 X 或其他字符。
  3. 无多余空格：[x]或[]前后的空格需严格控制，禁止在标识符中添加额外空格（例如 [ x ] 会渲染失败）。

避坑指南（高频问题汇总）

如果您发现 [x] 没有变成复选框，而是显示为普通文本，大概率是以下几种情况导致的，对照排查即可快速解决：

  • 遗漏前置列表符号：没有写 - 或 * ，直接写 [x] 内容，会被识别为普通文本。

  • 标识符空格错误：[x] 写成[ x ]（括号内多空格）、[X]（大写 X），或 [] 括号内无空格。

  • 缩进错误：任务列表需要左对齐，若缩进过多（如 4 个空格、1 个制表符），可能会被识别为嵌套列表，导致渲染异常。

源码对比

# 正确写法（3种均可，推荐第一种）
- [x] 正确：带前置符号，标识符规范，渲染成功
- [ ] 正确：未完成状态，空格规范
* [x] 正确：使用星号作为列表符号

# 错误写法（常见踩坑）
[x] 错误：缺少前置 - 或 *，无法渲染为复选框
- [ X ] 错误：括号内多空格+大写 X
- [] 错误：括号内无空格
  - [x] 错误：前置多缩进（2个空格），可能渲染异常

效果演示

实用技巧

  • 任务列表支持嵌套：在父任务下缩进 2 个空格，添加子任务，可实现层级分类（如上述步骤示例）。

  • 可在任务文本后添加备注，例如：- [x] 完成文章初稿 （截止日期：2026\-04\-20）。

  • 批量编辑：在编辑器中，选中多个任务列表项，可快速切换完成/未完成状态（具体快捷键因编辑器而异）。

3. KaTeX 科学写作

对于技术博客、学术笔记、数学/物理相关分享，公式排版是核心需求。本站集成了 KaTeX 公式渲染引擎，支持从基础运算到复杂矩阵、方程组的全方位渲染，排版美观、加载快速，且兼容绝大多数 LaTeX 语法，无需额外配置，直接书写即可生效。

本节将重点讲解常用公式样式、符号用法及环境演示，涵盖希腊字母、逻辑符号、箭头算子、方程组、矩阵等高频场景，帮你轻松搞定科学写作的公式排版。

基础规则

  • 行内公式：用单个 $ 包裹，例如α+β=γ\alpha + \beta = \gamma。
  • 独立公式：用两个 $$ 包裹，例如
    E=mc2E=mc^2

A. 希腊字母与常用常数

希腊字母是科学写作的基础，KaTeX 支持大小写希腊字母，小写直接拼写，大写首字母大写即可；常用常数（如圆周率 π、无穷大 ∞）也可直接通过指令调用。

源码示例：

# 源码
$\alpha, \beta, \gamma, \delta, \epsilon$  # 小写希腊字母
$\Alpha, \Beta, \Gamma, \Delta, \Epsilon$  # 大写希腊字母
$\pi, \phi, \theta, \lambda, \infty$  # 常用常数与符号
$\sqrt{2}, \sqrt[3]{8}, \pi \approx 3.14159$  # 根号与近似

效果演示：

α,β,γ,δ,ϵ\alpha, \beta, \gamma, \delta, \epsilon|A,B,Γ,Δ,E\Alpha, \Beta, \Gamma, \Delta, \Epsilon|π,ϕ,θ,λ,∞\pi, \phi, \theta, \lambda, \infty|2,83,π≈3.14159\sqrt{2}, \sqrt[3]{8}, \pi \approx 3.14159

B. 逻辑与集合符号

在算法、数学证明、逻辑推理类博客中，逻辑与集合符号使用频繁，以下是常用符号的写法及效果，直接复制即可使用。

源码示例：

# 源码
$\forall x \in \mathbb{R}, \exists y \implies x \cup y \neq \emptyset$  # 全称、存在、蕴含、集合
$A \cap B, A \cup B, A \subseteq B, A \supseteq B$  # 集合运算
$\neg p, p \land q, p \lor q, p \oplus q$  # 逻辑运算（非、与、或、异或）
$\mathbb{N}, \mathbb{Z}, \mathbb{Q}, \mathbb{R}, \mathbb{C}$  # 数集（自然数、整数、有理数等）

效果演示：

∀x∈R,∃y  ⟹  x∪y≠∅\forall x \in \mathbb{R}, \exists y \implies x \cup y \neq \emptyset|A∩B,A∪B,A⊆B,A⊇BA \cap B, A \cup B, A \subseteq B, A \supseteq B|¬p,p∧q,p∨q,p⊕q\neg p, p \land q, p \lor q, p \oplus q|N,Z,Q,R,C\mathbb{N}, \mathbb{Z}, \mathbb{Q}, \mathbb{R}, \mathbb{C}

C. 环境演示：大括号组与矩阵

对于方程组、分段函数、矩阵等复杂公式，需要使用 KaTeX 环境进行排版，以下是最常用的两种环境示例，可根据需求修改内容。

源码示例：

# 源码（方程组与矩阵）
$$
\begin{cases} 
3x + 5y = 2 \\  # 方程组第一行
x - 2y = 8      # 方程组第二行（\\ 表示换行）
\end{cases}
\quad \text{AND} \quad  # 空格分隔两个公式
\begin{pmatrix} 1 & 0 \\ 0 & 1 \end{pmatrix}  # 矩阵（小括号）
$$

# 源码（分段函数）
$$
f(x) = 
\begin{cases} 
x^2, & x \geq 0 \\  # 逗号后空格用于对齐
-x, & x < 0          # 直接使用 < 即可，无需转义
\end{cases}
$$

效果演示：

{3x+5y=2x−2y=8AND(1001)\begin{cases} 3x + 5y = 2 \\ x - 2y = 8 \end{cases} \quad \text{AND} \quad \begin{pmatrix} 1 & 0 \\ 0 & 1 \end{pmatrix}
f(x)={x2,x≥0−x,x<0f(x) = \begin{cases} x^2, & x \geq 0 \\ -x, & x < 0 \end{cases}

D. 箭头与算子

箭头用于表示方向、映射、推导关系，算子用于表示运算（如求和、求积、求导），以下是高频用法示例。

# 源码
$A \xrightarrow{f} B, A \leftarrow B, A \leftrightarrow B$  # 映射与双向箭头
$\uparrow, \downarrow, \updownarrow, \Rightarrow, \Leftarrow$  # 方向与推导箭头
$\pm, \mp, \times, \div, \cdot$  # 运算符号
$\sum_{i=1}^{n} x_i, \prod_{i=1}^{n} x_i, \lim_{x \to 0} f(x)$  # 算子（求和、求积、极限）
$\frac{dy}{dx}, \frac{\partial f}{\partial x}$  # 导数与偏导数

效果演示：

A→fB,A←B,A↔BA \xrightarrow{f} B, A \leftarrow B, A \leftrightarrow B|↑,↓,↕,⇒,⇐\uparrow, \downarrow, \updownarrow, \Rightarrow, \Leftarrow|±,∓,×,÷,⋅\pm, \mp, \times, \div, \cdot|∑i=1nxi,∏i=1nxi,lim⁡x→0f(x)\sum_{i=1}^{n} x_i, \prod_{i=1}^{n} x_i, \lim_{x \to 0} f(x)|dydx,∂f∂x\frac{dy}{dx}, \frac{\partial f}{\partial x}

WARNING避坑提醒：在公式内部，直接使用 < 和 > 即可。请不要将其转义为 &lt;，否则 KaTeX 引擎会报错。

4. 表格用法

表格是呈现结构化数据的核心元素，适合展示对比、分类、统计类信息（如参数说明、语言速查、步骤对比等），本站支持标准 Markdown 表格语法，同时兼容对齐、合并单元格等常用进阶功能，语法简洁、渲染美观，无需额外配置即可使用。

本节将详细讲解表格的基础写法、对齐方式、进阶用法及避坑要点，结合实际场景示例，帮你快速掌握表格排版技巧，让结构化数据展示更清晰。

基础写法

Markdown 表格由“表头+分隔线+表体”三部分组成，分隔线用于区分表头与表体，同时控制列的对齐方式，基础语法简洁易懂，直接复制修改即可使用。

# 基础表格（默认左对齐）
| 表头1 | 表头2 | 表头3 |
| --- | --- | --- |
| 内容1-1 | 内容1-2 | 内容1-3 |
| 内容2-1 | 内容2-2 | 内容2-3 |
| 内容3-1 | 内容3-2 | 内容3-3 |

# 说明
1.  竖线 `|` 用于分隔列，表头与表体的竖线需对齐（可不用严格对齐字符数，渲染时会自动适配）；
2.  分隔线 `---` 不可省略，至少需要 3 个连字符，用于区分表头和表体；
3.  表格前后需空一行，避免与其他内容粘连，导致渲染异常。

基础效果演示

表头1表头2表头3
内容1-1内容1-2内容1-3
内容2-1内容2-2内容2-3
内容3-1内容3-2内容3-3

进阶用法：列对齐

通过在分隔线 --- 前后添加冒号 :，可控制列的对齐方式，满足不同数据展示需求（如数字右对齐、文本居中对齐），三种对齐方式如下：

# 对齐方式示例（推荐写法）
| 左对齐 | 居中对齐 | 右对齐 |
| :--- | :---: | ---: |
| 文本1 | 文本2 | 数字100 |
| 文本3 | 文本4 | 数字200 |
| 文本5 | 文本6 | 数字300 |

# 对齐规则
- 左对齐：分隔线左侧加冒号 `:---`（默认对齐方式，可省略冒号）；
- 居中对齐：分隔线两侧加冒号 `:---:`；
- 右对齐：分隔线右侧加冒号 `---:`；
- 可单独设置某一列的对齐方式，不影响其他列。

对齐效果演示

左对齐居中对齐右对齐
文本1文本2数字100
文本3文本4数字200
文本5文本6数字300

避坑提醒（高频问题）

  • 分隔线不可省略：缺少 --- 会导致表格无法渲染，仅显示普通文本；分隔线至少需要3个连字符，不可少于3个。

  • 竖线对齐：表头与表体的竖线需一一对应，不可多列或少列，否则会出现表格错位。

  • 表格前后需空一行，避免与其他内容粘连导致渲染异常。

  • 内容换行：表格单元格内换行需用 <br> 标签，例如：内容1<br>内容2，直接换行会导致表格错乱。

  • 特殊字符：单元格内若包含 | 符号，需用 \| 转义，否则会被识别为列分隔符，导致表格异常。

实用技巧

  • 简洁排版：表格列数不宜过多（建议不超过5列），避免移动端显示错乱；内容较短时，可适当压缩列宽，提升阅读舒适度。

  • 内容嵌套：单元格内可嵌套代码、链接、emoji等语法，例如：

    | 语法 | 示例 |
| --- | --- |
| 链接 | [示例](https://xxx.com) |

  • 模板复用：将常用表格模板（如参数说明表、对比表）保存，下次创作直接复制修改，节省排版时间。

5. Shiki 语法高亮

技术博客的核心是代码展示，一个清晰、美观的语法高亮能极大提升阅读体验，让代码结构一目了然。本站采用 Shiki 语法高亮引擎，支持 30 种主流编程语言、配置文件语法，无需额外引入插件，只需在代码块标记后添加对应语言别名，即可实现自动高亮。

Shiki 高亮的优势在于：颜色搭配舒适、语法识别精准、支持多种主题（本站默认采用 Tokyo Night 主题，深色背景搭配高对比度着色，兼顾可读性与美观度），以下是完整的支持语言速查表格，按类别划分，方便快速查找。

支持语言速查表

类别支持语言别名(用于```后)示例
前端js, ts, jsx, tsx, vue, html, css, less, sassjs console.log(“Hello Zen Architecture”);
后端go, rust, python (py), java, cpp (c++), c, php, ruby, sqlpython print(“Hello Markdown”)
配置/运维bash (sh), yaml, json, toml, docker, nginx, ini, makefilebash npm install markdown-it
科学/其他latex, markdown (md), diff, xml, wasmlatexα+β=γ\alpha + \beta = \gamma

效果演示（以常用语言为例）

示例1：JavaScript（js）

// 计算斐波那契数列
function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

// 调用函数并打印结果
const result = fibonacci(10);
console.log(`斐波那契数列第10项：${result}`); // 输出 55

示例2：Python（py）

# 读取文件内容并统计行数
def count_lines(file_path):
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            lines = f.readlines()
            return len(lines)
    except FileNotFoundError:
        print(f"错误：文件 {file_path} 不存在")
        return 0

# 测试函数
file_lines = count_lines("test.md")
print(f"文件总行数：{file_lines}")

示例3：YAML（配置文件）

# 文章元数据示例
title: Zen Architecture 渲染指南
publish_time: 2026-04-25
keywords:
  - 博客
  - Markdown
hidden: false
noindex: false
type: article

实用技巧

  • 语言别名不区分大小写：例如 JS、js 均可识别，但推荐使用小写（规范写法）。

  • 部分语言支持别名：例如 c++ 可简写为 cpp，sh 可简写为 bash，两种写法均生效。

  • 代码块换行：在编辑器中直接换行即可，Shiki 会自动保留换行格式，无需额外添加换行符。

  • 代码块高亮主题：本站默认使用 Tokyo Night 主题，若需自定义主题，可在文章元数据中添加 highlight_theme 参数（目前支持 light/dark 两种）。

6. 系统级元数据

元数据（YAML Front Matter）是控制文章行为、优化 SEO 的核心工具，通过在文章开头添加元数据，你可以自定义文章标题、发布时间、关键词、显示状态等，让文章更易被搜索引擎收录，同时控制文章在站点中的展示方式。

元数据采用 YAML 语法，包裹在 --- 之间，位于文章最顶部，语法严格，参数不可写错（否则会导致渲染异常）。以下是详细的参数说明、可选值及高阶用法示例。

元数据参数详解

参数描述示例值
title文章标题Zen Architecture 渲染指南
publish_time发布日期2026-04-25
keywords关键词数组[博客, Markdown, KaTeX]
hidden是否从列表页隐藏true / false
noindex是否禁止搜索引擎索引true / false
type页面类型article / page
updates更新历史日期数组[2026-04-25]
cover封面图链接https://example.com/img.jpg

高阶写法示例

以下是不同场景的元数据示例，可根据自身需求修改参数：

# 示例1：普通博客文章（推荐配置）
---
title: Zen Architecture 渲染指南：从基础到高级的 Markdown 排版技巧
publish_time: 2026-04-25
keywords: [博客, Markdown渲染, KaTeX, Shiki, Zen Architecture]
cover: https://images.unsplash.com/photo-1542831371-29b0f74f9713?auto=format&fit=crop&q=80&w=1000
updates: [2026-04-25, 2026-04-26]
---

# 示例2：导航栏页面（如“关于我”）
---
title: 关于我
type: page
hidden: false
noindex: false
keywords: [About, 个人介绍, CV]
cover: https://xxx.com/avatar.jpg
---

# 示例3：私密测试文章（不公开、不收录）
---
title: Markdown 语法测试文章
publish_time: 2026-04-25
hidden: true
noindex: true
keywords: [测试, Markdown]
---

避坑提醒

  • 元数据必须位于文章最顶部，且前后必须用 ---包裹，否则会被识别为普通文本。

  • 日期格式必须严格遵循 YYYY-MM-DD（例如：2026-04-25 正确，2026/04/25、2026年4月25日 错误）。

  • 数组参数（如 keywords、updates）需用 [ ] 包裹，元素之间用逗号分隔，不可遗漏逗号。

  • 参数值若包含特殊字符（如冒号、空格），需用引号包裹，例如：title: “Zen Architecture: 渲染指南“。

7. 实用技巧汇总：高效排版秘籍

通用技巧

  • 标题层级：严格遵循 ## -> ### -> #### 的递进关系。
  • 段落间距：段落之间务必保持一个空行，以确保解析器正确切分段落。
  • 脚注使用：在正文中使用 [^1]，在文末定义 [^1]: 说明内容。[1]

高频避坑

  • 代码块标识：确保 ``` 后面紧跟语言别名，中间不要有空格。
  • 元数据格式：日期必须严格遵循 YYYY-MM-DD 格式。

  1. 脚注演示：用于补充参考资料，不影响正文阅读。 ↩︎