name: markdown-documentation user-invocable: false description: 用于使用Markdown编写技术文档、README或项目文档时。涵盖结构、约定和最佳实践。 allowed-tools:

读取
写入
编辑
Grep
Glob

Markdown 文档编写

编写有效的Markdown技术文档的最佳实践。

README 结构

最小化 README

# 项目名称

简要描述这个项目的功能。

## 安装

安装说明。

## 使用

基本使用示例。

## 许可证

MIT

全面 README

# 项目名称

![构建状态](badge-url)
![版本](badge-url)

项目的一段描述。

## 特性

- 特性一
- 特性二
- 特性三

## 安装

### 先决条件

- 要求1
- 要求2

### 步骤

说明...

## 使用

### 基本示例

代码示例...

### 高级使用

更多示例...

## 配置

配置选项...

## API 参考

API文档...

## 贡献

查看 [CONTRIBUTING.md](CONTRIBUTING.md)

## 许可证

MIT许可证 - 参见 [LICENSE](LICENSE)

文档组织

文件命名

docs/
├── README.md           # 入口点
├── CONTRIBUTING.md     # 贡献指南
├── CHANGELOG.md        # 版本历史
├── CODE_OF_CONDUCT.md  # 社区指南
├── getting-started.md  # 入门指南
├── api/
│   ├── README.md       # API概述
│   └── endpoints.md    # 端点参考
└── guides/
    ├── installation.md
    └── configuration.md

文档间链接

有关详细信息，请参阅[安装指南](./guides/installation.md)。

对于API参考，请查看[端点](./api/endpoints.md#authentication)。

写作风格

简洁明了

<!-- 差 -->
为了安装应用程序，您需要运行以下命令。

<!-- 好 -->
安装应用程序：

使用主动语态

<!-- 差 -->
配置文件应在主目录中创建。

<!-- 好 -->
在您的主目录中创建配置文件。

直接面向读者

<!-- 差 -->
用户可以配置超时设置。

<!-- 好 -->
您可以配置超时设置。

代码文档

内联代码与代码块

使用 `npm install` 安装依赖项。

对于多个命令，使用代码块：

```bash
npm install
npm run build
npm start


### 命令示例

显示命令和输出：

```bash
$ npm --version
10.2.0

配置示例

始终展示完整、有效的示例：

创建 config.json：

{
  "port": 3000,
  "debug": true,
  "database": {
    "host": "localhost",
    "name": "myapp"
  }
}

提示和标注

GitHub风格提醒

> [!NOTE]
> 用户应该知道的有用信息。

> [!TIP]
> 做事更好的有益建议。

> [!IMPORTANT]
> 用户需要知道的关键信息。

> [!WARNING]
> 需要立即关注的紧急信息。

> [!CAUTION]
> 关于风险或负面结果的建议。

自定义标注（基于表情符号）

⚠️ **警告**：此操作无法撤销。

💡 **提示**：使用环境变量处理敏感数据。

📝 **注意**：此功能需要版本2.0+。

API 文档

端点文档

创建用户

创建新用户账户。

请求： POST /api/users

头部：

头部	值	必需
Content-Type	application/json	✅
Authorization	Bearer {token}	✅

主体：

{
  "name": "John Doe",
  "email": "john@example.com"
}

响应（201）：

{
  "id": "abc123",
  "name": "John Doe",
  "email": "john@example.com"
}

错误（400）：

{
  "error": "无效的电子邮件格式"
}

函数文档

`parseConfig(path, options?)`

解析配置文件。

参数：

名称	类型	默认值	描述
path	string	—	配置文件路径
options.strict	boolean	false	遇到未知键时抛出错误
options.env	boolean	true	扩展环境变量

返回： Config - 解析后的配置对象

抛出：

FileNotFoundError - 配置文件不存在
ParseError - 无效的JSON/YAML语法

示例：

const config = parseConfig('./config.json', { strict: true });

更新日志

保持更新日志格式

# 更新日志

此项目的所有显著更改将记录在此文件中。

## [未发布]

### 新增
- 新特性X

### 更改
- 更新依赖Y

## [1.2.0] - 2024-01-15

### 新增
- 特性A
- 特性B

### 修复
- 特性C中的错误

### 弃用
- 旧API端点

## [1.1.0] - 2024-01-01

### 新增
- 初始发布

图表

Mermaid（GitHub支持）

```mermaid
graph LR
    A[开始] --> B{决策}
    B -->|是| C[操作1]
    B -->|否| D[操作2]
    C --> E[结束]
    D --> E
```

ASCII 图表

```
┌─────────┐     ┌─────────┐     ┌─────────┐
│ 客户端  │────▶│ 服务器  │────▶│ 数据库 │
└─────────┘     └─────────┘     └─────────┘
```

最佳实践

从为什么开始：解释项目的功能和存在原因
展示而非讲述：提供有效的代码示例
保持最新：代码更改时更新文档
测试示例：确保代码示例实际工作
使用一致的术语：定义术语并一致使用
提供上下文：链接到先决条件和相关文档
考虑受众：根据用户技能水平编写
包括故障排除：记录常见错误和解决方案

常见文档文件

文件	目的
README.md	项目概述和快速开始
CONTRIBUTING.md	如何贡献
CHANGELOG.md	版本历史
LICENSE	法律条款
CODE_OF_CONDUCT.md	社区指南
SECURITY.md	安全政策
SUPPORT.md	如何获取帮助