feat: update docs (#1440)

earayu · web-flow · commit 27685d873ac2 · 2026-02-03T19:04:19.000+08:00
diff --git a/docs/en-US/deployment/_category.yaml b/docs/en-US/deployment/_category.yaml
@@ -0,0 +1,2 @@
+title: Deployment
+position: 3
diff --git a/docs/en-US/deployment/build-docker-image.md b/docs/en-US/deployment/build-docker-image.md
diff --git a/docs/en-US/design/_category.yaml b/docs/en-US/design/_category.yaml
@@ -0,0 +1,2 @@
+title: Design
+position: 1
diff --git a/docs/en-US/design/architecture.md b/docs/en-US/design/architecture.md
@@ -2,6 +2,7 @@
 title: System Architecture
 description: ApeRAG Architecture Design and Core Components
 keywords: ApeRAG, Architecture, RAG, Knowledge Graph, LightRAG
+position: 1
 ---
 
 # ApeRAG System Architecture
diff --git a/docs/en-US/design/document_upload_design.md b/docs/en-US/design/document_upload_design.md
@@ -1,3 +1,8 @@
+---
+title: Document Upload Design
+position: 3
+---
+
 # ApeRAG Document Upload Architecture Design
 
 ## Overview
diff --git a/docs/en-US/design/graph_index_creation.md b/docs/en-US/design/graph_index_creation.md
@@ -2,6 +2,7 @@
 title: Graph Index Creation Process
 description: Complete process and core technologies for ApeRAG knowledge graph index construction
 keywords: Knowledge Graph, Graph Index, Entity Extraction, Relationship Extraction, Concurrency Optimization
+position: 2
 ---
 
 # Graph Index Creation Process
diff --git a/docs/en-US/development/_category.yaml b/docs/en-US/development/_category.yaml
@@ -0,0 +1,2 @@
+title: Development
+position: 4
diff --git a/docs/en-US/integration/_category.yaml b/docs/en-US/integration/_category.yaml
@@ -0,0 +1,2 @@
+title: Integration
+position: 2
diff --git a/docs/en-US/integration/dify.md b/docs/en-US/integration/dify.md
diff --git a/docs/en-US/integration/mcp-api.md b/docs/en-US/integration/mcp-api.md
diff --git a/docs/zh-CN/deployment/_category.yaml b/docs/zh-CN/deployment/_category.yaml
@@ -0,0 +1,2 @@
+title: 部署
+position: 3
diff --git a/docs/zh-CN/deployment/build-docker-image.md b/docs/zh-CN/deployment/build-docker-image.md
diff --git a/docs/zh-CN/design/_category.yaml b/docs/zh-CN/design/_category.yaml
@@ -0,0 +1,2 @@
+title: 设计
+position: 1
diff --git a/docs/zh-CN/design/architecture.md b/docs/zh-CN/design/architecture.md
@@ -2,6 +2,7 @@
 title: 系统架构
 description: ApeRAG 架构设计与核心组件详解
 keywords: ApeRAG, 架构, RAG, 知识图谱, LightRAG
+position: 1
 ---
 
 # ApeRAG 系统架构
diff --git a/docs/zh-CN/design/document_upload_design.md b/docs/zh-CN/design/document_upload_design.md
@@ -1,3 +1,8 @@
+---
+title: 文档上传设计
+position: 3
+---
+
 # ApeRAG 文档上传架构设计
 
 ## 概述
diff --git a/docs/zh-CN/design/graph_index_creation.md b/docs/zh-CN/design/graph_index_creation.md
@@ -2,6 +2,7 @@
 title: 图索引构建流程
 description: ApeRAG 知识图谱索引构建的完整流程与核心技术
 keywords: 知识图谱, Graph Index, 实体提取, 关系抽取, 并发优化
+position: 2
 ---
 
 # 图索引构建流程
diff --git a/docs/zh-CN/development/_category.yaml b/docs/zh-CN/development/_category.yaml
@@ -0,0 +1,2 @@
+title: 开发
+position: 4
diff --git a/docs/zh-CN/integration/_category.yaml b/docs/zh-CN/integration/_category.yaml
@@ -0,0 +1,2 @@
+title: 集成
+position: 2
diff --git a/docs/zh-CN/integration/dify.md b/docs/zh-CN/integration/dify.md
diff --git a/docs/zh-CN/integration/mcp-api.md b/docs/zh-CN/integration/mcp-api.md
diff --git a/scripts/sync-docs.py b/scripts/sync-docs.py
@@ -82,11 +82,15 @@
     # "en-US/design/chat_history_design.md",
     
     # English docs - Development
-    "en-US/development/dify.md",
-    "en-US/development/mcp-api.md",
-    "en-US/development/build-docker-image.md",
     "en-US/development/development-guide.md",
     
+    # English docs - Deployment
+    "en-US/deployment/build-docker-image.md",
+    
+    # English docs - Integration
+    "en-US/integration/dify.md",
+    "en-US/integration/mcp-api.md",
+    
     # English docs - Reference
     # "en-US/reference/how-to-configure-ollama.md",
     # "en-US/reference/HOW-TO-DEBUG.md",
@@ -98,11 +102,15 @@
     # "zh-CN/design/chat_history_design.md",
     
     # Chinese docs - Development
-    "zh-CN/development/dify.md",
-    "zh-CN/development/mcp-api.md",
-    "zh-CN/development/build-docker-image.md",
     "zh-CN/development/development-guide.md",
     
+    # Chinese docs - Deployment
+    "zh-CN/deployment/build-docker-image.md",
+    
+    # Chinese docs - Integration
+    "zh-CN/integration/dify.md",
+    "zh-CN/integration/mcp-api.md",
+    
     # Chinese docs - Reference
     # "zh-CN/reference/how-to-configure-ollama.md",
     # "zh-CN/reference/HOW-TO-DEBUG.md",
@@ -220,10 +228,27 @@ def main():
             print(f"❌ Error syncing {doc_path}: {e}")
             error_count += 1
     
+    # Sync _category.yaml files
+    print("\n🔄 Syncing _category.yaml files...\n")
+    category_count = 0
+    for locale in ["en-US", "zh-CN"]:
+        locale_dir = DOCS_ROOT / locale
+        if locale_dir.exists():
+            for category_dir in locale_dir.iterdir():
+                if category_dir.is_dir():
+                    category_file = category_dir / "_category.yaml"
+                    if category_file.exists():
+                        dest_file = WEB_DOCS_ROOT / locale / category_dir.name / "_category.yaml"
+                        dest_file.parent.mkdir(parents=True, exist_ok=True)
+                        shutil.copy2(category_file, dest_file)
+                        print(f"✅ Synced: {category_file} -> {dest_file}")
+                        category_count += 1
+    
     # Summary
     print(f"\n{'='*60}")
     print(f"📊 Summary:")
     print(f"   ✅ Synced: {synced_count} documents")
+    print(f"   ✅ Synced: {category_count} category files")
     if error_count > 0:
         print(f"   ❌ Errors: {error_count}")
     print(f"{'='*60}\n")
diff --git a/web/docs/en-US/deployment/_category.yaml b/web/docs/en-US/deployment/_category.yaml
@@ -0,0 +1,2 @@
+title: Deployment
+position: 3
diff --git a/web/docs/en-US/deployment/build-docker-image.md b/web/docs/en-US/deployment/build-docker-image.md
diff --git a/web/docs/en-US/design/_category.yaml b/web/docs/en-US/design/_category.yaml
@@ -1 +1,2 @@
 title: Design
+position: 1
diff --git a/web/docs/en-US/design/architecture.md b/web/docs/en-US/design/architecture.md
@@ -2,6 +2,7 @@
 title: System Architecture
 description: ApeRAG Architecture Design and Core Components
 keywords: ApeRAG, Architecture, RAG, Knowledge Graph, LightRAG
+position: 1
 ---
 
 # ApeRAG System Architecture
diff --git a/web/docs/en-US/design/document_upload_design.md b/web/docs/en-US/design/document_upload_design.md
@@ -1,3 +1,7 @@
+---
+title: Document Upload Design
+---
+
 # ApeRAG Document Upload Architecture Design
 
 ## Overview
diff --git a/web/docs/en-US/design/graph_index_creation.md b/web/docs/en-US/design/graph_index_creation.md
@@ -2,6 +2,7 @@
 title: Graph Index Creation Process
 description: Complete process and core technologies for ApeRAG knowledge graph index construction
 keywords: Knowledge Graph, Graph Index, Entity Extraction, Relationship Extraction, Concurrency Optimization
+position: 2
 ---
 
 # Graph Index Creation Process
diff --git a/web/docs/en-US/development/_category.yaml b/web/docs/en-US/development/_category.yaml
@@ -1 +1,2 @@
 title: Development
+position: 4
diff --git a/web/docs/en-US/integration/_category.yaml b/web/docs/en-US/integration/_category.yaml
@@ -0,0 +1,2 @@
+title: Integration
+position: 2
diff --git a/web/docs/en-US/integration/dify.md b/web/docs/en-US/integration/dify.md
diff --git a/web/docs/en-US/integration/mcp-api.md b/web/docs/en-US/integration/mcp-api.md
diff --git a/web/docs/zh-CN/deployment/_category.yaml b/web/docs/zh-CN/deployment/_category.yaml
@@ -0,0 +1,2 @@
+title: 部署
+position: 3
diff --git a/web/docs/zh-CN/deployment/build-docker-image.md b/web/docs/zh-CN/deployment/build-docker-image.md
diff --git a/web/docs/zh-CN/design/_category.yaml b/web/docs/zh-CN/design/_category.yaml
@@ -1 +1,2 @@
 title: 设计
+position: 1
diff --git a/web/docs/zh-CN/design/architecture.md b/web/docs/zh-CN/design/architecture.md
@@ -2,6 +2,7 @@
 title: 系统架构
 description: ApeRAG 架构设计与核心组件详解
 keywords: ApeRAG, 架构, RAG, 知识图谱, LightRAG
+position: 1
 ---
 
 # ApeRAG 系统架构
diff --git a/web/docs/zh-CN/design/document_upload_design.md b/web/docs/zh-CN/design/document_upload_design.md
@@ -1,3 +1,8 @@
+---
+title: 文档上传设计
+position: 3
+---
+
 # ApeRAG 文档上传架构设计
 
 ## 概述
diff --git a/web/docs/zh-CN/design/graph_index_creation.md b/web/docs/zh-CN/design/graph_index_creation.md
@@ -2,6 +2,7 @@
 title: 图索引构建流程
 description: ApeRAG 知识图谱索引构建的完整流程与核心技术
 keywords: 知识图谱, Graph Index, 实体提取, 关系抽取, 并发优化
+position: 2
 ---
 
 # 图索引构建流程
diff --git a/web/docs/zh-CN/development/_category.yaml b/web/docs/zh-CN/development/_category.yaml
@@ -1 +1,2 @@
 title: 开发
+position: 4
diff --git a/web/docs/zh-CN/integration/_category.yaml b/web/docs/zh-CN/integration/_category.yaml
@@ -0,0 +1,2 @@
+title: 集成
+position: 2
diff --git a/web/docs/zh-CN/integration/dify.md b/web/docs/zh-CN/integration/dify.md
diff --git a/web/docs/zh-CN/integration/mcp-api.md b/web/docs/zh-CN/integration/mcp-api.md
diff --git a/web/src/lib/docs.ts b/web/src/lib/docs.ts
@@ -38,12 +38,14 @@ export type DocsSideBar = {
   href?: string;
   children?: DocsSideBar[];
   collapsed?: boolean;
+  position?: number;
 };
 
 type FileMetadata = {
   title?: string;
   description?: string;
   keywords?: string;
+  position?: number;
 };
 const readFile = async (filepath: string, folder: string) => {
   const isExists = fs.existsSync(filepath);
@@ -61,6 +63,7 @@ const readFile = async (filepath: string, folder: string) => {
     description: metadata.description,
     type: 'file',
     href: getHref(filepath),
+    position: metadata.position ?? 999,
   };
   return item;
 };
@@ -94,6 +97,7 @@ const readFolder = async (folderDir: string, parent: string) => {
     title: metadata.title || getTitleByFilename(parent),
     type: parentIsDocsRoot || childrenIsParent ? 'group' : 'folder',
     children,
+    position: metadata.position ?? 999,
   };
 
   return item;
@@ -125,7 +129,9 @@ export async function getDocsSideBar(dir?: string): Promise<DocsSideBar[]> {
     }),
   );
 
-  return result.filter((item) => item !== undefined);
+  return result
+    .filter((item) => item !== undefined)
+    .sort((a, b) => (a.position ?? 999) - (b.position ?? 999));
 }
 
 export async function getIndexPageUrl(
