Documentation Guide

This guide explains how to add, edit, and translate documentation pages for the VEF Framework documentation project.

Project Structure

vef-framework-go-docs/
├── docs/                          # English documentation (source of truth)
│   ├── getting-started/           # Getting Started category
│   ├── guide/                     # Guide category
│   ├── features/                  # Features category
│   ├── utilities/                 # Utilities category
│   ├── modules/                   # Modules category
│   └── reference/                 # Reference category
├── i18n/
│   └── zh-Hans/
│       └── docusaurus-plugin-content-docs/
│           └── current/           # Chinese documentation (mirrors docs/)
│               ├── getting-started/
│               ├── guide/
│               ├── features/
│               ├── utilities/
│               ├── modules/
│               └── reference/
├── docusaurus.config.ts           # Docusaurus configuration
└── sidebars.ts                    # Sidebar configuration (autogenerated)

Adding a New Documentation Page

Step 1: Create the English Document

Create a new .md file in the appropriate category directory under docs/:

---
sidebar_position: 5
---

# Page Title

Your content here...

The sidebar_position frontmatter controls the order within the category sidebar.

Step 2: Create the Chinese Translation

Create a matching file at the same relative path under 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

The Chinese file must have the same filename and sidebar_position, but translate all content including the title.

Step 3: Verify

# Build English
pnpm build

# Build Chinese
pnpm build -- --locale zh-Hans

# Or run dev server
pnpm start

Adding a New Category

Step 1: Create the Category Directory

mkdir docs/my-category

Step 2: Add Category Metadata

Create docs/my-category/_category_.json:

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

Step 3: Add Chinese Category Metadata

Create i18n/zh-Hans/docusaurus-plugin-content-docs/current/my-category/_category_.json:

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

Writing Guidelines

Frontmatter

Every documentation page must start with frontmatter:

---
sidebar_position: 1    # Position in sidebar (required)
---

Code Examples

• Use Go code blocks with syntax highlighting: ```go
• Code examples should be practical and runnable
• Reference the framework's actual API, not theoretical usage
• Verify examples against the framework's source code and test files

Cross-References

Link to other documentation pages using relative paths:

See [Models](./models) for details.
See [ORM SQL Builder](../guide/orm-builder) for query construction.

Tables

Use markdown tables for structured data like API references:

| Method | Returns | Purpose |
| --- | --- | --- |
| `Scan(ctx)` | `error` | Scan rows into model |

Bilingual Consistency

• Both English and Chinese files must cover the same topics
• Code examples should be identical in both versions
• Only translate prose, not code or technical identifiers
• Keep sidebar_position values identical

Sidebar Configuration

The project uses autogenerated sidebars (sidebars.ts):

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

This means:

• Sidebar structure is derived from the directory hierarchy
• Categories are created from directories with _category_.json
• Page order is controlled by sidebar_position in frontmatter
• No manual sidebar configuration is needed

Development Workflow

# Install dependencies
pnpm install

# Start dev server (English)
pnpm start

# Start dev server (Chinese)
pnpm start -- --locale zh-Hans

# Build for production
pnpm build

# Serve production build locally
pnpm serve

Category Position Reference

Position	Category	Label (EN)	Label (ZH)
1	getting-started	Getting Started	快速开始
2	guide	Guide	指南
3	features	Features	功能
9	utilities	Utilities	工具库
10	modules	Modules	模块
20	reference	Reference	参考

Checklist for New Pages

• English file created in docs/ with correct sidebar_position
• Chinese file created in i18n/zh-Hans/.../current/ with matching structure
• Code examples verified against framework source code
• Cross-references to related pages added
• Both pnpm build and pnpm build -- --locale zh-Hans pass
• Dev server shows the page in both locales