Markdown 写作规范
零基础
这门课的目标不是「把 Markdown 所有语法都背下来」，而是帮你建立一套适合课程作业、开源项目和团队协作的文档习惯。你会发现：写得清楚的人，往往也比别人更容易获得合作机会。
你将学会什么
Section titled “你将学会什么”- 建立清晰、可扫描的文档结构
- 掌握标题、列表、代码块、表格的最小可用写法
- 减少「写了很多，但别人看不懂」的情况
- 掌握 README 的最小结构与提交前检查清单
- 学会让文档「下次还能改得动」的可维护写法
- 会用任意代码编辑器（如 VS Code）写文档
- 写过课程实验报告或任何一份 README 更佳
| 章节 | 内容 |
|---|---|
| 1. 文档结构：标题与列表 | 为什么写作重要、标题层级与列表规范 |
| 2. 代码块与链接引用 | 命令怎么展示、链接怎么写才不误导 |
| 3. 表格、提示框与提交前检查 | 结构化信息、三种提示框与五步检查清单 |
| 4. 从草稿到定稿 | 可维护原则与四步写作流程 |
| 5. README 与协作文档 | README 最小结构与协作边界 |
学习路线建议
Section titled “学习路线建议”- 如果你之前很少写文档，建议按「结构 → 细节 → 检查 → 协作」的顺序学，前三章能覆盖大多数课程场景
- 每章末尾都有 3 道小测验，答错时解析会说明原因
一篇文档里可以出现多个 # 标题吗？
Section titled “一篇文档里可以出现多个 # 标题吗？”可以，但不建议。多个顶级标题会让读者看不出主次，信息层级混乱。更实用的写法是全篇只保留一个 #，其余用 ## 和 ### 组织，让读者扫一眼目录就能说出这篇文档讲了几件事。详见标题层级与列表。
为什么代码块要标明语言类型？
Section titled “为什么代码块要标明语言类型？”标明语言才能正确高亮，读者一眼能看出命令与输出的区别，减少误写。展示命令时只保留必要命令，不要截图整段终端；如果命令依赖特定位置，先写一句「在项目根目录执行」再贴代码。详见代码块与链接引用。
提交文档前要检查哪些内容？
Section titled “提交文档前要检查哪些内容？”按五步检查：标题是否准确概括内容、章节顺序是否从背景到操作、命令是否经过实际运行验证、链接是否仍可访问、有没有没写清的假设。最后一步最容易跳过，因为它需要你把自己当成第一次读文档的人。详见表格、提示框与提交前检查。
README 里能同时写多个版本的配置说明吗？
Section titled “README 里能同时写多个版本的配置说明吗？”不建议。同一份文档里混着多个版本的说明，读者无法判断哪条有效，认知负担明显升高。README 只放当前版本最准确的信息，过期说明移到历史文档或 changelog。详见README 与协作文档。
- CommonMark 快速参考——官方规范项目的速查页，附 10 分钟教程，适合核对语法细节
- GitHub 基础写作与格式化语法——GitHub 官方文档，覆盖评论、Issue 与 .md 文件的完整语法，与 README 场景直接相关
- Markdown Guide 基础语法——按条目给出示例与渲染结果，适合逐项对照练习
相关课程
- Modern Git 进阶全攻略
从常用工作流到提交规范，掌握团队协作必备的 Git 能力。