用 Markdown 编写软件文档

与代码共存的文档

试用文档导出

优秀的软件值得拥有优秀的文档。Markdown 已成为软件文档的标准，因为它与代码共存，通过版本控制跟踪更改，并在从 GitHub 到文档网站的各处精美呈现。

本指南涵盖了使用 Markdown 编写有效软件文档的最佳实践。

为什么用 Markdown 写文档？

与代码共存

将文档保存在与代码相同的仓库中。当代码更改时，文档可以在同一个提交中更新。不需要维护或同步单独的 wiki。

版本控制

文档更改就像代码更改一样被跟踪。在 Pull Request 中审查文档更新。需要时可以回滚。查看谁在什么时候写了什么。

平台无关

Markdown 在 GitHub、GitLab、Bitbucket、文档网站和无数其他平台上都能渲染。一次编写，随处展示。

README 最佳实践

您的 README 通常是用户看到的第一个东西。务必做好。

基本章节

# Project Name

Brief description of what this project does.

## Installation

```bash
npm install your-package
```

## Quick Start

```javascript
import { feature } from 'your-package';
feature.doSomething();
```

## Documentation

Link to full docs.

## Contributing

How to contribute.

## License

MIT

API 文档

用一致的格式清晰地记录您的 API：

## `createUser(options)`

Creates a new user account.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | User's display name |
| `email` | string | Yes | User's email address |
| `role` | string | No | User role (default: "user") |

### Returns

`Promise<User>` - The created user object.

### Example

```javascript
const user = await createUser({
  name: 'Jane Doe',
  email: 'jane@example.com'
});
```

一致的结构帮助开发者快速找到他们需要的信息。

预览您的文档

用户指南和教程

分步文档帮助用户成功：

## Getting Started with Authentication

This guide walks through setting up authentication.

### Prerequisites

- Node.js 18+
- An API key (get one at dashboard.example.com)

### Step 1: Install the Package

```bash
npm install @example/auth
```

### Step 2: Configure Your Environment

Create a `.env` file:

```
AUTH_API_KEY=your-api-key-here
```

### Step 3: Initialize Authentication

```javascript
import { initAuth } from '@example/auth';

const auth = initAuth({
  apiKey: process.env.AUTH_API_KEY
});
```

代码块和语法

使用 GitHub 风格 Markdown 的功能来编写技术内容：

语言特定高亮

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

差异高亮

```diff
- const old = "previous";
+ const new = "updated";
```

文件名

显示用户应该编辑的文件：

**`config/settings.json`**
```json
{
  "debug": true
}
```

在我们的高级功能指南中了解更多。

维护文档

保持更新

在代码更改的同一个 PR 中更新文档
在代码审查时同时审查文档
删除已弃用功能的文档

链接验证

失效的链接令用户沮丧。定期检查内部和外部链接是否仍然有效。

导出分发

需要在仓库外分享文档？导出为 HTML 用于网页托管，或 PDF 用于离线访问。

文档结构

以清晰的层次结构组织较大的文档集：

docs/
├── README.md           # Overview and quick start
├── getting-started/
│   ├── installation.md
│   └── configuration.md
├── guides/
│   ├── authentication.md
│   └── deployment.md
├── api/
│   ├── overview.md
│   └── endpoints.md
└── contributing.md

这种结构从小型项目到大型框架都适用。