本文是一份面向实际写作和系统落地的 Markdown 指南。重点不是“语法列表”，而是讲清楚如何用 Markdown 写出结构清晰、可维护、可转换、可发布的文档
适用场景
- 写技术文档、安装指南、运维手册
- 写 README、变更记录、公告、方案说明
- 统一团队文档风格
- 将 Markdown 转换为 HTML 页面
- 在站点后台或内容系统里保存结构化正文
Markdown 是什么
Markdown 是一种轻量级标记语言。它的目标很简单：
- 用尽量少的符号表达结构
- 让纯文本易读
- 让内容方便转换成 HTML
- 让文档既适合编辑，也适合渲染
它特别适合“内容为主、结构清晰”的文本，比如教程、说明文、知识库、博客正文。
Markdown 的核心原则
1. 先结构，后样式
Markdown 最重要的是表达内容结构，而不是追求花哨效果。
2. 少量语法，稳定输出
不要滥用复杂嵌套、深层表格、过多 HTML 混写，否则后期维护成本会很高。
3. 保持可读性
即使不渲染，源文件本身也应该能清楚表达意思。
4. 能转 HTML，且转换后语义正确
如果文档最终要展示到网页，就要关注：
- 标题层级是否合理
- 列表是否规范
- 代码块是否保留语言标识
- 链接、图片、表格是否可被正确渲染
基本文档骨架
一篇实用的 Markdown 文档通常包含以下部分：
# 标题
简短说明这份文档的用途。
## 适用场景
## 核心概念
## 安装或准备
## 使用方法
## 常见问题
## 最佳实践
## 总结这种结构适合大多数教程型文档。
标题
标题使用 # 表示层级。
# 一级标题
## 二级标题
### 三级标题
#### 四级标题规则
- 一个文档通常只保留一个一级标题
- 标题层级要连续，不要跳级太多
- 标题要直接说明内容，不要空泛
不推荐
# 文档
### 第二部分推荐
# Markdown 使用指南
## 基础语法
## 实战模板
## 常见问题段落与换行
Markdown 中普通空行表示段落分隔。
这是第一段。
这是第二段。如果想在同一段里强制换行，可以在行尾保留两个空格，或者按渲染器规则使用 <br>，但通常不建议过度依赖。
强调
常见强调方式：
**加粗**
*斜体*建议：
- 用加粗突出关键术语、结论或注意事项
- 不要整页都加粗，否则重点会失效
列表
无序列表
- 项目一
- 项目二
- 项目三有序列表
1. 第一步
2. 第二步
3. 第三步适用建议
- 无序列表适合并列项
- 有序列表适合步骤、流程、顺序
- 同一列表尽量保持同一层级，不要混乱嵌套
链接
Markdown 链接格式：
[显示文本](https://example.com)建议
- 链接文本尽量有信息量
- 不要大量使用“点击这里”
- 内链可以直接写相对路径
示例：
[Nginx 安装指南](./nginx.md)图片
Markdown 图片格式：
图片写作建议
- alt 要能描述图片内容
- 图片文件名尽量语义化
- 如果图片是装饰用途，仍然尽量保持描述清晰
常见问题
- 图片路径写错
- 图片过大导致加载慢
- 没有替代文本，影响可访问性
代码
行内代码
行内代码使用反引号：
使用 `docker ps` 查看容器。代码块
使用三个反引号包裹代码：
```bash
apt update
apt install nginx
### 建议
- 尽量标注语言类型，如 `bash`、`json`、`go`、`sql`
- 代码块保持最小可执行示例
- 不要把太长的代码硬塞进正文，必要时拆分说明
## 引用
引用用 `>`：
```md
> 先写清楚结构，再考虑美观。适合：
- 注意事项
- 经验结论
- 规范说明
分隔线
---适合分隔章节，但不要频繁使用。
表格
Markdown 表格适合做对比或参数列表。
| 项目 | 说明 |
| --- | --- |
| title | 页面标题 |
| alt | 图片替代文本 |使用建议
- 表格适合短内容
- 单元格内容过长时，阅读体验会变差
- 如果数据量大，优先考虑列表或分段说明
任务列表
- [x] 安装完成
- [ ] 配置完成
- [ ] 验证完成适合：
- 发布检查
- 运维排障清单
- 文档写作进度
原始 HTML
Markdown 允许嵌入部分 HTML，但应谨慎使用。
适合使用的场景
- Markdown 本身表达不了的细节
- 需要特定容器或样式钩子
- 表格或布局有特殊需求
不建议
- 大段 HTML 替代 Markdown
- 把正文写成 HTML，Markdown 只当壳
- 过度依赖前端样式来表达内容结构
如果文档最终要长期维护，优先使用 Markdown 原生语法。
Markdown 写作规范
标题规范
- 标题要短
- 标题要明确
- 标题要与内容一致
列表规范
- 列表项尽量语义平行
- 同层级内容统一格式
- 不要在简单条目里写太长的句子
代码规范
- 给命令加语言标签
- 输出示例和输入示例要分开
- 配置片段尽量完整
链接规范
- 内链优先
- 外链要明确目标
- 避免无意义链接文本
图片规范
- 图片要有意义
- 图片路径要稳定
- 复杂流程图优先用可维护格式生成
实践建议
- 如果内容来源不确定，先判断是否像 Markdown，再决定是否转换
- 转 HTML 后要关注标题、列表、表格、代码块是否保持语义
- 作为内容系统的输入时，要统一约定 Markdown 规范，避免不同来源风格混乱
Markdown 到 HTML 的常见注意点
1. 标题层级映射
# 会变成 HTML 的 h1，## 会变成 h2，以此类推。
2. 列表嵌套
缩进不规范会导致列表层级错乱。
3. 代码块高亮
Markdown 只负责结构，具体高亮通常由前端或渲染器扩展实现。
4. 表格兼容性
有些渲染器对表格支持不同，最好启用 GFM 兼容模式。
5. 安全性
如果 Markdown 来源不可信，转换后的 HTML 不能直接无脑输出到页面，需要做安全处理或过滤策略。
常见错误
错误 1：标题乱跳
# 一级
### 三级问题：结构不连续，阅读和解析都不友好。
错误 2：列表格式混乱
- 项目一
1. 子项
- 子项二问题：混用层级时没有统一规则。
错误 3：代码块没有语言
apt update
问题：渲染器无法更好地做语法提示。
错误 4：用 Markdown 写复杂布局
问题：Markdown 不是排版系统，复杂布局会让文档难以维护。
一个实用模板
# 功能名称
一句话说明这个功能解决什么问题。
## 适用场景
- 场景一
- 场景二
## 前置条件
- 条件一
- 条件二
## 使用步骤
1. 第一步
2. 第二步
3. 第三步
## 示例
```bash
command --option常见问题
问题一
说明与解决办法。
总结
一句话收尾。
这个模板适合大多数技术文档。
## 最佳实践清单
- 优先使用 Markdown 原生语法
- 保持标题层级清晰
- 用列表表达流程
- 用代码块表达命令和配置
- 为图片和链接提供明确语义
- 少用原始 HTML
- 在转 HTML 前先统一文档风格
- 如果是内容系统，提前约定 Markdown 规范
## 总结
Markdown 的价值在于“轻结构、强可读、易转换”。
对于技术文档、站点内容和知识库来说，最好的 Markdown 不是语法最复杂的，而是最容易写、最容易读、最容易渲染、最容易维护的。