Merge pull request #35 from objectstack-ai/copilot/refactor-website-documentation

Author: hotlong

README.md

@@ -65,9 +65,9 @@ npx @objectdocs/cli init
 ```
 
 This will:
-- Create `content/package.json` with necessary scripts
-- Copy the site engine to `content/.objectdocs`
-- Install dependencies in `content/.objectdocs/node_modules`
+- Copy the site engine from `@objectdocs/site` to `content/.objectdocs`
+- Create `content/package.json` with scripts (`dev`, `build`, `start`)
+- Install dependencies in `content/.objectdocs`
 - Automatically add `content/.objectdocs` and `content/node_modules` to `.gitignore`
 - Keep your project root clean and unpolluted
 
@@ -99,38 +99,17 @@ cd content && npm run dev
 
 Visit http://localhost:7777 to see your site.
 
-### Option 2: New Standalone Project
+### Option 2: Use npm init
 
-For a new dedicated documentation project:
+For a quick start with automatic initialization:
 
 ```bash
 mkdir my-docs
 cd my-docs
-npm init -y
-npm install -D @objectdocs/cli
+npm init @objectdocs
 ```
 
-Add scripts to your root `package.json`:
-
-```json
-{
-  "scripts": {
-    "dev": "cd content && npm run dev",
-    "build": "cd content && npm run build",
-    "start": "cd content && npm run start"
-  }
-}
-```
-
-Initialize ObjectDocs:
-
-```bash
-npm run init
-# or
-npx objectdocs init
-```
-
-Then follow the same steps as Option 1 to add content.
+This runs the init command automatically. Then follow the same steps as Option 1 to add content.
 
 ## 🏗️ Project Structure
 
@@ -139,19 +118,24 @@ ObjectDocs enforces a clear directory structure to ensure maintainability at sca
 ```text
 .
 ├── content/               # [Data Layer] All documentation files
-│   ├── package.json       # npm scripts (dev, build, start)
-│   ├── .objectdocs/       # Site engine (auto-generated, gitignored)
-│   ├── docs.site.json     # Global settings (Nav, Logo, Branding)
+│   ├── package.json       # Scripts: dev, build, start (created by init)
+│   ├── .objectdocs/       # Site engine (copied from @objectdocs/site, gitignored)
+│   │   ├── node_modules/  # Dependencies (installed during init)
+│   │   ├── .next/         # Next.js build cache (development)
+│   │   └── out/           # Static build output (production)
+│   ├── docs.site.json     # Global config (Nav, Logo, Branding, i18n)
 │   └── docs/
-│       ├── meta.json      # Directory structure & sorting control
+│       ├── meta.json      # Directory structure & page order
 │       └── index.mdx      # Documentation content
+├── out/                   # Final build output (copied from content/.objectdocs/out)
 ├── package.json           # (Optional) Root project package.json
 └── ...
 ```
 
 **Key Points:**
 - All documentation-related files are in `content/`
-- `content/.objectdocs/` is auto-generated and gitignored
+- `content/.objectdocs/` contains the complete Next.js site engine (auto-generated, gitignored)
+- Build output: `content/.objectdocs/out` → copied to root `out/` directory
 - Your project root remains clean
 - Perfect for adding docs to any existing project
 
@@ -161,7 +145,7 @@ ObjectDocs is designed to be "Configuration as Code".
 
 ### Global Config (`content/docs.site.json`)
 
-Manage global navigation, branding, and feature flags:
+Manage global navigation, branding, i18n, and feature flags:
 
 ```json
 {
@@ -175,10 +159,19 @@ Manage global navigation, branding, and feature flags:
   "links": [
     { "text": "Guide", "url": "/docs" },
     { "text": "GitHub", "url": "https://github.com/objectstack-ai", "icon": "github" }
-  ]
+  ],
+  "i18n": {
+    "defaultLanguage": "en",
+    "languages": ["en", "zh-CN", "ja", "es", "fr", "de", "ko", "ru", "pt", "ar", "hi", "it", "tr", "vi"]
+  }
 }
 ```
 
+**Supported Features:**
+- 14 languages for internationalization
+- Automatic config watching and hot reload during development
+- Config is copied to `content/.objectdocs` before each build/dev command
+
 ### Sidebar Control (`content/**/meta.json`)
 
 Control the sidebar order and structure using local metadata files in each directory:

content/docs/getting-started/architecture.cn.mdx

@@ -30,29 +30,77 @@ ObjectDocs 建立在严格的 **关注点分离 (Separation of Concerns)** 理
 
 ## 目录结构
 
-一个标准的 ObjectDocs 项目结构如下：
+初始化后的标准 ObjectDocs 项目结构：
 
 ```text
 .
-├── content/               # [数据层] 原始内容
-│   ├── docs.site.json     # 全局设置 (导航, Logo, 品牌)
+├── content/               # [数据层] 所有文档文件
+│   ├── package.json       # 脚本: dev, build, start (由 init 创建)
+│   ├── .objectdocs/       # 站点引擎 (从 @objectdocs/site 复制, gitignored)
+│   │   ├── node_modules/  # 依赖 (初始化时安装)
+│   │   ├── .next/         # Next.js 构建缓存 (开发)
+│   │   └── out/           # 静态构建输出 (生产)
+│   ├── docs.site.json     # 全局配置 (导航, Logo, 品牌, i18n)
+│   ├── public/            # 静态资源 (在构建/开发时复制到站点)
 │   └── docs/
-│       ├── meta.json      # 目录结构 & 排序控制
+│       ├── meta.json      # 目录结构 & 页面顺序
 │       └── index.mdx      # 文档内容
-├── package.json
-└── public/                # 静态资源 (图片等)
+├── out/                   # 最终构建输出 (从 content/.objectdocs/out 复制)
+├── .gitignore             # 自动更新以排除 content/.objectdocs
+├── package.json           # (可选) 根目录 package.json
+└── ...
 ```
 
+**核心组件:**
+- **`content/.objectdocs/`**: 包含来自 `@objectdocs/site` 包的完整 Next.js 站点引擎
+- **`content/package.json`**: 由 init 命令创建，包含 dev/build/start 脚本
+- **构建流程**: `content/.objectdocs/out` → `out/` (根目录)
+- **环境**: 命令在 `content/.objectdocs` 内运行，`DOCS_DIR` 环境变量指向文档目录
+
 ## 数据流向
 
-1.  **构建时**: `@objectdocs/site` 读取 `content/` 下的所有 MDX 和 JSON 文件。
-2.  **解析**: Fumadocs 引擎解析元数据，构建导航树。
-3.  **渲染**: Next.js (App Router) 将内容渲染为 React Server Components。
-4.  **交互**: 客户端组件（如 `<Cards>`, `<Steps>`）在浏览器中激活。
+### 初始化流程
+1. **初始化命令**: `npx @objectdocs/cli init`
+2. **包复制**: 整个 `@objectdocs/site` 包 → `content/.objectdocs`
+3. **脚本创建**: 创建 `content/package.json` 并添加 dev/build/start 脚本
+4. **依赖安装**: 在 `content/.objectdocs` 中运行 `npm install`
+5. **Gitignore 更新**: 添加排除生成文件的规则
+
+### 开发流程
+1. **启动**: 运行 `cd content && npm run dev`
+2. **配置同步**: 复制 `docs.site.json` 和 `public/` 到 `content/.objectdocs`
+3. **环境**: 设置 `DOCS_DIR` 环境变量指向 `content/docs`
+4. **监听**: 监控 `docs.site.json` 的变化并自动重启
+5. **服务器**: Next.js 开发服务器在端口 7777 上运行（默认）
+
+### 构建流程
+1. **构建时**: 运行 `cd content && npm run build`
+2. **配置同步**: 复制 `docs.site.json` 和 `public/` 到 `content/.objectdocs`
+3. **环境**: 设置 `DOCS_DIR` 环境变量
+4. **MDX 解析**: Fumadocs 从 `DOCS_DIR` 读取所有 `.mdx` 文件
+5. **元数据**: 解析 `meta.json` 文件构建导航树
+6. **渲染**: Next.js App Router 将内容渲染为 React Server Components
+7. **输出**: 
+   - 静态模式: `content/.objectdocs/out` → `out/` (根目录)
+   - 动态模式: `content/.objectdocs/.next` → `.next/` (根目录)
+
+### 运行流程 (静态)
+1. **服务**: 从 `out/` 目录提供生产构建
+2. **资源**: 静态 HTML、CSS、JS 和图片
+3. **CDN**: 可以部署到 Vercel、Netlify 或任何静态托管
+
+### 运行流程 (动态)
+1. **启动**: 运行 `cd content && npm run start`
+2. **服务器**: 具有 ISR/SSR 功能的 Next.js 生产服务器
+3. **交互**: 客户端组件（如 `<Cards>`, `<Steps>`）在浏览器中激活
 
 ### 为什么这样设计？
 
 这种架构使得我们能够：
 
-*   **多产品支持**: 通过切换不同的 `content` 目录，可以在同一套代码库中支持多个产品的文档。
-*   **低代码集成**: 因为内容与 UI 分离，我们可以更容易地注入动态的低代码组件演示。
+*   **清晰分离**: 将文档内容与站点引擎完全分离
+*   **项目无关**: 可以在任何现有项目中添加文档而不污染根目录
+*   **版本控制**: 整个站点引擎都被 gitignore，只跟踪内容
+*   **多产品支持**: 通过切换不同的 `content` 目录，可以支持多个产品的文档
+*   **低代码集成**: 因为内容与 UI 分离，我们可以更容易地注入动态的低代码组件演示
+*   **轻松更新**: 通过重新运行 init 或更新 CLI 版本来更新站点引擎

content/docs/getting-started/architecture.mdx

@@ -30,29 +30,77 @@ Each documentation directory is self-contained. If you want to add a new section
 
 ## Directory Structure
 
-A standard ObjectDocs project structure looks like this:
+A standard ObjectDocs project structure after initialization:
 
 ```text
 .
-├── content/               # [Data Layer] Raw Content
-│   ├── docs.site.json     # Global settings (Nav, Logo, Branding)
+├── content/               # [Data Layer] All documentation files
+│   ├── package.json       # Scripts: dev, build, start (created by init)
+│   ├── .objectdocs/       # Site engine (copied from @objectdocs/site, gitignored)
+│   │   ├── node_modules/  # Dependencies (installed during init)
+│   │   ├── .next/         # Next.js build cache (development)
+│   │   └── out/           # Static build output (production)
+│   ├── docs.site.json     # Global config (Nav, Logo, Branding, i18n)
+│   ├── public/            # Static assets (copied to site during build/dev)
 │   └── docs/
-│       ├── meta.json      # Directory structure & sorting control
+│       ├── meta.json      # Directory structure & page order
 │       └── index.mdx      # Documentation content
-├── package.json
-└── public/                # Static assets (images, etc.)
+├── out/                   # Final build output (copied from content/.objectdocs/out)
+├── .gitignore             # Auto-updated to exclude content/.objectdocs
+├── package.json           # (Optional) Root project package.json
+└── ...
 ```
 
+**Key Components:**
+- **`content/.objectdocs/`**: Contains the complete Next.js site engine from `@objectdocs/site` package
+- **`content/package.json`**: Created by init command with dev/build/start scripts
+- **Build Flow**: `content/.objectdocs/out` → `out/` (root directory)
+- **Environment**: Commands run inside `content/.objectdocs` with `DOCS_DIR` env variable pointing to docs
+
 ## Data Flow
 
-1.  **Build Time**: `@objectdocs/site` reads all MDX and JSON files under `content/`.
-2.  **Parsing**: The Fumadocs engine parses metadata and builds the navigation tree.
-3.  **Rendering**: Next.js (App Router) renders content as React Server Components.
-4.  **Interaction**: Client components (like `<Cards>`, `<Steps>`) activate in the browser.
+### Initialization Flow
+1. **Init Command**: `npx @objectdocs/cli init`
+2. **Package Copy**: Entire `@objectdocs/site` package → `content/.objectdocs`
+3. **Script Creation**: `content/package.json` with dev/build/start scripts
+4. **Dependency Install**: `npm install` in `content/.objectdocs`
+5. **Gitignore Update**: Add exclusions for generated files
+
+### Development Flow
+1. **Start**: Run `cd content && npm run dev`
+2. **Config Sync**: Copy `docs.site.json` and `public/` to `content/.objectdocs`
+3. **Environment**: Set `DOCS_DIR` env variable to point to `content/docs`
+4. **Watch**: Monitor `docs.site.json` for changes and auto-restart
+5. **Server**: Next.js dev server runs on port 7777 (default)
+
+### Build Flow
+1. **Build Time**: Run `cd content && npm run build`
+2. **Config Sync**: Copy `docs.site.json` and `public/` to `content/.objectdocs`
+3. **Environment**: Set `DOCS_DIR` env variable
+4. **MDX Parsing**: Fumadocs reads all `.mdx` files from `DOCS_DIR`
+5. **Metadata**: Parse `meta.json` files to build navigation tree
+6. **Rendering**: Next.js App Router renders as React Server Components
+7. **Output**: 
+   - Static mode: `content/.objectdocs/out` → `out/` (root)
+   - Dynamic mode: `content/.objectdocs/.next` → `.next/` (root)
+
+### Runtime Flow (Static)
+1. **Serve**: Production build served from `out/` directory
+2. **Assets**: Static HTML, CSS, JS, and images
+3. **CDN**: Can be deployed to Vercel, Netlify, or any static host
+
+### Runtime Flow (Dynamic)
+1. **Start**: Run `cd content && npm run start`
+2. **Server**: Next.js production server with ISR/SSR capabilities
+3. **Interaction**: Client components (like `<Cards>`, `<Steps>`) hydrate in browser
 
 ### Why Design It This Way?
 
 This architecture allows us to:
 
-*   **Multi-Product Support**: By switching different `content` directories, multiple product documentations can be supported within the same codebase.
-*   **Low-Code Integration**: Since content is separated from UI, we can more easily inject dynamic low-code component demos.
+*   **Clean Separation**: Keep the documentation content completely separate from the site engine
+*   **Project Agnostic**: Add docs to any existing project without polluting the root directory
+*   **Version Control**: The entire site engine is gitignored, only content is tracked
+*   **Multi-Product Support**: By switching different `content` directories, multiple product documentations can be supported
+*   **Low-Code Integration**: Since content is separated from UI, we can more easily inject dynamic low-code component demos
+*   **Easy Updates**: Update the site engine by re-running init or updating the CLI version

content/docs/getting-started/configuration.cn.mdx

@@ -13,7 +13,7 @@ ObjectDocs 遵循 **配置即代码 (Configuration as Code)** 的原则。所有
 
 ### docs.site.json
 
-主配置文件位于 `content/docs.site.json`。该文件控制整个文档站点的全局设置。
+主配置文件位于 `content/docs.site.json`。该文件控制整个文档站点的全局设置，并在构建和开发期间自动同步到 `content/.objectdocs`。
 
 ```json
 {
@@ -27,17 +27,34 @@ ObjectDocs 遵循 **配置即代码 (Configuration as Code)** 的原则。所有
   "links": [
     { "text": "Guide", "url": "/docs" },
     { "text": "GitHub", "url": "https://github.com/objectstack-ai", "icon": "github" }
-  ]
+  ],
+  "i18n": {
+    "defaultLanguage": "en",
+    "languages": ["en", "zh-CN", "ja", "es", "fr", "de", "ko", "ru", "pt", "ar", "hi", "it", "tr", "vi"]
+  }
 }
 ```
 
+**工作原理:**
+- 存储在 `content/docs.site.json` (你的内容目录)
+- 在每次 build/dev 命令前复制到 `content/.objectdocs`
+- 开发时监听 - 变化会触发服务器自动重启
+- 支持 14 种语言的国际化
+
 ### 配置项说明
 
 | 属性 | 类型 | 说明 |
 | :--- | :--- | :--- |
 | `branding.name` | `string` | 站点名称，显示在导航栏左侧。 |
-| `branding.logo` | `object` | 站点 Log 图片路径，支持亮色/暗色模式。 |
+| `branding.logo` | `object` | 站点 Logo 图片路径，支持亮色/暗色模式。 |
 | `links` | `array` | 顶部导航栏链接列表。 |
+| `i18n.defaultLanguage` | `string` | 默认语言代码 (例如, "en", "zh-CN")。 |
+| `i18n.languages` | `array` | 支持的语言 (14种可选: en, zh-CN, ja, es, fr, de, ko, ru, pt, ar, hi, it, tr, vi)。 |
+
+**开发功能:**
+- 配置更改在 `npm run dev` 期间自动检测
+- `docs.site.json` 被修改时服务器会重启
+- 配置更新无需手动重启
 
 ## 目录与导航配置
 

content/docs/getting-started/configuration.mdx

@@ -13,7 +13,7 @@ ObjectDocs follows the **Configuration as Code** principle. All site settings ar
 
 ### docs.site.json
 
-The main configuration file is located at `content/docs.site.json`. This file controls the global settings for the entire documentation site.
+The main configuration file is located at `content/docs.site.json`. This file controls the global settings for the entire documentation site and is automatically synced to `content/.objectdocs` during build and development.
 
 ```json
 {
@@ -27,17 +27,34 @@ The main configuration file is located at `content/docs.site.json`. This file co
   "links": [
     { "text": "Guide", "url": "/docs" },
     { "text": "GitHub", "url": "https://github.com/objectstack-ai", "icon": "github" }
-  ]
+  ],
+  "i18n": {
+    "defaultLanguage": "en",
+    "languages": ["en", "zh-CN", "ja", "es", "fr", "de", "ko", "ru", "pt", "ar", "hi", "it", "tr", "vi"]
+  }
 }
 ```
 
+**How it Works:**
+- Stored in `content/docs.site.json` (your content directory)
+- Copied to `content/.objectdocs` before each build/dev command
+- Watched during development - changes trigger automatic server restart
+- Supports 14 languages for internationalization
+
 ### Configuration Options
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
 | `branding.name` | `string` | Site name, displayed on the left side of the navbar. |
 | `branding.logo` | `object` | Site logo image paths, supports light/dark mode. |
 | `links` | `array` | List of links in the top navigation bar. |
+| `i18n.defaultLanguage` | `string` | Default language code (e.g., "en", "zh-CN"). |
+| `i18n.languages` | `array` | Supported languages (14 available: en, zh-CN, ja, es, fr, de, ko, ru, pt, ar, hi, it, tr, vi). |
+
+**Development Features:**
+- Config changes are automatically detected during `npm run dev`
+- Server restarts when `docs.site.json` is modified
+- No manual restart needed for configuration updates
 
 ## Directory & Navigation Configuration