空垠尘

Markdown 排版规范与高阶扩展实践

· 约 2608 字 · 需 6 分钟
/ /
#Markdown #排版规范 #LaTeX #Mermaid #技术写作

引言：纯文本写作的优雅力量

2004 年，约翰·格鲁伯（John Gruber）与阿隆·斯沃茨（Aaron Swartz）共同发明了 Markdown 标记语言。其设计的初衷非常纯粹：“让人们能够使用易读易写的纯文本格式编写文档，并能够将其轻松转换为结构良好的 XHTML 或 HTML。”

在现代软件工程与技术写作领域，Markdown 已经成为事实上的通用排版标准。无论是 GitHub 上的开源项目说明（README.md）、技术博客的文章记录，还是企业内部的架构设计文档，Markdown 都以其极轻的语法负担、极佳的版本控制友好性，赢得了无数开发者的青睐。

然而，在实际写作中，“写出 Markdown”和“写出专业、工整且具高度可读性的 Markdown”之间，往往存在着巨大的排版差距。本文将从 基础排版规范、中英文混排美学 以及 高阶扩展语法（LaTeX 公式与 Mermaid 架构图） 三个维度，系统性地梳理 Markdown 的写作实践。

一、 Markdown 核心基础排版规范

1. 语义化标题结构与层级严格性

标题是文档大纲与阅读目录（TOC）的单一事实来源。在技术排版中，必须遵守严格的层级递进规则：

  • 一级标题 (#)：单篇文章仅建议出现一次，通常由博客系统的文章元数据（Frontmatter title）自动作为主标题渲染；
  • 二级标题 (##)：代表文章的核心独立大章；
  • 三级标题 (###)：大章内部的具体知识模块；
  • 严禁跨层级使用：例如在 ## 下直接跳跃使用 ####，这会导致自动生成的目录导航（TOC）结构断裂。
1<!-- 正确示范：严格逐级递进 -->
2## 1. 架构设计原则
3### 1.1 单一职责
4### 1.2 开放封闭
5
6<!-- 错误示范：跳级使用导致大纲解析混乱 -->
7## 1. 架构设计原则
8#### 1.1 单一职责 (跳过了 H3)

2. 列表排版与嵌套缩进规范

列表能将散乱的信息结构化呈现。但在多级列表混排时，空格与缩进是常见的格式崩塌点：

  • 无序列表：推荐统一使用减号 -，同级列表项符号必须全局一致，切勿在同一篇文章中混用 *、+ 和 -；
  • 嵌套缩进：子列表必须相较于父级缩进 2 个空格或 4 个空格（建议全站统一为 2 个空格）；
  • 列表间距：紧凑型列表项之间无需空行，若某一项包含多段文字或代码块，则整个列表建议使用松散型空行分隔。
1- **核心中间件层**
2  - 身份鉴权拦截器（JWT / WebAuthn 校验）
3  - 访问限流中间件（基于 Token Bucket 算法）
4- **数据持久化层**
5  - SQLite WAL 关系型存储
6  - 全局只读 KV 缓存

3. 代码块与语法高亮规范

代码块是技术文档的核心组成部分。优秀的排版应当满足可读性与功能性的双重要求：

  1. 显式声明语言标识：在三个反引号后，必须明确标明编程语言的代号（如 go、typescript、rust、bash、json、sql 等）。这不仅能触发 Chroma 或 Prism 的语法高亮引擎，更能让前端代码卡片正确显示语言 Badge 并启用一键复制功能；
  2. 区分行内代码与块级代码：
    • 文件路径（如 /etc/hosts）、命令选项（如 --minify）、变量名（如 userToken）必须使用单个反引号包裹；
    • 包含多行逻辑的程序片段，必须使用独立代码块。
1// 声明语言标识为 typescript
2interface UserSession {
3  userId: string;
4  role: "admin" | "member";
5  expiresAt: number;
6}

4. 引用块（Blockquote）的层次感

引用块通常用于引经据典、特别声明、核心结论或设计准则的突出强调：

  • 可以通过多个 > 符号实现多级嵌套引用；
  • 可以在引用块内部嵌套使用加粗、斜体、列表甚至代码块。

核心设计准则：

“简单性是可靠性的先决条件。在满足业务需求的前提下，最优秀的代码往往是那些被精简掉的代码。”

—— 艾兹格·迪杰斯特拉（Edsger W. Dijkstra）

二、 中英文混排美学与排版细节

一份专业的文档不仅在于语法无误，更体现在对标点符号与空白字符等微小细节的雕琢上。

1. 中英文与数字之间的“盘古之白”

在中文排版传统中，汉字属于全角方块字，而英文字母与阿拉伯数字属于半角字符。当中文与英文/数字直接贴合在一起时，视觉上会显得极其拥挤。

  • 推荐做法：在中文字符与英文字符、中文与数字之间，主动保留一个半角空格；
  • 排版对比：
    • ❌ 差评：我们在2026年使用Hugo编译了全站的HTML文件。
    • ✅ 推荐：我们在 2026 年使用 Hugo 编译了全站的 HTML 文件。

2. 标点符号的准确使用

  • 中文主句：必须使用标准的全角标点符号（，。！？；：“”‘’（））；
  • 英文短语与代码段内：必须使用标准的半角标点符号（, . ! ? : "" '' ()）；
  • 避免中英标点混用：中文句子结尾切勿使用英文半角句号 .。

三、 Markdown 进阶扩展功能实战

现代纯静态博客通过集成 KaTeX 与 Mermaid 渲染引擎，使 Markdown 能够原生渲染复杂的科学公式与软件架构图。

1. 原生 LaTeX / KaTeX 数学公式排版

无需截取低分辨率的图片，直接在 Markdown 中书写标准 LaTeX 语法即可完成高精度排版。

(1) 行内数学公式（Inline Math）

使用单个美元符号 $ 包裹公式，常用于正文中穿插参数或简短等式：

  • 质能方程：$E = mc^2$
  • 欧拉恒等式：$e^{i\pi} + 1 = 0$
  • 正态分布概率密度函数：$f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2}$

(2) 块级独立公式（Display Math）

使用双美元符号 $$ 包裹独立公式块，公式将居中排版并保留完整的上下标与积分范围：

  • 高斯积分公式： $$ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} $$

  • 离散傅里叶变换 (DFT)： $$ X_k = \sum_{n=0}^{N-1} x_n \cdot e^{-i \frac{2\pi}{N} k n} \quad (k = 0, 1, \dots, N-1) $$

  • 麦克斯韦方程组（微分形式）： $$ \begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \ \nabla \cdot \mathbf{B} &= 0 \ \nabla \times \mathbf{E} &= -\frac{\partial \mathbf{B}}{\partial t} \ \nabla \times \mathbf{B} &= \mu_0 \mathbf{J} + \mu_0 \varepsilon_0 \frac{\partial \mathbf{E}}{\partial t} \end{aligned} $$

2. Mermaid 矢量流程图与架构图

在文本中声明 ```mermaid 代码块，浏览器将在前端动态渲染为矢量 SVG 图表，支持深浅色模式自适应。

(1) 现代边缘架构流程图 (graph LR)

flowchart LR
    Client["终端访客"] -->|"HTTPS / HTTP/3"| CDN["Cloudflare 边缘网络"]
    CDN -->|"缓存命中 (&lt; 10ms)"| EdgeCache["Edge Cache 边缘缓存"]
    CDN -->|"缓存未命中"| Pages["Cloudflare Pages 静态分发"]
    Pages -->|"纯净渲染"| Storage["Markdown 内容库"]

(2) OAuth 2.1 PKCE 状态机交互时序图 (sequenceDiagram)

sequenceDiagram
    autonumber
    actor User as 用户
    participant Client as 前端应用
    participant Authz as 认证服务
    participant API as 业务 API

    User->>Client: 点击通行密钥 Passkey 登录
    Client->>Client: 生成 code_verifier 与 challenge
    Client->>Authz: 发起授权请求 /authorize
    Authz->>User: 触发 WebAuthn 硬件密钥验签
    User-->>Authz: 验证指纹或人脸成功
    Authz-->>Client: 返回临时授权码 Code
    Client->>Authz: 兑换令牌 /token
    Authz->>Authz: 校验签名与 challenge 一致
    Authz-->>Client: 签发 JWT Access Token
    Client->>API: 携带 Token 请求业务数据
    API-->>Client: 200 OK 返回受保护资源

四、 总结：Docs as Code 的工程哲学

在现代技术实践中，“文档即代码（Docs as Code）”的理念正日益成为共识：

  1. 版本控制：文档与源码一同保存在 Git 仓库中，每次修改都有迹可循；
  2. 规范化治理：通过统一的排版规范与样式约定，确保团队产出高标准的知识资产；
  3. 内容与展示分离：纯净的 Markdown 专注于内容本身的逻辑严密性，而视觉呈现交由现代静态渲染引擎全权处理。

养成规范、严谨的排版习惯，不仅能让技术总结更加清晰，更能让每一次阅读都成为一种享受。

文章目录