287 lines
5.4 KiB
Markdown
287 lines
5.4 KiB
Markdown
# mdBook 文档编写与 Mermaid 使用指南
|
||
|
||
## 📝 文档编写基础
|
||
|
||
### 1. 添加新章节
|
||
|
||
在 `src/SUMMARY.md` 中添加章节链接：
|
||
|
||
```markdown
|
||
- [章节标题](./路径/文件.md)
|
||
- [子章节](./子章节.md)
|
||
```
|
||
|
||
### 2. 创建 Markdown 文件
|
||
|
||
在 `src/` 目录下创建对应的 `.md` 文件，使用标准的 Markdown 语法编写。
|
||
|
||
### 3. 常用命令
|
||
|
||
```bash
|
||
# 构建文档
|
||
mdbook build
|
||
|
||
# 启动本地预览服务器（支持热重载）
|
||
mdbook serve
|
||
|
||
# 清理构建文件
|
||
mdbook clean
|
||
```
|
||
|
||
## 🎨 Mermaid 图表使用
|
||
|
||
Mermaid 已经成功安装并配置！你可以在任何 Markdown 文件中使用以下图表类型：
|
||
|
||
### 1. 流程图 (Flowchart)
|
||
|
||
````markdown
|
||
```mermaid
|
||
graph TD
|
||
A[开始] --> B{是否登录?}
|
||
B -->|是| C[显示主页]
|
||
B -->|否| D[跳转登录页]
|
||
C --> E[结束]
|
||
D --> E
|
||
```
|
||
````
|
||
|
||
### 2. 时序图 (Sequence Diagram)
|
||
|
||
````markdown
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant 用户
|
||
participant 前端
|
||
participant 后端
|
||
participant 数据库
|
||
|
||
用户->>前端: 发起请求
|
||
前端->>后端: API 调用
|
||
后端->>数据库: 查询数据
|
||
数据库-->>后端: 返回结果
|
||
后端-->>前端: JSON 响应
|
||
前端-->>用户: 渲染页面
|
||
```
|
||
````
|
||
|
||
### 3. 类图 (Class Diagram)
|
||
|
||
````markdown
|
||
```mermaid
|
||
classDiagram
|
||
class OakObject {
|
||
+String id
|
||
+Date createdAt
|
||
+save()
|
||
+delete()
|
||
}
|
||
|
||
class User {
|
||
+String name
|
||
+String email
|
||
+login()
|
||
}
|
||
|
||
class Post {
|
||
+String title
|
||
+String content
|
||
}
|
||
|
||
OakObject <|-- User
|
||
OakObject <|-- Post
|
||
User "1" --> "*" Post : 发布
|
||
```
|
||
````
|
||
|
||
### 4. 状态图 (State Diagram)
|
||
|
||
````markdown
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> 草稿
|
||
草稿 --> 审核中: 提交审核
|
||
审核中 --> 已发布: 审核通过
|
||
审核中 --> 草稿: 审核拒绝
|
||
已发布 --> 已归档: 归档
|
||
已归档 --> [*]
|
||
```
|
||
````
|
||
|
||
### 5. 甘特图 (Gantt Chart)
|
||
|
||
````markdown
|
||
```mermaid
|
||
gantt
|
||
title Oak 项目开发计划
|
||
dateFormat YYYY-MM-DD
|
||
section 设计阶段
|
||
需求分析 :done, des1, 2025-01-01, 2025-01-15
|
||
系统设计 :active, des2, 2025-01-10, 2025-01-30
|
||
section 开发阶段
|
||
后端开发 : dev1, 2025-02-01, 30d
|
||
前端开发 : dev2, 2025-02-15, 25d
|
||
section 测试阶段
|
||
单元测试 : test1, after dev1, 10d
|
||
集成测试 : test2, after dev2, 15d
|
||
```
|
||
````
|
||
|
||
### 6. 饼图 (Pie Chart)
|
||
|
||
````markdown
|
||
```mermaid
|
||
pie title 技术栈分布
|
||
"TypeScript" : 45
|
||
"React" : 25
|
||
"Node.js" : 20
|
||
"MySQL" : 10
|
||
```
|
||
````
|
||
|
||
### 7. ER 图 (Entity Relationship Diagram)
|
||
|
||
````markdown
|
||
```mermaid
|
||
erDiagram
|
||
USER ||--o{ POST : 发布
|
||
USER {
|
||
string id PK
|
||
string name
|
||
string email
|
||
}
|
||
POST ||--|{ COMMENT : 包含
|
||
POST {
|
||
string id PK
|
||
string title
|
||
string content
|
||
string userId FK
|
||
}
|
||
COMMENT {
|
||
string id PK
|
||
string content
|
||
string postId FK
|
||
string userId FK
|
||
}
|
||
USER ||--o{ COMMENT : 评论
|
||
```
|
||
````
|
||
|
||
### 8. Git 图 (Git Graph)
|
||
|
||
````markdown
|
||
```mermaid
|
||
gitGraph
|
||
commit
|
||
commit
|
||
branch develop
|
||
checkout develop
|
||
commit
|
||
commit
|
||
checkout main
|
||
merge develop
|
||
commit
|
||
branch feature
|
||
checkout feature
|
||
commit
|
||
checkout main
|
||
merge feature
|
||
```
|
||
````
|
||
|
||
## 🚀 完整示例
|
||
|
||
创建一个新的章节来展示 Oak 架构：
|
||
|
||
**在 SUMMARY.md 中添加：**
|
||
```markdown
|
||
- [Oak 架构设计](./architecture.md)
|
||
```
|
||
|
||
**创建 src/architecture.md：**
|
||
|
||
````markdown
|
||
# Oak 架构设计
|
||
|
||
## 系统架构图
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph 前端层
|
||
A[React 组件] --> B[Oak Client SDK]
|
||
end
|
||
|
||
subgraph 应用层
|
||
B --> C[API Gateway]
|
||
C --> D[业务逻辑层]
|
||
D --> E[对象模型层]
|
||
end
|
||
|
||
subgraph 数据层
|
||
E --> F[(MySQL)]
|
||
E --> G[(MongoDB)]
|
||
end
|
||
|
||
subgraph 基础设施
|
||
H[权限系统]
|
||
I[日志系统]
|
||
J[缓存系统]
|
||
end
|
||
|
||
D --> H
|
||
D --> I
|
||
D --> J
|
||
```
|
||
|
||
## 请求处理流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as 客户端
|
||
participant A as API Gateway
|
||
participant B as 业务层
|
||
participant D as 数据库
|
||
|
||
C->>A: HTTP 请求
|
||
A->>A: 验证权限
|
||
A->>B: 调用业务逻辑
|
||
B->>B: 数据验证
|
||
B->>D: 执行查询
|
||
D-->>B: 返回数据
|
||
B->>B: 业务处理
|
||
B-->>A: 返回结果
|
||
A-->>C: JSON 响应
|
||
```
|
||
````
|
||
|
||
## 💡 提示与技巧
|
||
|
||
1. **实时预览**：运行 `mdbook serve`，在浏览器中打开 `http://localhost:3000`，编辑后会自动刷新
|
||
|
||
2. **图表样式**：Mermaid 支持主题配置，可以在 `book.toml` 中添加：
|
||
```toml
|
||
[output.html.mermaid]
|
||
theme = "default" # 可选: default, dark, forest, neutral
|
||
```
|
||
|
||
3. **图表方向**：
|
||
- `graph TD` 或 `graph TB`：从上到下
|
||
- `graph LR`：从左到右
|
||
- `graph RL`：从右到左
|
||
- `graph BT`：从下到上
|
||
|
||
4. **节点形状**：
|
||
- `[矩形]`
|
||
- `(圆角矩形)`
|
||
- `{菱形}`
|
||
- `((圆形))`
|
||
- `[[子程序]]`
|
||
- `[(圆柱)]`
|
||
|
||
5. **在线编辑器**：使用 [Mermaid Live Editor](https://mermaid.live/) 在线测试图表
|
||
|
||
## 📚 更多资源
|
||
|
||
- [mdBook 官方文档](https://rust-lang.github.io/mdBook/)
|
||
- [Mermaid 官方文档](https://mermaid.js.org/)
|
||
- [mdbook-mermaid 仓库](https://github.com/badboy/mdbook-mermaid)
|