文档编制指南

本指南说明如何为 VEF 框架文档项目添加、编辑和翻译文档页面。

项目结构

vef-framework-go-docs/
├── docs/                          # 英文文档（源文件）
│   ├── getting-started/           # 快速开始分类
│   ├── guide/                     # 指南分类
│   ├── features/                  # 功能分类
│   ├── utilities/                 # 工具库分类
│   ├── modules/                   # 模块分类
│   └── reference/                 # 参考分类
├── i18n/
│   └── zh-Hans/
│       └── docusaurus-plugin-content-docs/
│           └── current/           # 中文文档（与 docs/ 镜像）
│               ├── getting-started/
│               ├── guide/
│               ├── features/
│               ├── utilities/
│               ├── modules/
│               └── reference/
├── docusaurus.config.ts           # Docusaurus 配置
└── sidebars.ts                    # 侧边栏配置（自动生成）

添加新文档页面

第一步：创建英文文档

在 docs/ 下的适当分类目录中创建新的 .md 文件：

---
sidebar_position: 5
---

# 页面标题

内容...

sidebar_position 前置元数据控制在分类侧边栏中的排序位置。

第二步：创建中文翻译

在 i18n/zh-Hans/docusaurus-plugin-content-docs/current/ 下创建相同相对路径的文件：

docs/guide/my-feature.md
→ i18n/zh-Hans/docusaurus-plugin-content-docs/current/guide/my-feature.md

中文文件必须有相同的文件名和 sidebar_position，但翻译所有内容包括标题。

第三步：验证

# 构建英文
pnpm build

# 构建中文
pnpm build -- --locale zh-Hans

# 或者启动开发服务器
pnpm start

添加新分类

第一步：创建分类目录

mkdir docs/my-category

第二步：添加分类元数据

创建 docs/my-category/_category_.json：

{
  "label": "My Category",
  "position": 10
}

第三步：添加中文分类元数据

创建 i18n/zh-Hans/docusaurus-plugin-content-docs/current/my-category/_category_.json：

{
  "label": "我的分类",
  "position": 10
}

编写规范

前置元数据

每个文档页面必须以前置元数据开头：

---
sidebar_position: 1    # 侧边栏位置（必需）
---

代码示例

• 使用带语法高亮的 Go 代码块：```go
• 代码示例应该是实用且可运行的
• 引用框架的实际 API，而不是理论用法
• 根据框架的源码和测试文件验证示例

交叉引用

使用相对路径链接到其他文档页面：

详见 [模型](./models)。
查询构造详见 [ORM SQL 构造器](../guide/orm-builder)。

表格

使用 Markdown 表格展示 API 参考等结构化数据：

| 方法 | 返回值 | 用途 |
| --- | --- | --- |
| `Scan(ctx)` | `error` | 将行扫描到模型 |

中英文一致性

• 英文和中文文件必须覆盖相同的主题
• 代码示例在两个版本中应保持一致
• 仅翻译文字内容，不翻译代码或技术标识符
• sidebar_position 值必须保持一致

侧边栏配置

本项目使用自动生成的侧边栏（sidebars.ts）：

const sidebars = {
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
};

这意味着：

• 侧边栏结构从目录层级自动推导
• 分类由包含 _category_.json 的目录创建
• 页面顺序由前置元数据中的 sidebar_position 控制
• 不需要手动侧边栏配置

开发流程

# 安装依赖
pnpm install

# 启动开发服务器（英文）
pnpm start

# 启动开发服务器（中文）
pnpm start -- --locale zh-Hans

# 构建生产版本
pnpm build

# 本地预览生产构建
pnpm serve

分类位置参考

位置	分类	标签（英文）	标签（中文）
1	getting-started	Getting Started	快速开始
2	guide	Guide	指南
3	features	Features	功能
9	utilities	Utilities	工具库
10	modules	Modules	模块
20	reference	Reference	参考

新页面清单

• 在 docs/ 中创建英文文件，设置正确的 sidebar_position
• 在 i18n/zh-Hans/.../current/ 中创建中文文件，保持相同结构
• 根据框架源码验证代码示例
• 添加到相关页面的交叉引用
• pnpm build 和 pnpm build -- --locale zh-Hans 均通过
• 开发服务器在两种语言下都能显示该页面