一、六个核心语法
# 一级标题
## 二级标题
### 三级标题
普通段落，**加粗**，*斜体*，`行内代码`。
- 无序列表
- 第二项
- 嵌套项（缩进两个空格）
1. 有序列表
2. 第二项
[链接文字](https://example.com)
> 引用块，常用于备注。标题的 # 后面必须有空格，#标题 不会生效。
代码块用三个反引号包起来，紧跟语言名用于高亮：
```python
print("hi")
```当内容本身包含三个反引号时，外层要用四个反引号，否则会被提前闭合。
二、表格
| 名称 | 说明 |
|---|---|
| id | 主键 |
| name | 用户名 |第二行的 ---|--- 是分隔行，必须有。列宽不用对齐，渲染时会自动调整。单元格里想写竖线要用 \| 转义。
三、五个常见坑
1. 列表前没有空行
正文内容
- 列表项很多解析器会把它们当成同一段。列表、代码块、表格前都留一个空行，最稳妥。
2. 缩进用了 Tab 或四个空格
四个空格会被当成「代码块」，导致列表项变成代码。嵌套列表统一用 2 个空格或 3 个（不同实现有差异），保持一致即可。
3. 段落内换行不生效
Markdown 里单个换行会被合并成一个空格，这是设计如此。要强制换行：
- 行尾加两个空格（不可见，容易丢）。
- 或加
<br>。 - 或空一行变成新段落（推荐）。
4. 特殊字符被当成语法
* _ # [ ] 出现在正文里可能触发格式。用反斜杠转义：\*、\_。
5. 代码块里的反引号冲突
嵌套代码块要用更多反引号包裹：
```markdown
内部代码
```四、GFM 扩展
GitHub 风格（多数平台支持）：
- [x] 已完成的任务
- [ ] 未完成
~~删除线~~
https://自动识别为链接.com还有自动链接、脚注（部分平台）、数学公式（$...$，需 KaTeX 支持）。
五、图片与链接的选择
- 图片用相对路径，便于仓库迁移；外链图片可能被防盗链。
- 图片要有
alt文本，对无障碍和 SEO 都有用。 - 链接文字要描述内容（「JSON 格式化工具」而不是「点这里」）。
六、Markdown 不适合做什么
- 精确排版：字号、行距、页边距都控制不了。要精排就用 HTML/CSS 或 Word。
- 复杂表格：合并单元格、嵌套表格不支持。
- 多栏布局：需要 HTML。
- 页码、目录：依赖具体渲染器（有些支持
[TOC]）。
它擅长的是「内容结构清晰、轻量、可版本管理」，这也是文档场景最需要的。
七、写完检查什么
- 标题层级是否连续（不要从
#直接跳到###）。 - 列表、代码块前后有没有空行。
- 链接是否能打开、图片是否显示。
- 代码块有没有标语言（影响高亮）。
- 渲染后与预期是否一致——不同平台渲染结果可能不同，发布前在目标平台预览一次。
本地预览用 Markdown 预览工具，左边写右边看，避免反复提交才发现格式乱。需要把 Markdown 里的特殊字符转义时，用 HTML 实体编解码。
小结
# 后要空格；列表/代码/表格前留空行；嵌套缩进用 2 空格；段内换行要空行分段；特殊字符用 \ 转义；发布前在目标平台预览。