Markdown 语法速查
这页更适合当“写作速查表”使用：需要时快速复制一段语法，再回到正文继续写。真正要提升写作效率，重点不是记住全部语法，而是养成稳定的文档结构习惯。
最常用的几类语法
- 标题
- 列表
- 链接 / 图片
- 代码块
- 表格
- 引用与提示块
如果你经常写技术文档，只把上面这几类用熟，已经能覆盖大多数场景。
标题
# 一级标题
## 二级标题
### 三级标题
#### 四级标题文本格式
**粗体**
_斜体_
~~删除线~~
`行内代码`
> 引用建议保持层级清晰：不要为了视觉效果跳级使用标题，也不要把粗体当成“伪标题”长期替代正式结构。
链接与图片
[链接文字](https://example.com)
[带标题的链接](https://example.com "标题")
写长期文档时，链接文字尽量写清目标，不要大量使用“点这里”“链接如下”。
列表
- 无序列表
- 第二项
- 嵌套
1. 有序列表
2. 第二项
- [x] 任务列表（已完成）
- [ ] 未完成任务列表很适合做检查清单、发布清单、排障步骤和待办事项。
代码块
```javascript
const hello = "world";npm install
代码块最好标注语言，这样在大多数编辑器和站点里都能获得更好的高亮效果。
## 表格
```markdown
| 左对齐 | 居中 | 右对齐 |
| :----- | :--: | -----: |
| 内容 | 内容 | 内容 |表格适合做对比、清单和参数摘要；如果内容太长，反而不如拆成列表更易读。
分隔线
---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[结束]
## 常见坑
- 标题层级混乱，导致目录不好用
- 列表和代码块缩进不一致，渲染结果和预期不同
- 图片使用本地绝对路径，换设备后失效
- 表格里塞入过长段落，移动端阅读体验很差
- 不区分“速查文档”和“完整教程”，导致文档结构发散
## 常用编辑器
| 工具 | 说明 |
| ------------------------------------------------ | -------------------------- |
| [Typora](https://typora.io/) | 所见即所得 Markdown 编辑器 |
| VS Code | 内置 Markdown 预览 |
| [StackEdit](https://stackedit.io/) | 在线编辑器 |
| [Marktext](https://github.com/marktext/marktext) | 开源编辑器 |
## 写文档时的建议
- 先写目录结构，再填正文，比边写边想更稳
- 一篇文档尽量回答一个核心问题，不要把过多主题揉在一起
- 命令、路径、变量名统一用代码样式包起来
- 能互链的文档尽量互链，减少孤立页面
如果你是在维护本仓库内容，除了语法本身，也建议同时检查 frontmatter、站内链接和页面定位是否清晰。
## 参考链接
- [GitHub Markdown 文档](https://docs.github.com/en/get-started/writing-on-github) — GFM 语法
- [CommonMark 规范](https://commonmark.org/) — 标准规范