第 13 章：实战场景
语法学完了，工具也选好了。现在走进真实的使用场景，看看在实际项目中如何运用 Markdown 写出高质量内容。
学习目标
- 掌握高质量 GitHub README 的写作方法
- 了解技术博客的 Markdown 写作流程
- 学会编写规范的项目文档
- 构建高效的 Markdown 笔记体系
13.1 GitHub README 编写
README 是项目的名片。一个好的 README 能极大提高项目的吸引力和可维护性。
README 黄金结构
markdown
# 项目名称
<!-- 徽章：构建状态、版本、许可证 -->
<!-- 一句话描述 -->
简短有力的项目描述（一句话说清楚这是什么）
<!-- 特性 -->
## ✨ 特性
- 特性 1
- 特性 2
- 特性 3
<!-- 快速开始 -->
## 🚀 快速开始
### 环境要求
- Node.js >= 18
- npm >= 9
### 安装
\`\`\`bash
git clone https://github.com/user/repo.git
cd repo
npm install
\`\`\`
### 使用
\`\`\`javascript
import { myLib } from 'my-lib';
const result = myLib.doThing();
console.log(result);
\`\`\`
<!-- API 文档 -->
## 📖 API
| 方法 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `doThing()` | — | `string` | 做某件事 |
| `configure(opts)` | `Options` | `void` | 配置选项 |
<!-- 贡献指南 -->
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
<!-- 许可证 -->
## 📄 许可证
MIT © 2024 Your NameREADME 模板
完整模板见：examples/templates/github-readme-template.md
README 写作要点
- 一句话说清楚这是什么：放在最显眼的位置
- 快速开始要真的快：3 步内让用户跑起来
- API 用表格呈现：方法名、参数、返回值一目了然
- 配上截图：界面类项目，一张截图胜过千言万语
- 加上徽章：构建状态、版本、许可证一目了然
13.2 技术博客写作
博客 Markdown 结构
markdown
# 文章标题
> 摘要：一句话概括文章主旨
## 背景
为什么需要这篇文章？解决了什么问题？
## 正文
### 小标题 1
内容...
### 小标题 2
内容...
## 实践建议
- 建议 1
- 建议 2
## 总结
核心观点的回顾。
## 参考
- [参考链接 1](https://example.com)
- [参考链接 2](https://example.com)博客写作技巧
- 标题下加摘要：用引用块写一两句话的 TL;DR
- 善用代码块：技术博客的核心是代码演示
- 流程图先行：复杂逻辑先用 Mermaid 流程图讲清楚
- 分段清晰：每个小节不超过 3-5 段，合理使用二级和三级标题
- 结尾有参考：列出参考链接，既是尊重原作者的引用，也方便读者延伸阅读
13.3 项目文档写作
一个规范的软件项目通常需要以下文档：
docs/
├── README.md # 项目概述
├── getting-started.md # 快速上手
├── installation.md # 详细安装指南
├── api/ # API 文档
│ ├── overview.md
│ └── endpoints/
├── architecture.md # 架构设计
├── contributing.md # 贡献指南
├── changelog.md # 更新日志
└── faq.md # 常见问题文档编写原则
- 明确受众：写给谁看？（新用户？开发者？架构师？）
- 渐进式：从最简单的「快速开始」到详细的「API 参考」
- 示例驱动：每个功能都要有可运行的代码示例
- 保持更新：文档和代码用同一个 Git 仓库，版本同步
13.4 个人笔记体系
Obsidian 式双向链接笔记
Obsidian 引入的 [[链接]] 语法改变了笔记的组织方式：
markdown
# 设计模式 - 观察者模式
观察者模式是一种 [[行为型设计模式]]，与 [[发布订阅模式]] 密切相关。
## 应用场景
- [[前端框架 - 响应式系统]]
- [[事件驱动架构]]这样，每篇笔记都通过链接互相串联，形成知识网络而非孤立片段。
笔记结构建议
notebook/
├── 00-Inbox/ # 收集箱：快速记录，定期整理
├── 10-工作/
│ ├── 项目A/
│ └── 会议记录/
├── 20-学习/
│ ├── 前端/
│ ├── 后端/
│ └── 系统设计/
├── 30-生活/
└── 40-归档/笔记命名规范
YYYY-MM-DD 主题.md # 日记类
主题 - 子主题.md # 知识类
项目名 - 模块.md # 项目类
会议 - YYYY-MM-DD 主题.md # 会议记录13.5 Markdown 在团队中的规范
统一编辑器配置
在项目根目录创建 .editorconfig：
ini
[*.md]
trim_trailing_whitespace = true
insert_final_newline = true
max_line_length = 120统一 Markdown 格式化
使用 Prettier 或 markdownlint 统一团队的 Markdown 风格：
bash
# 安装 prettier
npm install -D prettier
# 格式化所有 Markdown 文件
npx prettier --write "**/*.md"团队文档协作流程
编写 Markdown → Git 提交 → PR 审查（看文档和看代码一样） → 合并 → 自动部署文档站本章小结
| 要点 | 说明 |
|---|---|
| README | 黄金结构：项目名 + 特性 + 快速开始 + API + 许可证 |
| 技术博客 | 摘要先行，流程图讲逻辑，代码演示核心 |
| 项目文档 | 渐进式：快速开始 → 安装 → API → 架构 |
| 个人笔记 | 双向链接 + 定期整理 = 知识网络 |
| 团队规范 | 统一格式 + Git 管理 + PR 审查 |
下一章预告
最后一章，我们来总结 Markdown 写作的最佳实践——规范、常见错误避坑和终极速查表。