Markdown 语法指南

知识点地图#

本篇是 002-markdown 模块的入口与总览，属于「基础语法」知识类别。

解决什么问题：第一次接触 Markdown 时不知道从哪学起、学多少才够用， 以及「为什么我写的语法没生效」这类新手困惑的总根源。

什么时候用到：装好编辑器的第一天；或者写作中反复踩坑、想回头系统 梳理一遍底线规则的时候。

读完你能得到：一张覆盖日常写作 90% 的最小语法表、两条解释一切 「怪脾气」的设计原则（纯文本、空白即语法）、以及本模块 33 篇的 分层学习路径。

1. 从一个真实任务开始#

今天你要给团队项目补一份 README。打开 GitHub 的编辑框，你其实已经 被 Markdown 包围了：issue、PR 描述、代码评审、聊天软件的代码块、 几乎所有的笔记与文档工具——2004 年诞生至今，它成了开发者的通用 书写层。

本仓库（FANDEX）就是一个活样本：cnt-content/full/002-markdown/ 下的 33 篇文档全部用 Markdown 书写，经构建管线变成网页、桌面端与 Android 端三份读物。你在读的这一篇，就是一份真实生产环境里的 Markdown 源文件。

所以学习目标很具体：读完本篇，你能独立写出结构清晰的 README， 并且知道剩下的 32 篇该按什么顺序学、学到什么程度。

2. 动手：五分钟建立正反馈#

准备一个能实时预览的编辑器：VS Code（新建 .md 文件，右上角 「打开侧边预览」）、Obsidian 或 Typora 均可。然后把这 8 个符号 挨个敲一遍，每敲一个就看一眼预览：

表格的完整写法（第二行的 --- 是分隔线，冒号控制对齐）：

| 命令         | 作用     |
| :----------- | :------- |
| npm install  | 安装依赖 |
| npm run dev  | 本地开发 |

第一课的判断标准：这 8 个符号你已经能不看表写出来，就足以覆盖 日常写作的 90%。剩下的语法不是不学，而是等遇到再学（见第 4 节路径）。

同一套语法，三个真实场景——验证「最小集够用」这件事不是说说而已：

场景一：项目 README。# 写项目名，一段话写简介，有序列表写 安装步骤，表格列命令。读者是第一次打开仓库的人，结构清晰比内容多 更重要——这就是为什么 README 的 H1 全仓库只该有一个。

场景二：GitHub 上报一个 bug。步骤用有序列表（复现路径必须有序）， 报错信息用行内代码或代码块包住（保留换行与缩进，否则堆成一团）， 期望行为与实际行为加粗对比。维护者拿到 issue 能不能一眼看懂， 取决于你列表和代码块用得对不对。

**期望**：点击保存后提示成功
**实际**：控制台报 `TypeError: Cannot read properties of undefined`

复现步骤：
1. 打开设置页
2. 清空昵称后点保存

场景三：团队周报或会议纪要。小节用 ##，各人进展用任务列表 - [x] / - [ ]（见 170），待决议事项用引用块 > 框出来。三个 场景用的是完全相同的符号——这正是 Markdown 作为「通用书写层」的 价值：学一次，处处能用。

3. 为什么 Markdown 长这样#

理解两条设计决策，后面所有「怪脾气」都能解释：

一、它是纯文本。不像 Word 存的是私有二进制格式，Markdown 文件 用任何编辑器打开都能读，能进 Git 做版本对比，能被程序解析、转换、 批量处理。这也是为什么它成了开源世界的默认文档格式。

二、空白即语法。Markdown 用「不可见的空白」承载结构，这是它 上手快的原因，也是新手坑的来源。两条铁律先记住：

1. 语法标记后必须有空格：# 标题 生效，#标题 不生效；
2. 段落之间必须空一行：没有空行的连续文字会被合并成一段。

遇到「看起来写了但没生效」，第一反应永远是：检查空格和空行。

方言问题一句话说清。Markdown 早期规范模糊，各平台自行扩展 （GitHub 的 GFM 最成功），2014 年起 CommonMark 项目制定了无歧义 标准，GFM 即在它之上扩展。你只需要知道：核心语法（本模块 020-100 篇）在哪都一样；扩展语法（表格、任务列表、删除线等 GFM 能力，以及 数学公式、Mermaid 图表）在 GitHub、VS Code、Obsidian 等主流环境 也都可用，但写到「任何渲染器」时要用 110 篇的兼容性思维检查。

4. 学习路径与分层（本模块导航）#

本模块有 33 篇文档，不要按编号顺序阅读。Markdown 的学习应该 像学写字：先会写最常用的字，再学排版，最后才研究字体原理。按三层 递进：

Layer 0 生存层（第一周，覆盖日常写作 90% 场景）#

按顺序学这五篇，每学一篇立刻在编辑器里写一遍、看渲染效果：

1. 020-HeadingSyntax（标题）
2. 030-ParagraphLineBreak（段落与换行）
3. 040-BasicTextFormat（加粗/斜体等基础格式）
4. 060-ListSyntax（列表）
5. 050-LinkImage（链接与图片）

第一课就该有即时正反馈：输入 # 你好，看到标题变大——比读 十页规范有用得多。

Layer 1 进阶层（第二周，排版优化）#

• 100-Table（表格）
• 090-CodeBlockSyntaxHighlight（代码块与语法高亮）
• 070-BlockquoteNestedList（引用与嵌套列表）

Layer 2 专业层（按需查阅，不急着学）#

• 240-CommonMarkSpec（CommonMark 规范：解析器原理，高级话题， 零基础可完全跳过）
• 210-LaTeXMathFormula、220-Mermaid（数学公式、图表）
• 260-FrontmatterYAML、270-SpecDocumentWriting、 310-DocsSiteAndAutomation（工程化写作）
• 其余速查类文档（脚注、删除线、自动链接、任务列表、锚点、转义等）： 用到再查，每篇都独立成篇

三条学习原则#

1. 边学边写：每个语法学完立刻手打一遍，不要只看示例；
2. 先看效果再看原理：先输入符号看渲染，再理解它为什么这样设计；
3. 空白即语法：遇到「看起来对但没生效」，先检查不可见字符。

5. 坑点与自检#

新手高频问题，按「现象 → 原因 → 解法」排列，都是真实踩过的：

自检动作：写完文档，用「无预览裸读」检查一遍——真正的 Markdown 源文件即使不渲染也应当结构清晰可读；再开预览核对一遍结构。

6. 动手实践#

任务：给一个你正在做（或想做）的项目写 20 行左右的 README， 只允许用第 2 节的 8 个符号，必须包含：项目名（H1）、一句话简介、 三个安装步骤（有序列表）、一张依赖表（表格）、一个常见问题 （加粗 + 引用）。

提示：先在纸上列骨架再动笔；表格至少两列（名称、用途）； 常见问题的「现象」加粗、「解法」放进引用块，视觉上自然分成两段。 写完用第 5 节的自检动作过一遍。

遮代码自检——先自己写完再看参考：

# todo-cli

一个命令行待办事项管理器，数据存本地 JSON 文件。

## 安装

1. 克隆仓库：`git clone https://github.com/example/todo-cli.git`
2. 安装依赖：`npm install`
3. 全局链接：`npm link`

## 常用命令

| 命令            | 用途           |
| :-------------- | :------------- |
| todo add "事项" | 新增一条待办   |
| todo list       | 列出全部待办   |
| todo done 2     | 完成第 2 条    |

## 常见问题

**添加中文事项后显示乱码？**

> 检查终端编码是否为 UTF-8。Windows 下可在设置中把默认代码页改为
> 65001，或使用 Windows Terminal。

附加练习：

1. 打开本仓库 cnt-content/full/002-markdown/010-SyntaxGuide.md 的源文件，对照你正在读的渲染版，找出三处「源码写法与渲染效果」 的对应关系（比如本文的表格和引用块分别是怎么写的）。
2. 故意制造三个第 5 节表里的坑（去掉空格、去掉空行、错误缩进）， 观察渲染结果，再把它们修好——修复过程就是最好的记忆。

7. 下一步#

• 按第 4 节 Layer 0 顺序进入 020-HeadingSyntax；
• 编辑器怎么选、怎么配：280-EditorFeature；
• 要转 PDF/EPUB 或建文档站：290-ConversionTool；
• 团队写作想统一风格、自动格式化：300-LintFormatTooling；
• 想知道解析器为什么这样解析：240-CommonMarkSpec（专业层，不急）。