mkdocs/docs/开发指南/开发规范.md

开发规范

Markdown 编写规范

标题层级

• 使用 # 作为文档主标题（H1）
• 使用 ## 作为章节标题（H2）
• 使用 ### 作为小节标题（H3）
• 避免跳过标题层级

代码块

使用三个反引号包裹代码，并指定语言：

```python
def hello():
    print("Hello, World!")

### 链接

- 内部链接：使用相对路径
- 外部链接：使用完整 URL

```markdown
[内部文档](../其他文档.md)
[外部链接](https://example.com)

图片

将图片放在 docs/images/ 目录，使用相对路径：

![图片描述](images/example.png)

表格

使用 Markdown 表格语法：

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 值1 | 值2 | 值3 |

文档结构规范

文档头部

每个文档应包含：

• 标题（H1）
• 简要描述
• 目录（可选，用于长文档）

章节组织

• 使用清晰的章节标题
• 保持逻辑顺序
• 使用列表和表格增强可读性

命名规范

文件名

• 使用小写字母和连字符
• 避免使用空格和特殊字符
• 示例：快速开始.md、api-文档.md

目录名

• 使用中文或英文
• 保持简洁明了
• 示例：开发指南/、dev-guide/

内容规范

语言风格

• 使用简洁明了的语言
• 避免冗长的句子
• 使用列表和表格组织信息

代码示例

• 提供完整可运行的代码示例
• 添加必要的注释
• 说明代码的用途和注意事项

更新记录

重要文档建议添加更新记录：

## 更新记录

- 2024-01-01: 初始版本
- 2024-01-15: 添加新功能说明