Markdown 最佳实践速查指南

Markdown 最佳实践速查指南 - 涵盖常见语法、排版规范与协作约定，适合日常文档写作快速参考

Markdown 最佳实践速查指南 v1.0.0

概述

本指南为 Markdown 日常文档写作提供快速参考，涵盖核心语法、排版规范与团队协作约定。 适用于技术文档、README、PRD、知识库等场景。

常用语法速查

标题层级

markdown

# 一级标题（每页唯一）
## 二级标题
### 三级标题

约定：不跳级使用标题（如 H1 后直接 H3）。

强调

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

列表

markdown

- 无序列表项
- 第二项
  - 嵌套项（缩进2空格）
1. 有序列表项
2. 第二项

链接与图片

markdown

[链接文字](https://example.com "可选标题")
![图片描述](image.png "可选标题")

代码块

markdown

```language
code here
```

约定：始终指定语言，便于语法高亮。

表格

markdown

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| A   | B   | C   |

引用

markdown

> 单行引用
>
> 多行引用

排版规范

1. 行尾换行：段落之间空一行，行内不手动换行
2. 标点统一：中英文混排时，中文用中文标点，英文用英文标点
3. 代码标识：术语、API名等用行内代码包裹
4. 链接描述：链接文字应描述目标内容，不用"点击这里"
5. 图片 alt：所有图片必须有 alt 文本

协作约定

• PR/MR 中修改文档时，在描述中注明影响范围
• 长文档建议添加目录（TOC）
• 大段修改前先创建分支或草稿
• 定期 review 过时内容

版本历史

• 1.0.0 (2026-08-28): 初始版本