# Nargo Document 架构设计
## 1. 整体架构
Nargo Document (nargo-document) 是一个基于 Nargo 编译器链的文档生成和管理工具，用于替代 VitePress，为 Nargo 项目提供完整的文档解决方案。
### 1.1 核心组件
```
nargo-document/
├── src/
│ ├── main.rs # 主入口
│ ├── cli/ # 命令行接口
│ ├── config/ # 配置系统
│ ├── generator/ # 文档生成器
│ │ ├── markdown/ # Markdown 处理
│ │ ├── html/ # HTML 生成
│ │ └── static/ # 静态资源处理
│ ├── server/ # 开发服务器
│ ├── theme/ # 主题系统
│ └── utils/ # 工具函数
├── Cargo.toml # 依赖配置
└── README.md # 说明文档
```
### 1.2 集成关系
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ nargo-document │────>│ nargo-tools │────>│ nargo-compiler │
│ │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ nargo-bundler │<────│ nargo-parser │<────│ nargo-ssr │
│ │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
## 2. 核心模块设计
### 2.1 命令行接口 (CLI)
- **功能**：提供 `nargo doc` 命令，支持构建和开发服务器模式
- **命令**：
- `nargo doc build` - 构建静态文档
- `nargo doc dev` - 启动开发服务器
- `nargo doc serve` - 预览构建的文档
- **参数**：
- `--config` - 指定配置文件路径
- `--outDir` - 指定输出目录
- `--port` - 指定开发服务器端口
### 2.2 配置系统
- **配置文件**：支持 `nargodoc.config.ts` 或 `nargodoc.config.js`
- **配置项**：
- `title` - 文档标题
- `description` - 文档描述
- `locales` - 多语言配置
- `themeConfig` - 主题配置（导航、侧边栏等）
- `markdown` - Markdown 配置
- `build` - 构建配置
- **配置解析**：使用 TypeScript/JavaScript 配置文件，支持类型提示
### 2.3 文档生成器
#### 2.3.1 Markdown 处理器
- **功能**：解析 Markdown 文件，支持扩展语法
- **特性**：
- 语法高亮
- Mermaid 图表
- 代码块处理
- 数学公式支持
- **实现**：利用现有的解析器，扩展支持文档特定功能
#### 2.3.2 HTML 生成器
- **功能**：将 Markdown 转换为 HTML 页面
- **特性**：
- 主题应用
- 导航生成
- 侧边栏生成
- 多语言支持
- **实现**：基于 nargo-bundler 的能力，生成静态 HTML
#### 2.3.3 静态资源处理
- **功能**：处理图片、CSS、JS 等静态资源
- **特性**：
- 资源优化
- 路径处理
- 缓存控制
- **实现**：利用 nargo-bundler 的资源处理能力
### 2.4 开发服务器
- **功能**：提供热模块替换（HMR）的开发环境
- **特性**：
- 实时预览
- 文件监听
- 自动刷新
- 错误提示
- **实现**：基于 Nargo 现有的 HMR 实现，扩展支持文档场景
### 2.5 主题系统
- **功能**：提供可定制的文档主题
- **特性**：
- 默认主题
- 自定义主题
- 样式覆盖
- 布局定制
- **实现**：基于 CSS 变量和模板系统
### 2.6 工具函数
- **功能**：提供通用工具函数
- **模块**：
- 文件操作
- 路径处理
- 日志系统
- 错误处理
- **实现**：复用 Nargo 现有的工具函数
## 3. 数据流设计
### 3.1 构建流程
1. **配置解析**：读取并解析配置文件
2. **文件扫描**：查找所有 Markdown 和 Nargo 文件
3. **内容处理**：
- 解析 Markdown 文件
- 分析 Nargo 组件
- 生成文档内容
4. **HTML 生成**：
- 应用主题
- 生成导航和侧边栏
- 生成静态 HTML 文件
5. **资源处理**：
- 处理静态资源
- 优化输出文件
6. **输出**：将生成的文件写入输出目录
### 3.2 开发服务器流程
1. **配置解析**：读取并解析配置文件
2. **文件监听**：监听文件变化
3. **服务器启动**：启动 HTTP 服务器
4. **热更新**：
- 检测文件变化
- 重新处理变化的文件
- 通过 WebSocket 通知浏览器更新
5. **实时预览**：浏览器自动更新显示
## 4. 与现有 Nargo 工具的集成
### 4.1 与 nargo-tools 的集成
- **复用**：使用 nargo-tools 现有的文档生成功能
- **扩展**：扩展脚本分析能力，支持更详细的文档生成
- **集成**：将 nargo-document 作为 nargo-tools 的一个子命令
### 4.2 与 nargo-bundler 的集成
- **使用**：利用 nargo-bundler 的打包和构建能力
- **扩展**：添加文档特定的构建逻辑
- **优化**：针对文档场景优化构建性能
### 4.3 与 nargo-parser 的集成
- **使用**：利用 nargo-parser 解析 Nargo 文件
- **扩展**：添加对 Markdown 文件的解析支持
- **集成**：统一解析接口，支持多种文件格式
## 5. 性能优化策略
### 5.1 增量构建
- **实现**：只重新处理变化的文件
- **缓存**：缓存已处理的文件内容
- **依赖分析**：跟踪文件依赖关系，只重建受影响的文件
### 5.2 并行处理
- **实现**：利用 Rust 的多线程能力
- **并行**：并行处理多个文件
- **批处理**：批量处理相似任务
### 5.3 内存优化
- **实现**：优化内存使用
- **流式处理**：大文件采用流式处理
- **内存缓存**：合理使用内存缓存
## 6. 扩展性设计
### 6.1 插件系统
- **设计**：简单的插件接口
- **支持**：自定义插件扩展功能
- **集成**：与现有 Nargo 插件系统兼容
### 6.2 主题扩展
- **设计**：主题继承和覆盖机制
- **支持**：自定义主题和样式
- **集成**：与现有 CSS 处理工具集成
### 6.3 多语言支持
- **设计**：基于配置的多语言系统
- **支持**：自动生成多语言文档
- **集成**：与现有国际化工具集成
## 7. 迁移策略
### 7.1 从 VitePress 迁移
- **配置兼容**：提供 VitePress 配置的转换工具
- **内容兼容**：支持 VitePress 的 Markdown 扩展
- **主题迁移**：提供主题迁移指南
### 7.2 渐进式采用
- **设计**：支持与 VitePress 共存
- **工具**：提供迁移辅助工具
- **文档**：详细的迁移指南
## 8. 技术栈
- **核心语言**：Rust
- **前端**：HTML, CSS, JavaScript
- **构建工具**：Nargo 编译器链
- **依赖**：
- nargo-tools
- nargo-bundler
- nargo-parser
- markdown-rs (Markdown 解析)
- tokio (异步运行时)
- warp (HTTP 服务器)
## 9. 开发计划
1. **阶段 1**：基础架构搭建
- 命令行接口
- 配置系统
- 基础文档生成
2. **阶段 2**：核心功能实现
- Markdown 处理
- HTML 生成
- 静态站点构建
3. **阶段 3**：开发服务器
- 服务器实现
- 热模块替换
- 实时预览
4. **阶段 4**：主题系统
- 默认主题
- 主题定制
- 样式系统
5. **阶段 5**：优化和集成
- 性能优化
- 与 Nargo 工具链集成
- 迁移工具
## 10. 结论
Nargo Document 架构设计充分利用了 Nargo 现有的编译器链和工具能力，通过扩展和集成，构建一个完整的文档系统。该架构具有以下优势：
- **性能优势**：基于 Rust 的高性能实现
- **集成优势**：与 Nargo 工具链深度集成
- **扩展优势**：模块化设计，易于扩展
- **迁移优势**：支持从 VitePress 平滑迁移
通过这个架构，Nargo Document 可以为 Nargo 项目提供一个高效、灵活、功能完整的文档解决方案，替代现有的 VitePress 系统。