Markdown 语法
写 README、提交说明和内部文档够用的那一部分。重点放在渲染器之间行为不一致的地方——语法本身十分钟就能学完，出问题基本都出在空行和缩进上。
标题
# 一级标题
## 二级标题
### 三级标题
# 后面要有空格。一篇文章只用一个一级标题（通常就是文件名对应的大标题），层级不要跳着用——很多渲染器会根据标题生成目录，跳级会让目录结构错乱。
另一种写法是在文字下面画等号或减号，只支持两级，现在很少有人用，遇到旧文档认识即可：
一级标题
========
二级标题
--------
段落与换行
连续的文字属于同一个段落，空一行才分段。这一点和很多人从聊天软件带来的直觉不同：在源码里敲一次回车，渲染出来仍是一行。
要在段落内部强制换行，行尾加两个空格，或者行尾加一个反斜杠（后者在 CommonMark 里有效，部分老渲染器不认）。
第一行末尾两个空格··
第二行
第一行末尾反斜杠\
第二行
行尾空格在保存时很容易被编辑器或 Git 钩子自动删掉，导致换行莫名消失。需要强制换行时，用反斜杠或直接空一行分段，比两个空格可靠。
强调
*斜体* 或 _斜体_
**粗体** 或 __粗体__
***粗斜体***
~~删除线~~（GFM 扩展，不是所有渲染器都支持）
星号更安全：下划线形式在变量名、文件名里很常见，my_file_name 这种文本容易被误判成斜体，所以编程文档里统一用星号。
列表
- 无序项
- 另一项
- 缩进两个空格成为子项
- 子项的第二行
1. 有序项
2. 第二项
子项缩进 2 到 4 个空格都可以，但要全文一致。混用会让某些渲染器把子项当成新的顶层列表。
列表项里放多段文字或代码块，需要继续缩进（通常是 4 个空格），并且前面留空行：
1. 第一步
这一段的缩进让它留在列表项里面。
```bash
make build
```
2. 第二步
任务列表
- [x] 已完成
- [ ] 未完成
这是 GitHub 风格的扩展，纯 CommonMark 渲染器会把它显示成普通的 [x] 文本。在 issue、PR 描述里很好用。
代码
行内代码用反引号包住，反引号内的 Markdown 语法不生效：
执行 `npm run build`，产物在 `dist/` 下。
要显示的内容本身含有反引号时，用两个反引号包住它，并在内层两侧各留一个空格：
`` 含有 ` 反引号的内容 ``
多行代码用三个反引号围起来，开头那行可以标语言，几乎所有渲染器都会据此做语法高亮：
```python
def greet(name: str) -> str:
return f"hello, {name}"
```
语言标记写错不会报错，只是没有高亮。常用的有 bash、python、js、json、yaml、sql、diff。写 diff 时开头加 + / - 就能得到红绿标色，很适合贴配置改动。
链接与图片
[行内链接](https://example.com/docs)
[带标题的链接](https://example.com/docs "文档首页")
[引用式链接][ref]
[ref]: https://example.com/docs
引用式写法适合同一个地址在文中出现多次，改的时候只改一处。图片语法就是链接前面多一个感叹号。
仓库内的文档互相引用，用相对路径而不是绝对地址，这样换仓库地址、换分支预览都不会断：
[部署说明](../deploy/README.md)
尖括号可以直接写网址，渲染成链接：<https://example.com>。但邮箱别这么写，除非你希望它被自动收集。
表格
| 参数 | 类型 | 说明 |
|---|---|---|
| `timeout` | int | 超时秒数 |
| `retries` | int | 重试次数 |
第二行的短横线数量无所谓，但每一列都要有。用冒号控制对齐：
| 左对齐 | 居中 | 右对齐 |
|:---|:---:|---:|
| a | b | c |
表格单元格里要写竖线本身，得转义成 \|；写代码时把整个 `a|b` 包在反引号里在部分渲染器上仍会断列，最稳的办法还是转义。表格里不能放多段文字和列表，需要复杂内容就改成小标题加正文。
引用块
> 一级引用
>
> > 嵌套引用
>
> - 引用里也可以放列表
引用块常被拿来当提示框用。GitHub 的 alert 语法在部分平台上会渲染成带颜色的块，其他地方只是普通引用：
> [!NOTE]
> 这是一条提示。
分隔线与转义
三个以上的 -、* 或 _ 单独一行就是分隔线。注意紧跟在文字下面的 --- 会被当成二级标题的下划线，前面留一个空行就不会歧义。
要显示 Markdown 元字符本身，用反斜杠转义。可转义的字符：\ ` * _ { } [ ] ( ) # + - . ! | >。
常见坑
1. 列表前面没留空行
下面是步骤：
- 第一步
- 第二步
很多渲染器（尤其是严格的 CommonMark 实现）会把这段当成一个段落，- 第一步 原样显示。养成"列表前后各留一个空行"的习惯。
2. 中文全角标点后面接语法
**注意：**这一行 渲染正常，但 **注意：**这一行 后面紧跟中文时，某些解析器（尤其是强调符号紧贴汉字的情况）可能不识别。稳妥写法是在标记外侧留空格，或把标点也放进标记内。
3. 标题里的井号
# 问题 #1 的末尾 #1 在部分实现里会被当成"闭合标记"吃掉。用 # 问题 \#1，或者干脆不写编号。
4. HTML 与 Markdown 混排
大多数渲染器允许直接写 HTML，但块级 HTML 内部默认不再解析 Markdown：
<div>
**这里不会变粗**
</div>
需要在 HTML 块里用 Markdown 时，很多实现要求空行分隔，或者加 markdown="1" 属性（并非通用）。所以能不用 HTML 就不用。
5. 自动链接把邮箱暴露了
直接写 name@example.com 在部分平台上会自动变成可点击的邮件链接，然后被爬虫收走。公开文档里改成图片或写"name at example.com"。
6. 相对链接在渲染器里失效
./docs/setup.md 在 GitHub 上能点，在某些静态站点生成器里会被改写成 .html，在另一些里则原样输出导致 404。跨平台发布的文档，链接目标最好用渲染器文档里明确支持的形式。
一份 README 的骨架
# 项目名
一句话说明这个项目解决什么问题。
## 安装
```bash
pip install example
```
## 快速开始
```python
from example import Client
client = Client(token="...")
print(client.ping())
```
## 配置
| 变量 | 默认值 | 说明 |
|---|---|---|
| `EXAMPLE_HOST` | `127.0.0.1` | 服务地址 |
| `EXAMPLE_TIMEOUT` | `30` | 超时秒数 |
## 常见问题
见 [docs/faq.md](docs/faq.md)。
## 许可证
MIT
骨架里没有"贡献指南"和"行为准则"，小项目不需要。README 的目标是让人在三十秒内知道这是什么、怎么跑起来；超出这个范围的内容放到 docs/ 下。