fix: right document hyperlink navigation; separate Chinese and English docs; add history contributors

* doc: add github page

* test(doc): add test for doc page building

* fix: github page

* fix: right document hyperlink navigation; separate Chinese and English docs

* doc: add history contributors

Author: ActivePeter

.github/workflows/docs-pages.yml

@@ -9,7 +9,8 @@ on:
     # Republish when doc or homepage inputs change.
     paths:
       - ".github/workflows/docs-pages.yml"
-      - "fluxon_doc/**"
+      - "fluxon_doc_cn/**"
+      - "fluxon_doc_en/**"
       - "README.md"
       - "README_CN.md"
       - "pics/**"

AGENTS.md

@@ -9,7 +9,7 @@ Keep this document concise.
 ## Doc Site
 - Use Quartz for the doc site. Treat Quartz as cached build tooling under `.cached`; do not vendor it as a git submodule.
 - Publish the repo-root `README.md` as the doc-site homepage.
-- Do not add index `README.md` files under `fluxon_doc/**`; use real content pages and generated navigation instead.
+- Do not add index `README.md` files under `fluxon_doc_cn/**` or `fluxon_doc_en/**`; use real content pages and generated navigation instead.
 - GitHub Pages output must work under a project subpath such as `/Fluxon/`; avoid root-only internal links.
 - In the doc explorer, keep the left tree expanded, include `首页`, and place `roadmap` immediately after `首页`.
 

README.md

@@ -10,7 +10,7 @@
 [![Latest](https://img.shields.io/badge/Latest-v0.2.1-f28500)](./fluxon_release)
 [![Interfaces](https://img.shields.io/badge/Interfaces-KV%2FRPC%20%7C%20MQ%20%7C%20FS-1f6feb)](#interface-capabilities)
 
-[English](./README.md) | [中文](./README_CN.md) | [User Docs](https://tele-ai.github.io/Fluxon/user_doc/)
+[English](./README.md) | [中文](./README_CN.md) | [Docs](./README.md) | [中文文档](./README_CN.md)
 
 </div>
 
@@ -33,7 +33,7 @@ Fluxon is a high-performance distributed communication and caching substrate for
 
 ![](./pics/topology_ui.png)
 
-For more usage details, see [User Docs](./fluxon_doc/user_doc/).
+For more usage details, see [User Docs](./fluxon_doc_en/user_doc/).
 
 ## Interface Capabilities
 
@@ -107,7 +107,7 @@ The benchmark results show that small-file reads and large-file writes are alrea
 
 ## Quick Start
 
-Quick Start is the shortest path to try Fluxon. For formal installation, deployment, and operations, see [User Docs](./fluxon_doc/user_doc/).
+Quick Start is the shortest path to try Fluxon. For formal installation, deployment, and operations, see [User Docs](./fluxon_doc_en/user_doc/).
 
 ### KV Quick Start
 
@@ -132,15 +132,15 @@ del demo:hello
 
 Runtime view:
 
-![](./fluxon_doc/pics/quickstart_kv.png)
+![](./pics/quickstart_kv.png)
 
 Open the printed link to view the KV Web UI:
 
-![](./fluxon_doc/pics/quickstart_kvui.gif)
+![](./pics/quickstart_kvui.gif)
 
 Related interface docs:
 
-- [KV and RPC Interface](<./fluxon_doc/user_doc/用户 - 3 - KV-RPC接口.md>)
+- [KV and RPC Interface](<./fluxon_doc_en/user_doc/User - 3 - KV and RPC Interface.md>)
 
 ### MQ Quick Start
 
@@ -167,11 +167,11 @@ Startup also prints the `MQ Web UI` address.
 
 Runtime view:
 
-![](./fluxon_doc/pics/quickstart_mq.png)
+![](./pics/quickstart_mq.png)
 
 Related interface docs:
 
-- [MQ Interface](<./fluxon_doc/user_doc/用户 - 4 - MQ接口.md>)
+- [MQ Interface](<./fluxon_doc_en/user_doc/User - 4 - MQ Interface.md>)
 
 ### FS Quick Start
 
@@ -201,15 +201,15 @@ FS Quick Start additionally prints:
 
 Runtime view:
 
-![](./fluxon_doc/pics/quickstart_fs.png)
+![](./pics/quickstart_fs.png)
 
 Open the printed link to view the FS Web UI:
 
-![](./fluxon_doc/pics/quickstart_fsui.gif)
+![](./pics/quickstart_fsui.gif)
 
 Related interface docs:
 
-- [FS Interface](<./fluxon_doc/user_doc/用户 - 5 - FS接口.md>)
+- [FS Interface](<./fluxon_doc_en/user_doc/User - 5 - FS Interface.md>)
 
 ## Repository Structure
 
@@ -225,9 +225,55 @@ Related interface docs:
 
 Thank you for your contribution. Start with the local developer docs:
 
-- [Developer Docs](./fluxon_doc/dev_doc/)
-- [Developer - 1 - Package core install artifacts](<./fluxon_doc/dev_doc/开发者 - 1 - 打包核心安装包.md>)
-- [Developer - 2 - Package middleware and images](<./fluxon_doc/dev_doc/开发者 - 2 - 打包中间件和镜像.md>)
+- [Developer Docs](./fluxon_doc_en/dev_doc/)
+- [Developer - 1 - Package core install artifacts](<./fluxon_doc_en/dev_doc/Developer - 1 - Package Core Install Artifacts.md>)
+- [Developer - 2 - Package middleware and images](<./fluxon_doc_en/dev_doc/Developer - 2 - Package Middleware and Images.md>)
+
+## Contributors
+
+<a href="https://github.com/Tele-AI/fluxon/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Tele-AI/fluxon" />
+</a>
+
+Some earlier contribution records are no longer fully reflected in the current commit history. Historical highlights:
+
+<div>
+  <a href="https://github.com/yxrxy" title="yxrxy - FluxonFS implementation and optimization" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/yxrxy.png?size=64" width="64" height="64" alt="yxrxy" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">yxrxy</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">FluxonFS implementation and optimization</div>
+  </a>
+  <a href="https://github.com/zTz01" title="zTz01 - KVCache optimization" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/zTz01.png?size=64" width="64" height="64" alt="zTz01" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">zTz01</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">KVCache optimization</div>
+  </a>
+  <a href="https://github.com/pakkah" title="pakkah - RDMA support, VLM exploration" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/pakkah.png?size=64" width="64" height="64" alt="pakkah" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">pakkah</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">RDMA support, VLM exploration</div>
+  </a>
+  <a href="https://github.com/mumupika" title="mumupika - Initial MQ implementation" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/mumupika.png?size=64" width="64" height="64" alt="mumupika" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">mumupika</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">Initial MQ implementation</div>
+  </a>
+  <a href="https://github.com/maplestarplayl" title="maplestarplayl - IPC integration, SPDK integration" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/maplestarplayl.png?size=64" width="64" height="64" alt="maplestarplayl" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">maplestarplayl</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">IPC integration, SPDK integration</div>
+  </a>
+  <a href="https://github.com/RuileLu" title="RuileLu - KV lease support" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/RuileLu.png?size=64" width="64" height="64" alt="RuileLu" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">RuileLu</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">KV lease support</div>
+  </a>
+  <a href="https://github.com/Summage" title="Summage - Initial KV architecture optimization" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/Summage.png?size=64" width="64" height="64" alt="Summage" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">Summage</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">Initial KV architecture optimization</div>
+  </a>
+</div>
 
 ## License
 

README_CN.md

@@ -14,7 +14,7 @@ Fluxon 是一套面向世界模型与其他 AI-native 场景训推系统的高
 [![Latest](https://img.shields.io/badge/Latest-v0.2.1-f28500)](./fluxon_release)
 [![Interfaces](https://img.shields.io/badge/Interfaces-KV%2FRPC%20%7C%20MQ%20%7C%20FS-1f6feb)](#接口能力)
 
-[中文](./README_CN.md) | [English](./README.md) | [用户文档](https://tele-ai.github.io/Fluxon/user_doc/)
+[中文](./README_CN.md) | [English](./README.md) | [用户文档](./README_CN.md) | [English Docs](./README.md)
 
 </div>
 
@@ -35,7 +35,7 @@ Fluxon 是一套面向世界模型与其他 AI-native 场景训推系统的高
 
 ![](./pics/topology_ui.png)
 
-更多使用说明见 [用户文档](./fluxon_doc/user_doc/)。
+更多使用说明见 [用户文档](./fluxon_doc_cn/user_doc/)。
 
 ## 接口能力
 
@@ -109,7 +109,7 @@ benchmark 显示，小文件读和大文件写已显著领先 `Alluxio`，大文
 
 ## 快速开始
 
-Quick Start 用于最短路径体验；正式安装、部署和运维入口见 [用户文档](./fluxon_doc/user_doc/)。
+Quick Start 用于最短路径体验；正式安装、部署和运维入口见 [用户文档](./fluxon_doc_cn/user_doc/)。
 
 ### KV 快速开始
 
@@ -134,15 +134,15 @@ del demo:hello
 
 运行效果：
 
-![](./fluxon_doc/pics/quickstart_kv.png)
+![](./pics/quickstart_kv.png)
 
 点开提示链接可以查看 KV Web UI：
 
-![](./fluxon_doc/pics/quickstart_kvui.gif)
+![](./pics/quickstart_kvui.gif)
 
 对应接口文档：
 
-- [KV 和 RPC 接口](<./fluxon_doc/user_doc/用户 - 3 - KV-RPC接口.md>)
+- [KV 和 RPC 接口](<./fluxon_doc_cn/user_doc/用户 - 3 - KV-RPC接口.md>)
 
 ### MQ 快速开始
 
@@ -169,11 +169,11 @@ exit
 
 运行效果：
 
-![](./fluxon_doc/pics/quickstart_mq.png)
+![](./pics/quickstart_mq.png)
 
 对应接口文档：
 
-- [MQ 接口](<./fluxon_doc/user_doc/用户 - 4 - MQ接口.md>)
+- [MQ 接口](<./fluxon_doc_cn/user_doc/用户 - 4 - MQ接口.md>)
 
 ### FS 快速开始
 
@@ -203,15 +203,15 @@ FS Quick Start 会额外打印：
 
 运行效果：
 
-![](./fluxon_doc/pics/quickstart_fs.png)
+![](./pics/quickstart_fs.png)
 
 点开提示链接可以查看 FS Web UI：
 
-![](./fluxon_doc/pics/quickstart_fsui.gif)
+![](./pics/quickstart_fsui.gif)
 
 对应接口文档：
 
-- [FS 接口](<./fluxon_doc/user_doc/用户 - 5 - FS接口.md>)
+- [FS 接口](<./fluxon_doc_cn/user_doc/用户 - 5 - FS接口.md>)
 
 ## 项目结构
 
@@ -227,9 +227,55 @@ FS Quick Start 会额外打印：
 
 感谢你的贡献。建议先阅读本地开发者文档：
 
-- [开发者文档总入口](./fluxon_doc/dev_doc/)
-- [开发者 - 1 - 打包核心安装包](<./fluxon_doc/dev_doc/开发者 - 1 - 打包核心安装包.md>)
-- [开发者 - 2 - 打包中间件和镜像](<./fluxon_doc/dev_doc/开发者 - 2 - 打包中间件和镜像.md>)
+- [开发者文档总入口](./fluxon_doc_cn/dev_doc/)
+- [开发者 - 1 - 打包核心安装包](<./fluxon_doc_cn/dev_doc/开发者 - 1 - 打包核心安装包.md>)
+- [开发者 - 2 - 打包中间件和镜像](<./fluxon_doc_cn/dev_doc/开发者 - 2 - 打包中间件和镜像.md>)
+
+## Contributors
+
+<a href="https://github.com/Tele-AI/fluxon/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Tele-AI/fluxon" />
+</a>
+
+部分更早期的贡献记录已经无法从当前 commit 历史里完整反映，这里补充说明：
+
+<div>
+  <a href="https://github.com/yxrxy" title="yxrxy - FluxonFS 实现和优化" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/yxrxy.png?size=64" width="64" height="64" alt="yxrxy" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">yxrxy</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">FluxonFS 实现和优化</div>
+  </a>
+  <a href="https://github.com/zTz01" title="zTz01 - KVCache 优化" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/zTz01.png?size=64" width="64" height="64" alt="zTz01" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">zTz01</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">KVCache 优化</div>
+  </a>
+  <a href="https://github.com/pakkah" title="pakkah - RDMA 支持、VLM 探索" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/pakkah.png?size=64" width="64" height="64" alt="pakkah" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">pakkah</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">RDMA 支持、VLM 探索</div>
+  </a>
+  <a href="https://github.com/mumupika" title="mumupika - 初始 MQ 版本实现" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/mumupika.png?size=64" width="64" height="64" alt="mumupika" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">mumupika</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">初始 MQ 版本实现</div>
+  </a>
+  <a href="https://github.com/maplestarplayl" title="maplestarplayl - IPC 接入、SPDK 接入" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/maplestarplayl.png?size=64" width="64" height="64" alt="maplestarplayl" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">maplestarplayl</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">IPC 接入、SPDK 接入</div>
+  </a>
+  <a href="https://github.com/RuileLu" title="RuileLu - KV lease 功能支持" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/RuileLu.png?size=64" width="64" height="64" alt="RuileLu" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">RuileLu</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">KV lease 功能支持</div>
+  </a>
+  <a href="https://github.com/Summage" title="Summage - 初始 KV 架构设计优化" style="display: inline-block; width: 128px; margin: 0 10px 14px 0; vertical-align: top; text-align: center; text-decoration: none; color: inherit; font-size: 0;">
+    <img src="https://github.com/Summage.png?size=64" width="64" height="64" alt="Summage" style="display: block; margin: 0 auto 8px; border-radius: 50%;" />
+    <div style="font-size: 0.95rem; font-weight: 600; line-height: 1.25;">Summage</div>
+    <div style="font-size: 0.8rem; line-height: 1.35;">初始 KV 架构设计优化</div>
+  </a>
+</div>
 
 ## 许可证
 

deployment/tests/test_build_doc_site_contract.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+import unittest
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SCRIPT_PATH = REPO_ROOT / "scripts" / "build_doc_site.py"
+
+
+def _load_module():
+    spec = importlib.util.spec_from_file_location("fluxon_build_doc_site_contract", SCRIPT_PATH)
+    assert spec is not None and spec.loader is not None
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+_DOC_SITE = _load_module()
+
+
+class TestBuildDocSiteContract(unittest.TestCase):
+    def test_counterpart_routes_cover_home_and_doc_pairs(self) -> None:
+        routes = _DOC_SITE.LANGUAGE_COUNTERPART_ROUTES
+        self.assertEqual(routes["/"], "/cn")
+        self.assertEqual(routes["/cn"], "/")
+        self.assertEqual(
+            routes["/user_doc/User---0---Installation"],
+            "/cn/user_doc/用户---0---安装",
+        )
+        self.assertEqual(
+            routes["/cn/dev_doc/开发者---2---打包中间件和镜像"],
+            "/dev_doc/Developer---2---Package-Middleware-and-Images",
+        )
+
+    def test_rewrite_homepage_target_path_for_english_home(self) -> None:
+        self.assertEqual(
+            _DOC_SITE.rewrite_homepage_target_path("./README_CN.md", language="en"),
+            "./cn/",
+        )
+        self.assertEqual(
+            _DOC_SITE.rewrite_homepage_target_path("./fluxon_doc_en/user_doc/", language="en"),
+            "./user_doc/",
+        )
+        self.assertEqual(
+            _DOC_SITE.rewrite_homepage_target_path("./fluxon_doc_cn/user_doc/", language="en"),
+            "./cn/user_doc/",
+        )
+
+    def test_rewrite_homepage_target_path_for_chinese_home(self) -> None:
+        self.assertEqual(
+            _DOC_SITE.rewrite_homepage_target_path("./README.md", language="cn"),
+            "../",
+        )
+        self.assertEqual(
+            _DOC_SITE.rewrite_homepage_target_path("./fluxon_doc_cn/user_doc/", language="cn"),
+            "./user_doc/",
+        )
+        self.assertEqual(
+            _DOC_SITE.rewrite_homepage_target_path("./fluxon_rs/rust-toolchain.toml", language="cn"),
+            "../fluxon_rs/rust-toolchain.toml",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

examples/fluxon_quick_start/README.md

@@ -46,7 +46,7 @@ Quick start launches the minimum runnable environment for each mode:
 Quick start is only for fast bring-up and interaction:
 
 - Formal service-plane docs:
-  - `fluxon_doc/user_doc/用户 - 2 - 服务平面.md`
+  - `fluxon_doc_en/user_doc/User - 2 - Service Plane.md`
 - Formal business interface docs:
   - KV, MQ, and FS user docs
 
@@ -176,10 +176,10 @@ Go back to the formal service-plane and interface paths if you need to:
 Document entrypoints:
 
 - Service plane:
-  - `fluxon_doc/user_doc/用户 - 2 - 服务平面.md`
+  - `fluxon_doc_en/user_doc/User - 2 - Service Plane.md`
 - KV and node-to-node RPC:
-  - `fluxon_doc/user_doc/用户 - 3 - KV-RPC接口.md`
+  - `fluxon_doc_en/user_doc/User - 3 - KV and RPC Interface.md`
 - MQ:
-  - `fluxon_doc/user_doc/用户 - 4 - MQ接口.md`
+  - `fluxon_doc_en/user_doc/User - 4 - MQ Interface.md`
 - FS:
-  - `fluxon_doc/user_doc/用户 - 5 - FS接口.md`
+  - `fluxon_doc_en/user_doc/User - 5 - FS Interface.md`