54 lines
1.2 KiB
Plaintext
54 lines
1.2 KiB
Plaintext
|
---
|
|||
|
|
description: markdown 文件编写规则
|
|||
|
|
globs: *.md
|
|||
|
|
alwaysApply: false
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 文档规范
|
|||
|
|
|
|||
|
|
## 通用要求
|
|||
|
|
- 所有文档使用Markdown格式
|
|||
|
|
- 使用简洁、清晰的语言
|
|||
|
|
- 文档内容应保持最新
|
|||
|
|
- 避免拼写和语法错误
|
|||
|
|
- 使用中文作为主要语言
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
- `README.md`：项目根目录，提供项目概述
|
|||
|
|
- `docs/`：存放详细文档
|
|||
|
|
- `guide/`：使用指南
|
|||
|
|
- `api/`：API文档
|
|||
|
|
- `examples/`：示例代码文档
|
|||
|
|
|
|||
|
|
## README.md 内容规范
|
|||
|
|
- 项目名称和简短描述
|
|||
|
|
- 技术栈说明
|
|||
|
|
- 项目结构说明
|
|||
|
|
- 使用说明
|
|||
|
|
- 许可证信息
|
|||
|
|
|
|||
|
|
## 版本记录规范
|
|||
|
|
- 使用 `CHANGELOG.md` 记录版本变更
|
|||
|
|
- 遵循语义化版本（Semantic Versioning）规范
|
|||
|
|
- 每个版本应包含：新增功能、修复问题、破坏性变更
|
|||
|
|
|
|||
|
|
## 文档内容组织
|
|||
|
|
- 从整体到局部，从简单到复杂
|
|||
|
|
- 重要信息放在前面
|
|||
|
|
- 相关内容应当放在一起
|
|||
|
|
- 使用小标题和列表增强可读性
|
|||
|
|
- 避免过长段落，保持内容简洁
|
|||
|
|
|
|||
|
|
## 代码示例规范
|
|||
|
|
- 提供完整可运行的示例
|
|||
|
|
- 代码应当简洁且易于理解
|
|||
|
|
- 添加适当的注释解释关键部分
|
|||
|
|
- 说明代码的预期输出或行为
|
|||
|
|
- 更新示例以匹配最新API
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
|