软件文档的 Markdown 最佳实践

好的文档与好的代码同样重要。Markdown 已成为 GitHub、GitLab、Confluence 及无数其他平台上技术文档的标准格式。以下是顶级工程团队所采用的最佳实践。

组织文档结构

每份文档都应有清晰的层次结构。使用单个 # H1 作为标题，然后用 ## H2 划分主要章节，### H3 划分子章节。

# API Reference

## Authentication

### API Keys

### OAuth 2.0

切勿跳过标题级别——从 ## 直接跳到 #### 会给读者和屏幕阅读器造成困惑。

代码块不可省略

始终为代码块指定语言。这样可以启用语法高亮，并告知读者代码的类型：

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

对于终端命令，使用 bash 或 sh。对于配置文件，使用相应的格式（yaml、toml、json）。

记录命令输出

在记录 CLI 工具时，同时展示命令及其预期输出：

```bash
$ git status
On branch main
nothing to commit, working tree clean
```

使用表格记录配置选项

表格非常适合用于记录配置参数：

重要信息使用提示块

许多平台支持提示/警告块语法。以引用块作为备选方案：

> **Note:** This feature requires Node.js 18 or later.

> **Warning:** This operation is irreversible.

保持可维护性

• 内部文档引用使用相对链接
• 将图片文件存放在专用的 docs/images/ 目录中
• 在长期维护的文档中注明"最后更新"日期
• 将过长的文档拆分成多个相互链接的较小文件

将文档与代码一同版本化

文档应与其所描述的代码存放在同一仓库中。这能确保文档随版本发布保持同步，并可在同一 pull request 中与代码变更一起进行审查。