Markdown 语法速查

这页更适合当“写作速查表”使用：需要时快速复制一段语法，再回到正文继续写。真正要提升写作效率，重点不是记住全部语法，而是养成稳定的文档结构习惯。

最常用的几类语法

• 标题
• 列表
• 链接 / 图片
• 代码块
• 表格
• 引用与提示块

如果你经常写技术文档，只把上面这几类用熟，已经能覆盖大多数场景。

标题

# 一级标题

## 二级标题

### 三级标题

#### 四级标题

文本格式

**粗体**
_斜体_
~~删除线~~
`行内代码`

> 引用

建议保持层级清晰：不要为了视觉效果跳级使用标题，也不要把粗体当成“伪标题”长期替代正式结构。

链接与图片

[链接文字](https://example.com)
[带标题的链接](https://example.com "标题")

![图片描述](image.png)
![](https://example.com/image.png)

写长期文档时，链接文字尽量写清目标，不要大量使用“点这里”“链接如下”。

列表

- 无序列表
- 第二项
  - 嵌套

1. 有序列表
2. 第二项

- [x] 任务列表（已完成）
- [ ] 未完成

任务列表很适合做检查清单、发布清单、排障步骤和待办事项。

代码块

```javascript
const hello = "world";
```

```bash
npm install
```

代码块最好标注语言，这样在大多数编辑器和站点里都能获得更好的高亮效果。

表格

| 左对齐 | 居中 | 右对齐 |
| :----- | :--: | -----: |
| 内容   | 内容 |   内容 |

表格适合做对比、清单和参数摘要；如果内容太长，反而不如拆成列表更易读。

分隔线

---

GitHub Flavored Markdown

自动链接

https://github.com 会自动变成链接

脚注

这是一段文字[^1]。

[^1]: 这是脚注内容。

折叠内容

<details>
<summary>点击展开</summary>

隐藏的内容

</details>

告警提示

> [!NOTE]
> 提示信息

> [!WARNING]
> 警告信息

> [!IMPORTANT]
> 重要信息

Mermaid 图表

```mermaid
graph LR
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
```

常见坑

• 标题层级混乱，导致目录不好用
• 列表和代码块缩进不一致，渲染结果和预期不同
• 图片使用本地绝对路径，换设备后失效
• 表格里塞入过长段落，移动端阅读体验很差
• 不区分“速查文档”和“完整教程”，导致文档结构发散

常用编辑器

写文档时的建议

• 先写目录结构，再填正文，比边写边想更稳
• 一篇文档尽量回答一个核心问题，不要把过多主题揉在一起
• 命令、路径、变量名统一用代码样式包起来
• 能互链的文档尽量互链，减少孤立页面

如果你是在维护本仓库内容，除了语法本身，也建议同时检查 frontmatter、站内链接和页面定位是否清晰。

参考链接

• Markdown 指南 — 完整教程
• GitHub Markdown 文档 — GFM 语法
• CommonMark 规范 — 标准规范
• 站内导航与索引 — 查看整站内容结构