第 14 章：最佳实践
最后一章，不是新语法，而是让所有语法「用得好」的经验总结。从写作规范到避坑指南，再到终极速查表。
学习目标
- 掌握 Markdown 的写作规范和风格指南
- 识别并避免常见错误
- 拥有可随时查阅的 Markdown 速查表
14.1 写作规范
标题
| 规范 | 示例 |
|---|---|
# 后加空格 | ✅ # 标题 ❌ #标题 |
| 一个文件只有一个 h1 | ✅ 用 # 做文章标题 |
| 标题层级不跳级 | ✅ h2 → h3 ❌ h2 → h4 |
| 标题文字简洁有力 | ✅ ## 安装方法 ❌ ## 关于如何安装和配置本项目的详细说明 |
| 不要用标题做强调 | ✅ **重要** ❌ ## 重要！！！ |
段落
| 规范 | 说明 |
|---|---|
| 空行分隔段落 | 一个空行，不要多也不要少 |
| 按句换行 | 每句话一行，git diff 更清晰 |
| 避免超长段落 | 超过 5 行考虑拆分 |
| 段落首行不缩进 | Markdown 渲染会自动处理段落间距 |
列表
| 规范 | 说明 |
|---|---|
统一使用 - | 不要混用 - * + |
| 缩进 4 空格 | 嵌套列表的子项缩进 4 个空格 |
| 列表标记后加空格 | ✅ - 项目 ❌ -项目 |
代码
| 规范 | 说明 |
|---|---|
| 指定语言 | ```python 而非 ``` |
| 代码块前后空行 | 隔离代码和正文 |
| 行内代码不过长 | 超过一行内容应使用代码块 |
链接
| 规范 | 说明 |
|---|---|
| 内部文件用相对路径 | [文档](docs/guide.md) |
| 外部链接写完整 URL | [GitHub](https://github.com) |
| 避免裸链接 | [链接](url) 而非直接写 url |
图片
| 规范 | 说明 |
|---|---|
| 必须写替代文本 | ✅  ❌  |
| 图片放仓库内 | 放在 images/ 目录，不走外部图床 |
| 控制图片大小 | 用 HTML <img width="..."> |
14.2 常见错误与解决方案
错误 1：标题 # 后忘加空格
markdown
❌ #标题 → 不解析为标题
✅ # 标题 → 正确错误 2：列表标记后忘加空格
markdown
❌ -项目 → 不解析为列表
✅ - 项目 → 正确错误 3：分隔线前没有空行
markdown
❌
这是文字
---
这是另一段 → --- 被当作二级标题
✅
这是文字
---
这是另一段 → --- 是分隔线错误 4：代码块未闭合
markdown
❌
```python
print("Hello")
忘记了闭合标记 → 后续内容全变代码
✅
```python
print("Hello")
``` → 正确闭合错误 5：表格分隔行忘记写
markdown
❌
| 姓名 | 年龄 |
| 张三 | 28 | → 缺少分隔行
✅
| 姓名 | 年龄 |
|------|------|
| 张三 | 28 |错误 6：图片使用本地绝对路径
markdown
❌  → 别人看不了
✅  → 相对路径错误 7：混用 Tab 和空格缩进
markdown
❌ 部分缩进用 Tab，部分用空格 → Git diff 混乱
✅ 统一使用 4 个空格 → 整洁一致错误 8：嵌套列表缩进不足
markdown
❌
- 主项
- 子项 → 2 空格，部分平台无效
✅
- 主项
- 子项 → 4 空格，兼容性最好14.3 文件组织规范
project/
├── README.md # 项目总入口
├── docs/ # 文档目录
│ ├── guide/
│ ├── api/
│ └── images/
├── CHANGELOG.md # 版本更新日志
├── CONTRIBUTING.md # 贡献指南
└── LICENSE # 许可证文件命名
| 规范 | 示例 |
|---|---|
| 全小写 | ✅ installation-guide.md ❌ Installation-Guide.md |
| 短横线分隔 | ✅ getting-started.md ❌ getting_started.md |
| 禁止空格 | ✅ api-reference.md ❌ api reference.md |
| 有意义的短名称 | ✅ config.md ❌ document1.md |
14.4 GitHub 特别建议
充分利用 GitHub 特性
- Profile README：创建同名仓库，README 成为你的 GitHub 首页
- Issue 模板：
.github/ISSUE_TEMPLATE/下用 Markdown 定义 Issue 模板 - Pull Request 模板：
.github/PULL_REQUEST_TEMPLATE.md - GitHub Pages：
docs/目录直接发布为文档站 - Mermaid 图表：在 Issue、PR、Discussion 中均可使用
14.5 Markdown 终极速查表
基础语法
| 元素 | 语法 |
|---|---|
| 标题 | # H1 ## H2 ### H3 ... ###### H6 |
| 粗体 | **粗体** |
| 斜体 | *斜体* |
| 粗斜体 | ***粗斜体*** |
| 删除线 | ~~删除~~ |
| 高亮 | ==高亮==（部分平台） |
| 段落 | 空行分隔 |
| 换行 | 行末两空格 |
列表
| 元素 | 语法 |
|---|---|
| 无序列表 | - 项目 |
| 有序列表 | 1. 项目 |
| 任务列表 | - [ ] 待办 |
| 已完成 | - [x] 完成 |
| 嵌套 | 4 空格缩进 |
链接与图片
| 元素 | 语法 |
|---|---|
| 行内链接 | [文字](https://...) |
| 参考链接 | [文字][id] + [id]: url |
| 自动链接 | <https://...> |
| 图片 |  |
| 图片链接 | [](url) |
内容组织
| 元素 | 语法 |
|---|---|
| 引用块 | > 内容 |
| 嵌套引用 | >> 内容 |
| 分隔线 | ---（前后空行） |
| 脚注 | [^1] + [^1]: 内容 |
| 注释 | <!-- 注释 --> |
代码
| 元素 | 语法 |
|---|---|
| 行内代码 | `代码` |
| 代码块 | ```language |
| 语法高亮 | 指定语言标识符 |
表格
| 元素 | 语法 |
|---|---|
| 基本表格 | | A | B | + `|-|- |
| 左对齐 | |:--- |
| 居中 | |:---:| |
| 右对齐 | |---:| |
扩展语法
| 元素 | 语法 |
|---|---|
| 行内公式 | $E=mc^2$ |
| 块级公式 | $$公式$$ |
| Mermaid | ```mermaid 代码块 |
| Emoji | :tada: 或直接输入 🎉 |
HTML 常用
| 需求 | HTML |
|---|---|
| 图片宽度 | <img src="..." width="300"> |
| 图片居中 | <p align="center"><img></p> |
| 下划线 | <u>文字</u> |
| 键盘按键 | <kbd>Ctrl+K</kbd> |
| 折叠面板 | <details><summary>标题</summary>内容</details> |
| 上下标 | <sup>上标</sup> <sub>下标</sub> |
14.6 推荐学习路径回顾
第 1 章（概念）──→ 第 2 章（基础）──→ 第 3-6 章（核心语法）
│
↓
第 7-9 章（进阶语法）
│
↓
第 10-11 章（扩展能力）
│
↓
第 12 章（工具选型）
│
↓
第 13 章（实战场景）──→ 第 14 章（最佳实践）结束语
恭喜你完成了 Markdown 实用教程的全部 14 章！
从最初认识 Markdown 是什么，到如今能够写出结构清晰、格式丰富、图文并茂的文档——你已经掌握了技术写作的核心技能之一。
几点建议：
- 📝 马上用起来：今天的笔记、明天的 README，都用 Markdown 写
- 🔁 回来翻翻：这本教程就在你的仓库里，有需要随时查阅第 14 章速查表
- 🎯 保持简洁：Markdown 的灵魂是「易读易写」，不要过度使用高级语法
- 🚀 持续精进：后面可以深入学习 Pandoc、静态博客框架等进阶工具
Markdown 不是目的，清晰有效的沟通才是。
希望这本教程对你有所帮助。