本文是一份系统、准确、可直接落地的 Markdown 使用指南。内容覆盖 CommonMark 标准语法 与 GFM（GitHub Flavored Markdown）常用扩展，并对易错点、编辑器差异、最佳实践做明确说明。文中所有语法示例均以「可复制即用」为原则编写。
这一部分属于 Markdown 核心规范，Typora、VS Code、Obsidian、GitHub、GitLab 等几乎所有编辑器都支持。
用 # 表示标题，1 个 # 为一级标题，最多 6 个 #。
# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ##### 五级标题 ###### 六级标题
要点：
# 与文字之间必须有一个空格（#标题 在很多解析器中不生效，兼容性差）。
一级标题建议全文档只用一个，作为文档总标题。
标题会自动生成锚点（用于页内跳转，见扩展语法第 9 节）。
替代写法（Setext 风格，仅支持 1~2 级）：
一级标题 ======== 二级标题 --------
建议：日常统一用 # 写法，Setext 风格了解即可。
Markdown 中段落由空行分隔；单个换行（回车）默认不产生新段落，会被合并成同一段。
这是第一段文本。 这是第二段文本（空一行分隔）。 这是同一段内的软换行， 会被合并为一行显示。
如何在段内强制换行？ 有三种方式：
方式一：行尾加两个空格再回车 这一行会换行（注意上一行末尾有两个空格） 方式二：行尾加反斜杠再回车\ 这一行会换行 方式三：使用 HTML 标签<br> 这一行会换行
要点：
方式一（行尾两个空格）是标准做法，但空格肉眼不可见，容易丢，协作时推荐方式二（\）或方式三（<br>）。
段落之间不要用多个空行堆叠，统一用一个空行分隔即可。
*斜体* 或 _斜体_ **加粗** 或 __加粗__ ***粗斜体*** 或 ___粗斜体___ ~~删除线~~（GFM 扩展）
要点：
斜体有两种写法：*文本* 和 _文本_。推荐用 *，因为下划线 _ 在英文单词、变量名中容易误触发。
加粗同理，推荐 **。
删除线 ~~文本~~ 属于 GFM 扩展，主流编辑器均支持。
下划线（<u>文本</u>）和高亮（<mark>文本</mark>）依赖 HTML，并非所有渲染环境支持，详见第二部分第 10 节。
用 > 表示引用，可嵌套、可多行。
> 这是单行引用 > 这是多行引用第一行 > 这是多行引用第二行 > 一级引用 >> 二级引用（嵌套）
引用内可以嵌套其他语法：
> **加粗引用**
>
> - 引用里的列表项
> - 第二项
>
> ```python
> print("引用里的代码块")
> ```要点：
引用块内要分段或放列表/代码块时，空行也要带上 >（否则可能提前结束引用）。
引用可以无限嵌套，但超过 2 层可读性差，慎用。
用 -、*、+ 均可，推荐统一用 -。
- 列表项 1 - 列表项 2 - 子项 2.1（缩进 2 个或 4 个空格） - 子项 2.2 - 列表项 3
用「数字 + .」表示。
1. 第一项 2. 第二项 1. 子项 2.1 2. 子项 2.2 3. 第三项
要点：
起始数字可以是任意值（如 3. 开头），渲染时会按顺序自动编号；但建议从 1 开始，语义清晰。
子列表的缩进：无序列表常用 2 空格，有序列表常用 3 空格（与父级标记宽度对齐），同一文档保持一致即可。
列表项之间不要空行（否则会变成「松散列表」，项间距变大）；需要松散列表时才有意空行。
- [ ] 未完成任务 - [x] 已完成任务
要点：
方括号内留一个空格表示未完成，填 x 或 X 表示已完成。
GitHub、Typora、Obsidian 等支持勾选交互；纯文本环境仅作展示。
用反引号包裹：
使用 `printf()` 函数实现输出。
要点： 如果内容本身含反引号，可用双反引号包裹：
``代码里有 ` 反引号``
用三个反引号包裹，并在开头注明语言以启用语法高亮：
```python
print("Hello Markdown")
for i in range(5):
print(i)
```支持的语言名示例： python、javascript、java、sql、bash、html、css、json、markdown、php、c、cpp、go、rust 等。
要点：
语言名必须写对，写错或留空则无高亮（但仍会按代码块渲染）。
代码块内部内容原样保留，不会被 Markdown 解析，因此可安全放置 #、* 等符号。
需要展示「包含三个反引号的代码块」时，外层用四个反引号包裹。
[显示文本](https://example.com) [显示文本](https://example.com "鼠标悬停显示的标题")
[Markdown 官网][md] [另一个链接][md] [md]: https://daringfireball.net/projects/markdown/ "Markdown Official Site"
要点：
参考式定义 [标识]: 地址 可放在文档任意位置（通常放文末），不会显示在正文。
标识不区分大小写。
<https://daringfireball.net/projects/markdown/> <example@163.com>
要点：
尖括号内是 URL 或邮箱时，自动变成可点击链接。
GFM 环境下，裸 URL（不加尖括号）通常也会被自动识别，但为保证兼容性，建议显式加尖括号。
语法与链接类似，前面加 !：
本地图片（按路径类型）：
 <!-- 相对路径：与 .md 同目录 -->  <!-- 相对路径：子目录 -->  <!-- 绝对路径：Mac/Linux -->  <!-- 绝对路径：Windows -->
要点：
强烈推荐使用相对路径，便于 .md 文件与图片一起迁移、上传到仓库。
Windows 绝对路径在 Markdown 中建议用正斜杠 / 或转义反斜杠，直接写 D:\files\doc.jpg 在部分渲染器会出错。
图片描述（alt 文本）不要省略，利于无障碍访问和图片加载失败时提示。
用三个及以上的 -、* 或 _ 单独成行：
---
要点：
前后各留一个空行，否则可能与上方文字组成「标题」（Setext 风格）或被误解析。
三种符号效果相同，推荐统一用 ---。
注意 --- 紧跟在文字下方时会被解析为「二级标题」，因此必须空行分隔。
当需要原样显示 Markdown 特殊符号时，在符号前加反斜杠 \：
\# 显示 #（不被识别为标题） \* 显示 *（不被识别为斜体） \_ 显示 _（不被识别为斜体） \[ 显示 [（不被识别为链接） \` 显示 `（不被识别为代码） \- 显示 -（不被识别为列表）
CommonMark 支持转义的符号集合：
\ ` * _ { } [ ] ( ) # + - . ! | >要点：
反斜杠本身要显示时，写 \\。
代码块内的内容无需转义（原样输出）。
表格中的竖线 | 是列分隔符，若要在单元格内显示 |，需写成 \|。
这一部分并非所有编辑器都支持，使用前请确认目标平台（GitHub / GitLab / Typora / Obsidian / VS Code 等通常支持大部分）。
基础语法：
| 左对齐 | 居中对齐 | 右对齐 | | :----- | :------: | -----: | | 内容1 | 内容2 | 内容3 | | 内容4 | 内容5 | 内容6 |
对齐控制： 第二行（分隔行）中用冒号位置决定对齐方式：
| 写法 | 效果 |
|---|---|
| :--- | 左对齐（默认） |
| :---: | 居中对齐 |
| ---: | 右对齐 |
| --- | 左对齐（等价） |
要点：
第二行（分隔行）必须有，是表格的判定标志；--- 的数量不限，但至少 3 个更稳妥。
首尾的 | 可省略，但保留可读性更好，也减少歧义。
单元格内容不能直接换行；需要换行可用 <br>。
单元格内要显示 |，写成 \|。
表格内可嵌套行内代码、链接、加粗等，但不能直接嵌套多行代码块或列表。
已在基础第 5 节介绍，此处强调交互场景：
- [ ] 待办事项 A - [x] 已完成事项 B - [ ] 待办事项 C
要点： GitHub Issue / PR 模板、Obsidian、Typora 中可点击勾选；纯文本渲染器仅显示符号。
~~被删除的内容~~
要点： 属于 GFM 扩展，绝大多数主流编辑器支持；极少数严格 CommonMark 渲染器不支持。
Markdown 由 John Gruber 创建[^1]。 [^1]: John Gruber 是 Markdown 语法的发明者，于 2004 年推出该语法。
要点：
正文中 [^标识] 是引用，文末 [^标识]: 说明 是定义。
标识可以是数字或英文单词，不区分大小写。
脚注定义可放在文末，渲染时自动汇总到文档末尾。
支持情况：Typora、Obsidian、GitHub 支持；部分简易渲染器不支持。
自动生成（依赖编辑器）：
[TOC]
要点：
Typora、Obsidian 等支持 [TOC] 自动根据标题生成目录。
GitHub 不识别 [TOC]，GitHub 自带页面右侧/顶部的目录导航。
在不支持 [TOC] 的环境，可手写锚点跳转实现目录（见第 9 节）。
行内公式用单美元符号包裹：
质能方程为 $E = mc^2$，其中 E 为能量。
块级公式用双美元符号包裹：
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$要点：
数学公式依赖 MathJax / KaTeX 渲染，Typora、Obsidian、GitHub（部分）、Jupyter 支持；普通 Markdown 预览器可能显示原始 LaTeX。
若当前环境不支持，可用行内代码或代码块包裹 LaTeX 源码，至少保证可读。
常用符号：\frac{a}{b}（分数）、\sqrt{x}（根号）、\sum（求和）、\int（积分）、\alpha \beta \gamma（希腊字母）。
Mermaid 是一种用文本描述图表的语法，代码块语言标记为 mermaid 即可。
流程图示例：
```mermaid
graph TD
A[开始] --> B[执行操作]
B --> C{判断条件}
C -->|是| D[结果1]
C -->|否| E[结果2]
D --> F[结束]
E --> F
```时序图示例：
```mermaid sequenceDiagram participant 客户端 participant 服务器 客户端->>服务器: 发送请求 服务器-->>客户端: 响应数据 ```
要点：
graph TD：从上到下；graph LR：从左到右。
节点形状：[] 矩形、() 圆角、{} 菱形（判断）、(()) 圆形。
箭头：--> 实线箭头、-->> 虚线箭头、--- 实线无箭头。
支持情况：GitHub、GitLab、Typora（需开启）、Obsidian（需插件）等；不支持时仅显示源码。
推荐：HTML 注释（兼容性最好）
<!-- 这是一段注释，不会显示在渲染结果中 --> 这是正文内容。
部分编辑器支持： 某些编辑器接受 [//]: # (注释内容) 作为 Markdown 注释，但兼容性差，不建议依赖。
要点：
注释在渲染结果中不可见，但仍存在于源文件中（注意：发布公开文档时，注释内容仍可能被看到）。
若需彻底隐藏，请直接删除内容。
跳转语法：
[跳转文本](#标题标识)
标题标识的生成规则（GitHub / 多数编辑器）：
标题文字转小写；
去掉标点符号、特殊字符；
空格替换为 -；
中文标题直接保留（不同平台处理略有差异）。
示例：
[跳转到表格语法](#1-表格) ... ## 1. 表格
要点：
锚点标识因编辑器而异，同一标题在 GitHub 与 Typora 生成的标识可能不同，跨平台文档需实测。
若标题含中文或特殊符号，跳转可能失效，建议用英文/数字标题或手动指定 HTML 锚点：
<a id="custom-anchor"></a> ## 某个标题 [跳转](#custom-anchor)
Markdown 支持内嵌 HTML，用于实现标准语法之外的效果。
<u>下划线</u> <mark>高亮</mark> <strong>加粗（等价 **）</strong> <br> <sup>上标</sup> <sub>下标</sub>
要点：
内嵌 HTML 兼容性因平台而异：Typora、Obsidian、GitHub 支持大部分简单标签；某些严格 Markdown 渲染器（如部分博客平台）会过滤 HTML。
块级 HTML 与 Markdown 混用时，HTML 块内不要缩进，且前后留空行，避免解析异常。
安全提示：在允许用户提交内容的平台（论坛、评论），HTML 可能被禁用或被清理，避免依赖 HTML 实现关键排版。
| 需求 | 语法 |
|---|---|
| 标题（1~6 级） | # ~ ######，# 后加空格 |
| 加粗 | **文本** |
| 斜体 | *文本* |
| 粗斜体 | ***文本*** |
| 删除线 | ~~文本~~ |
| 下划线 | <u>文本</u> |
| 高亮 | <mark>文本</mark> |
| 无序列表 | - 项 |
| 有序列表 | 1. 项 |
| 子列表 | 缩进 2~4 空格 |
| 任务列表 | - [ ] 未完成 / - [x] 已完成 |
| 引用 | > 文本 |
| 嵌套引用 | >> 文本 |
| 行内代码 | `代码` |
| 代码块 | ```lang + 代码 + ``` |
| 行内链接 | [文本](URL "标题") |
| 参考式链接 | [文本][id] + [id]: URL |
| 自动链接 | <https://...> |
| 图片 |  |
| 表格 | | 列 | 列 |，第二行 :--- 控制对齐 |
| 水平线 | ---（前后空行） |
| 脚注 | [^1] + [^1]: 说明 |
| 目录 | [TOC]（部分编辑器） |
| 行内公式 | $公式$ |
| 块级公式 | $$公式$$ |
| Mermaid 图 | ```mermaid 代码块 |
| 注释 | <!-- 注释 --> |
| 转义 | 特殊符号前加 \ |
| 强制换行 | 行尾两空格 / \ / <br> |
不确定目标平台是否支持时，优先使用基础语法（第一部分），扩展语法作为增强。
发布前在目标平台实际预览，尤其是表格、公式、Mermaid、HTML 标签。
一律使用相对路径，方便 .md 与图片整体迁移。
图片描述（alt）务必填写，利于无障碍与加载失败提示。
Windows 路径用 / 或 \\，避免直接写单个 \。
语言名写正确（python、javascript、sql、bash、json 等），否则无高亮。
需要展示含三个反引号的内容时，外层用四个反引号。
# 后、> 后、列表标记后都要有空格。
段落之间用一个空行分隔；水平线 --- 与表格分隔行前后必须空行，避免误解析。
行尾两个空格做换行容易丢失，协作场景用 \ 或 <br> 更稳妥。
同一文档中，列表子级缩进保持统一（建议无序 2 空格、有序 3 空格）。
列表项之间不要随意空行，否则会变成「松散列表」。
第二行分隔行不可省略。
单元格内换行用 <br>，显示竖线用 \|。
表格内避免嵌套复杂块（多行代码、列表）。
中文标题的自动锚点跨平台不一致，跨平台文档建议用英文/数字标题或自定义 HTML 锚点。
GitHub 不识别 [TOC]，需用其自带目录或手写锚点。
公式/图表依赖渲染引擎，不在所有环境生效；对兼容性要求高的文档，可同时给出源码与截图。
Mermaid 语法版本较多，复杂图建议在目标平台先验证。
仅在必要时用 HTML（下划线、高亮、复杂排版）。
注意平台可能过滤 HTML，不要用 HTML 承载关键内容。
HTML 块内不要缩进，前后留空行。
适当对齐表格的 |，源文件更易维护。
参考式链接定义集中放在文末，正文更干净。
注释虽不渲染，但仍存在于源文件，公开前确认无敏感信息。
不要直接渲染不可信来源的 Markdown（可能含恶意 HTML/脚本），平台应做过滤。
在允许用户输入的系统中，HTML 与链接协议（如 javascript:）应被白名单限制。
登录后参与评论
论坛评论仅限会员，登录后即可发表评论与回复