内容创建指南

本指南介绍如何在 AutoDoc 系统中创建和组织高质量的文档内容。

📝 文档创建基础

Markdown 语法

AutoDoc 使用 Markdown 格式编写文档。以下是常用的语法：

标题

# 一级标题
## 二级标题
### 三级标题
#### 四级标题

文本格式

**粗体文本**
*斜体文本*
~~删除线~~
`行内代码`

列表

# 无序列表
- 项目 1
- 项目 2
  - 子项目 2.1
  - 子项目 2.2

# 有序列表
1. 第一项
2. 第二项
3. 第三项

链接和图片

# 链接
[链接文本](./other-file.md)
[外部链接](https://example.com)

# 图片
![图片描述](./images/screenshot.png)
![网络图片](https://example.com/image.png)

代码块

```javascript
function hello() {
  console.log('Hello, World!');
}


#### 表格
```markdown
| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 数据1 | 数据2 | 数据3 |
| 数据4 | 数据5 | 数据6 |

VuePress 扩展语法

提示框

::: tip 提示
这是一个提示框
:::

::: warning 警告
这是一个警告框
:::

::: danger 危险
这是一个危险提示框
:::

::: info 信息
这是一个信息框
:::

代码组

::: code-group

```js [JavaScript]
console.log('Hello from JavaScript');

print('Hello from Python')

echo "Hello from Shell"

:::


## 📁 文件组织

### 目录结构规范

docs/ ├── README.md # 首页 ├── guide/ # 使用指南 │ ├── README.md # 指南首页 │ ├── getting-started.md # 快速开始 │ ├── configuration.md # 配置说明 │ └── content-creation.md # 内容创建 ├── api/ # API 文档 │ ├── README.md # API 概述 │ ├── authentication.md # 认证 │ └── endpoints/ # 接口详情 │ ├── users.md # 用户接口 │ └── projects.md # 项目接口 └── examples/ # 示例和教程 ├── README.md ├── basic-usage.md └── advanced-topics.md


### 文件命名规范

1. **使用小写字母**: 所有文件名使用小写字母
2. **使用连字符**: 单词之间使用连字符 `-` 分隔
3. **描述性命名**: 文件名应该清楚描述内容
4. **避免特殊字符**: 不使用空格、中文或特殊符号

**示例**:

✅ 推荐 getting-started.md api-reference.md user-management.md

❌ 避免 Getting Started.md API参考.md user_management.md


### README.md 文件

每个目录都应该包含 `README.md` 文件作为该目录的首页：

```markdown
# 目录标题

简要描述本目录的内容和用途。

## 内容概览

- [文档1](./file1.md) - 文档1的简要说明
- [文档2](./file2.md) - 文档2的简要说明
- [子目录](./subdirectory/) - 子目录的说明

## 快速导航

根据用户需求提供快速导航链接。

🎨 内容设计

文档结构模板

技术文档模板

# 文档标题

> 简要描述文档的目的和适用范围

## 概述

详细介绍文档的背景、目标和主要内容。

## 前置条件

列出使用本文档需要的前置知识或环境要求。

## 主要内容

### 第一部分

详细说明...

### 第二部分

详细说明...

## 示例

提供实际的使用示例。

## 常见问题

列出常见问题和解决方案。

## 相关资源

- [相关文档1](./related1.md)
- [相关文档2](./related2.md)

API 文档模板

# API 名称

## 接口描述

简要描述接口的功能和用途。

## 请求信息

- **请求方法**: GET/POST/PUT/DELETE
- **请求路径**: `/api/endpoint`
- **Content-Type**: `application/json`

## 请求参数

| 参数名 | 类型 | 必需 | 默认值 | 描述 |
|--------|------|------|--------|------|
| param1 | string | 是 | - | 参数描述 |
| param2 | number | 否 | 0 | 参数描述 |

## 响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": {
    // 响应数据
  }
}

使用示例

cURL 示例

curl -X GET "https://api.example.com/endpoint" \
  -H "Authorization: Bearer TOKEN"

JavaScript 示例

const response = await fetch('/api/endpoint', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer TOKEN'
  }
});

错误码

错误码说明解决方案
400请求参数错误检查参数格式
401未授权检查认证信息

### 用户指南模板
```markdown
# 功能名称

## 功能概述

简要介绍功能的作用和价值。

## 使用场景

描述什么情况下需要使用这个功能。

## 操作步骤

### 步骤 1: 准备工作

详细描述第一步需要做什么。

![截图说明](./images/step1.png)

### 步骤 2: 执行操作

详细描述第二步的操作。

![截图说明](./images/step2.png)

### 步骤 3: 验证结果

说明如何验证操作是否成功。

## 注意事项

- 重要提醒 1
- 重要提醒 2

## 常见问题

### 问题 1: 描述问题

**解决方案**: 详细的解决步骤

### 问题 2: 描述问题

**解决方案**: 详细的解决步骤

## 相关功能

- [相关功能1](./related-feature1.md)
- [相关功能2](./related-feature2.md)

🖼 图片和媒体

图片管理

  1. 存储位置: 将图片存储在 docs/.vuepress/public/images/ 目录下
  2. 命名规范: 使用描述性的文件名
  3. 格式选择:
    • 截图使用 PNG 格式
    • 照片使用 JPG 格式
    • 图标使用 SVG 格式

图片引用

# 绝对路径（推荐）
![图片描述](/images/screenshot.png)

# 相对路径
![图片描述](../images/screenshot.png)

# 带链接的图片
[![图片描述](/images/screenshot.png)](/images/screenshot-large.png)

图片优化

  1. 尺寸控制: 控制图片文件大小，建议单张图片不超过 500KB
  2. 分辨率: 使用适当的分辨率，通常 72-150 DPI 即可
  3. 压缩: 使用图片压缩工具减小文件大小

🔗 链接管理

内部链接

# 相对路径链接（推荐）
[链接文本](./other-file.md)
[链接文本](../other-dir/file.md)

# 锚点链接
[跳转到章节](#章节标题)

# 带查询参数的链接
[链接文本](./file.md#section)

外部链接

# 普通外部链接
[GitHub](https://github.com)

# 在新窗口打开
[GitHub](https://github.com){target="_blank"}

链接检查

定期检查文档中的链接是否有效：

  1. 内部链接: 确保引用的文件存在
  2. 外部链接: 定期验证外部链接的有效性
  3. 锚点链接: 确保锚点对应的标题存在

✅ 内容质量

写作原则

  1. 清晰简洁: 使用简单明了的语言
  2. 逻辑清晰: 按照逻辑顺序组织内容
  3. 用户导向: 从用户角度思考和组织内容
  4. 实用性: 提供可操作的具体步骤

质量检查清单

  • [ ] 标题层次清晰
  • [ ] 内容逻辑合理
  • [ ] 语言表达准确
  • [ ] 示例代码可运行
  • [ ] 图片清晰有意义
  • [ ] 链接有效可访问
  • [ ] 格式统一规范
  • [ ] 拼写语法正确

审核流程

  1. 自我审核: 作者完成初稿后进行自我检查
  2. 同行评审: 邀请同事进行内容审核
  3. 用户测试: 邀请目标用户测试文档可用性
  4. 持续改进: 根据反馈持续优化内容

🔄 版本管理

Git 工作流

  1. 创建分支: 为每个文档更新创建独立分支
  2. 提交变更: 使用清晰的提交信息
  3. 代码审查: 通过 Pull Request 进行审查
  4. 合并发布: 审查通过后合并到主分支

提交信息规范

# 新增文档
git commit -m "docs: 添加用户管理API文档"

# 更新文档
git commit -m "docs: 更新安装指南中的依赖版本"

# 修复文档
git commit -m "docs: 修复快速开始指南中的链接错误"

📚 相关资源