Zen Architecture 渲染指南：基于 Markdown-it 与 KaTeX，从公式到高亮全方位解锁本站 Markdown 高级排版新特性与创作艺术

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

📖 目录

1. GitHub Admonitions (警告框全家族)
2. 任务列表 (Task Lists) 渲染逻辑与避坑
3. KaTeX 科学写作：公式样式详解
4. Markdown 表格用法：规范排版，清晰呈现结构化数据
5. Shiki 语法高亮：30 种常用语言速查
6. 系统级元数据：SEO 与文章控制
7. 实用技巧汇总：高效排版秘籍

1. GitHub Admonitions

在博客创作中，我们常常需要突出重点、传递不同类型的信息——比如补充说明、操作技巧、重要提醒或风险警告。本站完整集成了 GitHub 风格的所有 5 种提示框，每种都有独特的视觉语义和配色。

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

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

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

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

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

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

✨ 效果演示

NOTE

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

TIP

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

IMPORTANT

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

WARNING

Warning: 类型必须大写（如 NOTE、TIP），小写会导致渲染失败。

CAUTION

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

2. 任务列表 (Task Lists)

🔍 渲染原理

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

1. 必须是一个列表项：以 - 或 * 开头，空格不可省略。
2. 复选框标识符规范：[ ] 之间必须是小写 x 或 单个空格。
3. 无多余空格：禁止在标识符内添加额外空格（如 [ x ] 会失败）。

📝 源码对比

正确写法：

• 正确：带前置符号，标识符规范
• 正确：未完成状态，空格规范

错误写法：

[x] 错误：缺少前置符号
- [ X ] 错误：大写 X 或多余空格
- [] 错误：括号内无空格

✨ 效果演示

• 正确：我是一个可交互的复选框
• 待办：我依然保持列表缩进
• 示例：分步任务展示
  • 步骤1：学习基础语法
  • 步骤2：发布优质博客

3. KaTeX 科学写作：公式样式详解

📌 基础规则

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

A. 希腊字母与常用常数

源码示例：

`$\alpha, \beta, \gamma, \delta, \epsilon$`
`$A, B, \Gamma, \Delta, E$`
`$\pi, \phi, \theta, \lambda, \infty$`

效果演示：$\alpha, \beta, \gamma, \delta, \epsilon$|$A, B, \Gamma, \Delta, E$|$\pi, \phi, \theta, \lambda, \infty$

B. 逻辑与集合符号

源码示例： $\forall x \in \mathbb{R}, \exists y \implies x \cup y \neq \emptyset$

效果演示：$\forall x \in \mathbb{R}, \exists y \implies x \cup y \neq \emptyset$|$A \cap B, A \cup B, A \subseteq B$

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

源码示例：

效果演示：

WARNING

避坑提醒：在公式内部，直接使用 < 和 > 即可。请不要将其转义为 <，否则 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.  表格前后需空一行，避免与其他内容粘连，导致渲染异常。

✨ 基础效果演示

5. Shiki 语法高亮：30 种常用语言速查

📋 支持语言速查表

✨ 效果演示

JavaScript 示例：

function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

YAML 示例：

title: Zen Architecture 渲染指南
hidden: false
type: article

6. 系统级元数据：SEO 与文章控制

📋 元数据参数详解

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

📌 通用技巧

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

🚫 高频避坑

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