Name: 写作即排版：Markdown 的表达体系
Author: gpt-5.2

基础语法与可读性原则：从纯文本到结构化表达

第 1 章：基础语法与可读性原则：从纯文本到结构化表达

Markdown 之所以被广泛接受，并不在于它“能做多少复杂排版”，而在于它在纯文本可读性与结构化表达之间取得了稳定平衡：同一份源文本既能在不渲染时被人类顺畅阅读，也能在渲染后形成明确的层级、段落与强调关系。本章将以“最小完备语法集合”为目标，建立一套可迁移、可维护、可排错的 Markdown 写作方法。

---

1.1 概念界定：标记语言、纯文本、渲染器与方言差异

1.1.1 标记语言与“结构优先”

所谓标记语言（markup language），核心并非“装饰”，而是用一组符号把文本的逻辑结构显式化。例如：标题表示层级，列表表示并列，引用表示来源或旁注。Markdown 的设计取向可以概括为：

**结构先于样式**：你写的是“这是二级标题”，而不是“把这一行加粗变大”。
**可读先于完美**：源文本应该尽量接近自然书写，避免大量括号与闭合标签。
**约定先于配置**：用少量稳定语法覆盖大多数写作需求。

从写作到排版的角度看，Markdown 的目标是把“作者在脑中组织文本结构的过程”，尽量直接地映射到源文本中。

1.1.2 纯文本与“最小完备”

纯文本意味着：文件可以被任何编辑器打开，内容不依赖专用软件；它也意味着格式信息不会以隐藏方式存在。所谓“最小完备语法集合”，指的是完成一般短文写作所需的最小语法闭包。用集合语言可表达为：

$$ \mathcal{M}_{min}=\{\text{标题},\ \text{段落},\ \text{强调},\ \text{引用},\ \text{链接},\ \text{代码}\} $$

本章将围绕这一集合展开，并贯穿一条写作原则：让语法服务于结构，让结构反过来提升可读性。

1.1.3 渲染器与方言：为什么同一份 Markdown 会“不一样”

Markdown 并非单一标准，而是一组相关实现。常见生态包括：

**CommonMark**：致力于给出更严格的一致性规范。
**GFM（GitHub Flavored Markdown）**：GitHub 平台的常用扩展（如删除线、任务列表、表格等）。
**各类编辑器/博客/知识库的定制渲染**：可能启用或禁用部分语法。

因此，Markdown 写作存在一个“现实约束”：同一源文本在不同平台上可能渲染不同。本章的策略是：优先使用跨平台稳定语法；对差异较大的特性（如删除线、换行规则、自动链接等）提供风险提示与替代写法；并建立基本排错意识。

---

1.2 基本块级元素：段落、换行、标题层级（语义与层级约束）

1.2.1 段落：用空行定义思想的边界

在 Markdown 中，段落的划分通常依赖空行。一段话写完后，留出一行空白，表示进入下一段。空行不仅影响渲染，更是源文本可读性的关键：它将思路拆成可扫描的块。

```markdown Markdown 的核心目标是：让源文本在未渲染时仍可阅读。

空行将段落分隔开，使结构在纯文本中依然清晰。 ```

经验规范：

一段表达一个中心意思；段落过长时，读者难以定位重点。
不要用连续多个空行“堆出视觉间距”，因为不同渲染器可能合并空行。

1.2.2 换行：不要把“编辑器换行”误当作“排版换行”

多数 Markdown 渲染器会把单个换行视为“段内换行”，最终合并为同一段落的连续文字。要实现强制换行，常见方式包括：

行末加两个空格再换行（部分渲染器支持）
使用 HTML 换行标签 `<br>`（兼容性较高，但会降低纯 Markdown 的一致性）

```markdown 这一行结尾有两个空格␠␠ 下一行将被强制换行显示。 ```

写作建议：在一般文章写作中，尽量使用段落组织，而非频繁强制换行；除非你在排版诗歌、地址、表格式信息等。

1.2.3 标题：层级是语义，不是字号

标题是 Markdown 结构化表达的骨架。推荐使用 ATX 风格标题（`#`）：

`#`：一级标题（全文主题）
`##`：二级标题（章节/小节）
`###`：三级标题（子主题）

```markdown

研究笔记：信息组织的最小单元

关键术语

标记与渲染

```

层级约束（可读性原则）： 1. 避免跳级：不要从 `#` 直接到 `###`。跳级会破坏大纲结构，也会影响目录生成与无障碍阅读。 2. 控制深度：普通短文建议不超过四级标题；标题越深，说明结构越碎，可能需要重组。 3. 标题要可检索：标题应承载信息，而不是“好看”。避免“杂谈”“随记”这类不可索引词汇；可用“对象 + 角度/问题”的形式，如“链接：相对路径与可维护性”。

---

1.3 基本行内元素：强调、删除线（平台差异提示）、行内代码

行内元素的目标，是在不打断段落连续性的前提下表达局部关系：重点、术语、对比、代码符号等。它们尤其需要遵守“少而稳”的原则：过度强调会稀释重点，也会降低源文本阅读效率。

1.3.1 强调：用一致的符号表达一致的语义

Markdown 常用强调包括：

斜体：`*强调*` 或 `_强调_`
加粗：`**强调**` 或 `__强调__`

建议选择一种符号风格并保持一致（通常推荐 `*` 系列）。更重要的是语义一致性：

加粗：用于术语定义、关键结论、需要快速扫描定位的信息。
斜体：用于外来词、作品名、轻量提示或语气强调（应克制使用）。

```markdown

**标记**：用于表达结构的符号系统
*render*：渲染过程的英文术语（示例）

```

1.3.2 删除线：常见但不稳定的扩展

删除线通常写作 `~~已删除~~`，它在 GFM 等平台常见，但在部分渲染器中可能不生效。将其视为“可选增强”，而不是基础语法依赖：

若用于“修订痕迹”，应确保目标平台支持；
若用于表达对比（如“并非 A，而是 B”），可以改用文字说明替代。

```markdown 这并非 ~~排版技巧~~，而是结构表达方法。 ```

1.3.3 行内代码：把“字面值”与“自然语言”隔离

行内代码使用反引号包裹：`` `code` ``。它适合表示：

变量名、函数名、命令、文件路径、关键字
需要“按字面理解”的符号串（避免被强调或链接语法误解析）

```markdown 行内代码示例：`sum = a + b`，命令示例：`python -m pip list` ```

排错提示：当代码本身包含反引号时，需要用更长的反引号包裹，或改用代码块。

---

1.4 引用与分隔：块引用的用途（引述/提示/批注）、水平分割线

1.4.1 块引用：不仅是引用，也可以是“作者的第二声部”

块引用以 `>` 开头，常见用途包括：

1. 引述：引用他人观点、文献或原话。 2. 提示：补充条件、注意事项、例外情况。 3. 批注：在主叙述之外增加评注或旁白。

```markdown > 引用用于呈现引述、提示或批注。 ```

更复杂的引用可包含多段内容（同样需要空行控制段落）：

```markdown > 这是第一段引用。 > > 这是第二段引用，用于补充说明。 ```

可读性原则：引用不宜过长；长引用建议配合来源信息，并在引用外给出概括性导语与评价。

1.4.2 水平分割线：用于结构切分，而非装饰

水平分割线常见写法包括 `---`、`***`。它适合在语义上表示“部分之间的断裂”，例如从正文进入附录、从论述进入练习题。

```markdown --- ```

规范建议：分割线前后各留一行空行；避免把分割线当作“加粗下划线”使用，否则会造成结构误导。

---

1.5 链接与资源：相对路径与绝对路径、可维护的链接写法

1.5.1 内联链接与参考式链接：可读性与可维护性的取舍

内联链接写法直观：

```markdown 相关资源：参见 [Markdown Guide](https://www.markdownguide.org/)。 ```

当同一链接在文中多次出现，或 URL 很长时，参考式链接更利于维护，也更接近学术写作的“文末参考”习惯：

```markdown 相关资源：参见 [Markdown Guide][mdg]，并对照 [CommonMark 规范][cm]。

[mdg]: https://www.markdownguide.org/ [cm]: https://commonmark.org/ ```

建议：短文可用内联链接；中长文或技术文档更推荐参考式链接，以降低编辑成本（例如更换域名、调整路径时只需改一处）。

1.5.2 相对路径：让文档在仓库与本地都能工作

当链接指向同一项目内的文件时，优先使用相对路径，这能显著提升可迁移性：

```markdown 参见 [写作规范](docs/style-guide.md)。 ```

对比之下，绝对路径或硬编码域名在迁移仓库、切换分支、导出离线文档时更容易失效：

```markdown 不推荐：参见 [写作规范](https://example.com/docs/style-guide.md)。 ```

实践原则：

“站外资源”用绝对 URL；“站内文档”用相对路径。
对图片等资源，尽量与文档同目录或在固定资源目录下，避免散落。

---

1.6 常见错误与规范：空行、缩进、混用符号、标题跳级

Markdown 的问题往往不是“语法不会写”，而是“源文本在复杂结构下失去一致性”。下列错误最常见，也最影响跨平台渲染。

1.6.1 空行缺失：段落、列表、引用互相粘连

空行既是渲染线索，也是阅读线索。典型问题包括：

列表前缺少空行导致渲染不稳定
引用与正文紧贴，结构边界不清晰
代码块前缺空行，导致被当作普通文本

经验规则：块级结构（标题、列表、引用、代码块、分割线）前后尽量留一行空行，源文本更清晰、渲染更稳定。

1.6.2 缩进与代码块：空格会改变语义

在一些 Markdown 规则中，缩进（通常为 4 个空格或 1 个制表符）会触发代码块。若你只是为了“让段落看起来整齐”而缩进，可能意外把普通文本变成代码。

```markdown 这行可能被解释为代码块，而不是普通段落。 ```

规范建议：

普通段落不要缩进；如需“首行缩进”的版式效果，应交给排版系统（CSS/模板），而不是在源文本里用空格模拟。

1.6.3 混用符号：同一种结构不要多种写法并存

例如同一篇文章里同时使用 `-`、`*`、`+` 三种无序列表符号，会降低一致性；同理，标题既用 `#` 又用 Setext（`===`）也会造成风格漂移。

统一策略（推荐一套即可）：

标题：只用 `#` 系列
无序列表：只用 `-`
强调：只用 `*` 系列（`*`、`**`）

1.6.4 标题跳级：对读者与机器都不友好

标题跳级不仅影响阅读逻辑，也会影响自动目录、搜索摘要、屏幕阅读器等工具对结构的解析。将跳级视为“结构错误”，而不是“格式偏好”。

1.6.5 最小排错流程：从源文本结构回溯渲染问题

当渲染结果异常时，可按下列顺序定位：

1. 检查是否缺少必要空行（段落、列表、引用、代码块边界）。 2. 检查是否存在意外缩进（特别是代码块触发）。 3. 检查符号是否闭合（如强调符号、代码围栏）。 4. 检查方言差异（例如删除线是否被支持）。 5. 将复杂结构逐步“删减到最小可复现示例”，以确认触发条件。

---

1.7 综合示例：从“可读源文本”到“可渲染结构”

下面给出一份短文示例，强调“未渲染时仍可读”。读者可以对照观察：标题形成层级，列表呈现并列关系，引用承载提示，链接提供外部延伸，行内代码标注字面值。

```markdown

研究笔记：信息组织的最小单元

Markdown 的核心目标是：让源文本在未渲染时仍可阅读。

关键术语

**标记**：用于表达结构的符号系统
**渲染**：将标记解释为可视化样式的过程

> 引用用于呈现引述、提示或批注。

相关资源：参见 [Markdown Guide](https://www.markdownguide.org/)。

行内代码示例：`sum = a + b` ```

```svg <svg viewBox="0 0 400 400" width="100%" height="100%" xmlns="http://www.w3.org/2000/svg"> <defs> <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"> <stop offset="0" stop-color="#0b1220"/> <stop offset="0.55" stop-color="#0f2a4a"/> <stop offset="1" stop-color="#0f766e"/> </linearGradient>

<g transform="translate(226 78)"> <rect x="0" y="0" width="140" height="220" rx="18" fill="#0b1220" opacity="0.32"/> <rect x="0" y="0" width="140" height="220" rx="18" fill="url(#card)"/> <rect x="0" y="0" width="140" hei