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

# 开发规范

## Markdown 编写规范

### 标题层级

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

### 代码块

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

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

```
### 链接

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

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

### 图片

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

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

### 表格

使用 Markdown 表格语法：

```markdown
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 值1 | 值2 | 值3 |
```

## 文档结构规范

### 文档头部

每个文档应包含：

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

### 章节组织

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

## 命名规范

### 文件名

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

### 目录名

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

## 内容规范

### 语言风格

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

### 代码示例

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

### 更新记录

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

```markdown
## 更新记录

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