We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/yfcyfc123234/showdoc_mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
---
alwaysApply: true
---
# 文档格式规范
> 确保项目中的文档保持统一格式，避免格式警告，提高文档质量和可读性
## 核心原则
### 文档质量要求
- **格式统一**：所有文档遵循统一的格式规范
- **避免警告**：避免 Markdown lint 等工具的格式警告
- **易于阅读**：文档结构清晰，易于理解和维护
- **保持更新**：文档与代码保持同步更新
### 文档类型
项目中可能包含以下类型的文档：
1. **Markdown 文档**：README.md、CHANGELOG.md、CONTRIBUTING.md 等
2. **代码注释**：函数注释、类注释、API 文档注释
3. **配置文件注释**：配置文件中的说明性注释
4. **规则文件**：`.mdc` 规则文件
## Markdown 文档格式规范
### 文件结构
#### 标准 Markdown 文件结构
```markdown
# 文档标题
> 简短的描述说明
## 目录（可选，长文档建议添加）
- [章节 1](#章节-1)
- [章节 2](#章节-2)
## 章节 1
内容...
## 章节 2
内容...
---
**最后更新**：YYYY-MM-DD
```
#### README.md 标准结构
```markdown
# 项目名称
> 项目简短描述（可选）
## 📋 项目概述
项目的基本介绍和用途
## 🚀 快速开始
### 安装
### 使用
## 📖 文档
## 🤝 贡献
## 📄 许可证
---
**最后更新**：YYYY-MM-DD
```
### 标题规范
1. **标题层级**
- 一级标题（`#`）：文档主标题，每份文档只有一个
- 二级标题（`##`）：主要章节
- 三级标题（`###`）：子章节
- 四级标题（`####`）：细分内容
- 避免超过四级标题
2. **标题格式**
- 标题前后空一行
- 标题后不跟标点符号
- 标题尽量简洁明确
- 可以使用 Emoji 图标（可选，保持一致性）
3. **标题示例**
```markdown
✅ 正确：
## 代码风格规范
❌ 错误：
## 代码风格规范。
##代码风格规范
```
### 列表规范
1. **有序列表**
- 使用数字编号（`1.`、`2.`）
- 列表项前后空一行（如果与其他内容相邻）
- 嵌套列表使用 2 或 4 个空格缩进
2. **无序列表**
- 使用 `-` 或 `*`（建议统一使用 `-`）
- 保持一致的列表标记
- 列表项前后空一行（如果与其他内容相邻）
3. **列表示例**
```markdown
✅ 正确：
以下是一些要点：
- 第一点
- 第二点
- 嵌套点 1
- 嵌套点 2
- 第三点
❌ 错误：
-第一点
- 第二点
```
### 代码块规范
1. **代码块格式**
- 使用三个反引号（`` ``` ``）包裹代码
- 指定语言类型（如 ````python`、````javascript`）
- 代码块前后空一行
2. **内联代码**
- 使用单个反引号（`` ` ``）包裹
- 用于文件名、变量名、函数名等
3. **代码块示例**
```markdown
✅ 正确：
这是一个代码块：
```python
def hello():
print("Hello")
```
❌ 错误：
```python
def hello():
print("Hello")
```
```
### 链接和图片规范
1. **链接格式**
- 使用 `[链接文字](URL)` 格式
- 链接文字应该描述链接内容
- 长链接使用引用格式更清晰
2. **图片格式**
- 使用 `` 格式
- 必须包含图片描述（Alt 文本）
- 使用相对路径或绝对路径保持一致
3. **链接和图片示例**
```markdown
✅ 正确：
[查看文档](https://example.com/docs)
❌ 错误：
[点击这里](https://example.com/docs)
```
### 表格规范
1. **表格格式**
- 使用管道符（`|`）分隔列
- 使用 `---` 分隔表头和数据
- 表头行和分隔行前后空一行
- 对齐方式可选（`:---:` 居中，`:---` 左对齐，`---:` 右对齐）
2. **表格示例**
```markdown
✅ 正确：
| 列1 | 列2 | 列3 |
|-----|:---:|----:|
| 左对齐 | 居中 | 右对齐 |
| 数据1 | 数据2 | 数据3 |
❌ 错误：
|列1|列2|列3|
|数据1|数据2|数据3|
```
### 强调和引用规范
1. **强调格式**
- **粗体**：使用 `**文字**`
- *斜体*：使用 `*文字*`
- 避免过度使用强调
2. **引用格式**
- 使用 `>` 表示引用
- 多行引用每行都加 `>`
- 引用前后空一行
3. **示例**
```markdown
✅ 正确：
> 这是一个引用块
> 可以有多行
❌ 错误：
>这是一个引用块
可以有多行
```
### 空格和空行规范
1. **中英文之间**
- 中英文之间添加空格（如：`这是一个 example`）
- 中文和数字之间添加空格（如：`第 1 章`）
2. **标点符号**
- 中文标点符号前后不加空格
- 英文标点符号后加空格
3. **空行**
- 标题前后各空一行
- 段落之间空一行
- 列表前后各空一行
- 代码块前后各空一行
### 避免的常见问题
1. **Markdown Lint 警告**
- ❌ 避免尾随空格（行尾多余空格）
- ❌ 避免缺少空行（标题、列表、代码块前后）
- ❌ 避免过长的行（建议不超过 100-120 字符）
- ❌ 避免使用 HTML 标签（尽量使用 Markdown 语法）
2. **格式问题**
- ❌ 避免混用列表标记（统一使用 `-` 或 `*`）
- ❌ 避免标题层级跳跃（如直接从 `##` 跳到 `####`）
- ❌ 避免代码块缺少语言标识
## 代码注释文档规范
### 函数注释
#### Python 函数注释
```python
def fetch_user_data(user_id: int, include_profile: bool = False) -> dict:
"""
获取用户数据。
Args:
user_id: 用户 ID
include_profile: 是否包含用户资料信息，默认为 False
Returns:
包含用户数据的字典
Raises:
ValueError: 当 user_id 无效时
ConnectionError: 当网络连接失败时
"""
pass
```
#### JavaScript/TypeScript 函数注释
```javascript
/**
* 获取用户数据
*
* @param {number} userId - 用户 ID
* @param {boolean} [includeProfile=false] - 是否包含用户资料信息
* @returns {Promise<Object>} 包含用户数据的对象
* @throws {Error} 当 user_id 无效时
*/
async function fetchUserData(userId, includeProfile = false) {
// ...
}
```
#### Kotlin/Java 函数注释
```kotlin
/**
* 获取用户数据
*
* @param userId 用户 ID
* @param includeProfile 是否包含用户资料信息，默认为 false
* @return 包含用户数据的 Map
* @throws IllegalArgumentException 当 userId 无效时
*/
fun fetchUserData(userId: Int, includeProfile: Boolean = false): Map<String, Any> {
// ...
}
```
### 类注释
```python
class UserRepository:
"""用户数据仓库类。
负责处理用户数据的增删改查操作。
Attributes:
db_connection: 数据库连接对象
cache: 缓存对象
"""
pass
```
### API 文档注释
#### OpenAPI/Swagger 格式
```yaml
paths:
/users/{userId}:
get:
summary: 获取用户信息
description: 根据用户 ID 获取用户的详细信息
parameters:
- name: userId
in: path
required: true
schema:
type: integer
responses:
'200':
description: 成功返回用户信息
'404':
description: 用户不存在
```
## 配置文件注释规范
### 配置注释格式
```yaml
# 数据库配置
database:
host: localhost # 数据库主机地址
port: 3306 # 数据库端口
name: myapp # 数据库名称
user: admin # 数据库用户名
# password: secret # 数据库密码（生产环境从环境变量读取）
```
## 规则文件（.mdc）格式规范
### Frontmatter 格式
所有 `.mdc` 规则文件必须包含 frontmatter：
```markdown
---
alwaysApply: true
---
# 规则标题
规则内容...
```
### 规则文件结构
```markdown
---
alwaysApply: true
---
# 规则标题
> 简短的规则描述
## 核心原则
## 具体规范
## 注意事项
## 示例
```
## 文档检查清单
### Markdown 文档检查
在创建或修改 Markdown 文档后，检查以下项目：
- [ ] 标题前后有空行
- [ ] 列表前后有空行
- [ ] 代码块前后有空行
- [ ] 没有尾随空格
- [ ] 链接文字描述清晰
- [ ] 图片包含 Alt 文本
- [ ] 表格格式正确
- [ ] 中英文之间有空格
- [ ] 行长度不超过建议值（100-120 字符）
### 代码注释检查
- [ ] 所有公开函数都有注释
- [ ] 注释说明函数的用途
- [ ] 注释包含参数说明
- [ ] 注释包含返回值说明
- [ ] 注释包含异常说明（如适用）
- [ ] 注释与代码保持同步
## 工具推荐
### Markdown Lint 工具
1. **markdownlint**（VS Code 扩展）
- 自动检测 Markdown 格式问题
- 提供格式修复建议
2. **Prettier**
- 自动格式化 Markdown 文件
- 统一代码和文档格式
### 文档生成工具
1. **Sphinx**（Python）
2. **JSDoc**（JavaScript）
3. **KDoc**（Kotlin）
4. **JavaDoc**（Java）
## 最佳实践
### 1. 保持文档更新
- 代码变更时同步更新文档
- 定期检查文档的准确性
- 删除过时的文档
### 2. 使用清晰的标题
- 标题描述章节内容
- 避免过于宽泛或过于具体的标题
- 保持标题层级清晰
### 3. 添加示例代码
- 提供可运行的示例代码
- 示例代码应该完整且正确
- 注释解释关键步骤
### 4. 使用统一的术语
- 统一使用技术术语
- 避免混用不同的术语
- 在文档开头定义术语表（如需要）
### 5. 考虑读者水平
- 根据目标读者调整文档详细程度
- 提供入门和进阶内容
- 链接到相关文档
## 注意事项
1. **格式一致性**
- 整个项目的文档保持格式一致
- 使用相同的 Markdown 风格
- 遵循项目的文档模板
2. **避免过度格式化**
- 不要过度使用强调和格式
- 保持文档简洁易读
- 重点内容才使用强调
3. **可访问性**
- 图片必须有 Alt 文本
- 链接文字描述清晰
- 使用语义化的 HTML（如需要）
4. **版本控制**
- 文档变更记录在 Git 提交信息中
- 重大文档更新记录在 CHANGELOG 中
- 文档最后更新日期（可选）
## 实际修复经验总结
> **说明**：本部分总结了在实际修复文档格式警告过程中积累的经验，这些经验来自修复大量 Markdown 文档的格式警告。所有项目在创建或修改文档时，都应该遵循这些经验，避免格式警告。
>
> **注意**：本文档中的某些示例代码块可能包含嵌套代码块，这是为了展示格式规范的需要。在实际项目中，应该避免这种嵌套，使用缩进文本代替。
基于大量文档格式警告的实际修复经验，以下是常见问题和解决方案：
### 最常见的 Markdown Lint 警告及修复方法
#### 1. MD032 - 列表前后缺少空行
**问题**：列表前后必须有空行，否则会被标记为警告。
**修复方法**：
```markdown
❌ 错误：
以下是一些要点：
- 第一点
- 第二点
内容继续...
✅ 正确：
以下是一些要点：
- 第一点
- 第二点
内容继续...
```
**修复要点**：
- 列表开始前必须空一行
- 列表结束后必须空一行
- 即使列表前是标题或段落，也需要空行
#### 2. MD040 - 代码块缺少语言标识
**问题**：所有代码块都应该指定语言类型，即使只是文本示例。
**修复方法**：
```markdown
❌ 错误：
\`\`\`
代码内容
\`\`\`
✅ 正确：
\`\`\`text
代码内容
\`\`\`
或者：
\`\`\`python
代码内容
\`\`\`
```
**修复要点**：
- 所有代码块都必须有语言标识
- 纯文本示例使用 `text`
- 代码示例使用对应的语言（`python`、`javascript`、`kotlin` 等）
- Markdown 模板内容使用 `markdown`
#### 3. MD029 - 有序列表编号问题
**问题**：当列表被分类或分组时，每个分类应该从 1 开始编号，而不是连续编号。
**修复方法**：
```markdown
❌ 错误（跨分类连续编号）：
**前端：**
1. React
2. Vue
**后端：**
3. Node.js ← 应该是 1
4. Spring Boot ← 应该是 2
✅ 正确（每个分类独立编号）：
**前端：**
1. React
2. Vue
**后端：**
1. Node.js
2. Spring Boot
```
**修复要点**：
- 不同分类的列表应该独立编号
- 每个分类从 1 开始
- 如果列表很长，考虑使用无序列表或分组
#### 4. MD024 - 重复标题
**问题**：同一文档中不能有相同内容的标题（即使在不同章节）。
**修复方法**：
```markdown
❌ 错误（重复标题）：
### Android 项目
#### 沉浸式状态栏实现
...
### Flutter 项目
#### 沉浸式状态栏实现 ← 重复！
✅ 正确（添加前缀区分）：
### Android 项目
#### Android 沉浸式状态栏实现
...
### Flutter 项目
#### Flutter 沉浸式状态栏实现 ← 添加前缀区分
```
**修复要点**：
- 相同内容的标题需要添加前缀或后缀区分
- 可以添加项目类型、平台类型等前缀
- 或者使用更具体的标题描述
#### 5. MD004 - 列表标记不统一
**问题**：整个文档应该统一使用一种列表标记（`-` 或 `*`）。
**修复方法**：
```markdown
❌ 错误（混用标记）：
- 第一点
* 第二点 ← 混用了 *
- 第三点
✅ 正确（统一使用 `-`）：
- 第一点
- 第二点
- 第三点
```
**修复要点**：
- 建议统一使用 `-`（更常见）
- 整个文档保持一致
- 嵌套列表也使用相同的标记
#### 6. MD022 - 标题周围缺少空行
**问题**：标题前后必须有空行，包括子标题。
**修复方法**：
```markdown
❌ 错误：
#### 用户操作
- 操作1
✅ 正确：
#### 用户操作
- 操作1
```
**修复要点**：
- 标题后面也必须空一行（即使后面是列表）
- 标题前面也要空一行
- 所有层级的标题都要遵循
#### 7. MD031 - 代码块周围缺少空行
**问题**：代码块前后必须有空行。
**修复方法**：
```markdown
❌ 错误：
标题
```python
代码
```
✅ 正确：
标题
```python
代码
```
```
**修复要点**：
- 代码块开始前必须空一行
- 代码块结束后必须空一行
- 即使代码块在列表项中，也要空行
#### 8. MD009 - 尾随空格
**问题**：行尾不应该有多余的空格。
**修复方法**：
- 使用编辑器自动删除尾随空格功能
- 或者在保存时自动清理
- 检查每行的末尾
#### 9. MD012 - 多个连续空行
**问题**：文档中不应该有超过一个连续的空行。
**修复方法**：
```markdown
❌ 错误：
内容1
内容2 ← 两个空行
✅ 正确：
内容1
内容2 ← 只有一个空行
```
#### 10. 嵌套代码块问题
**问题**：在代码块中嵌套代码块可能导致 linter 混淆。
**修复方法**：
**问题说明**：应避免在 markdown 代码块中嵌套 text 代码块，这会导致 linter 混淆。
**正确做法**：使用缩进代替嵌套代码块。例如：
模板内容：
使用缩进格式展示代码示例：
代码内容
更多代码
**修复要点**：
- 避免在代码块中嵌套代码块
- 使用缩进文本代替嵌套代码块
- 或者将嵌套内容改为纯文本描述
### 快速修复检查清单
在修复文档格式警告时，按以下顺序检查：
1. **检查列表格式** ✅
- [ ] 所有列表前后都有空行
- [ ] 列表标记统一（全部使用 `-`）
- [ ] 有序列表编号正确（分类列表独立编号）
2. **检查代码块格式** ✅
- [ ] 所有代码块都有语言标识
- [ ] 代码块前后都有空行
- [ ] 避免嵌套代码块（使用缩进代替）
3. **检查标题格式** ✅
- [ ] 所有标题前后都有空行
- [ ] 标题后不跟标点符号
- [ ] 没有重复标题（添加前缀区分）
4. **检查空行和空格** ✅
- [ ] 没有尾随空格
- [ ] 没有多个连续空行
- [ ] 段落之间只有一个空行
5. **检查其他格式** ✅
- [ ] 表格格式正确
- [ ] 链接和图片格式正确
- [ ] 中英文之间有空格
### 批量修复建议
当需要修复大量格式警告时：
1. **按类型分组修复**
- 先修复所有列表相关警告
- 再修复所有代码块相关警告
- 最后修复其他格式问题
2. **使用工具辅助**
- 使用 Prettier 自动格式化
- 使用 markdownlint 检查问题
- 使用编辑器的格式化功能
3. **逐步验证**
- 每修复一类问题后，检查 linter 警告数量
- 确保修复没有引入新问题
- 最终确保所有警告都已清除
## 自动修复建议
当检测到文档格式问题时：
1. **自动修复**
- 删除尾随空格
- 添加必要的空行
- 修正列表格式
- 为代码块添加语言标识（如果缺失）
- 统一列表标记（全部改为 `-`）
2. **提示用户修复**
- 标题层级问题
- 链接格式问题
- 代码块嵌套问题
- 重复标题问题
- 有序列表编号问题
3. **记录警告**
- 过长的行
- 缺少的注释
- 格式不一致