Oak-Team
/
oak-book
13
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
oak-book/MERMAID_GUIDE.md

5.4 KiB
Raw Blame History

mdBook 文档编写与 Mermaid 使用指南

📝 文档编写基础

1. 添加新章节

在 src/SUMMARY.md 中添加章节链接：

- [章节标题](./路径/文件.md)
    - [子章节](./子章节.md)

2. 创建 Markdown 文件

在 src/ 目录下创建对应的 .md 文件，使用标准的 Markdown 语法编写。

3. 常用命令

# 构建文档
mdbook build

# 启动本地预览服务器（支持热重载）
mdbook serve

# 清理构建文件
mdbook clean

🎨 Mermaid 图表使用

Mermaid 已经成功安装并配置！你可以在任何 Markdown 文件中使用以下图表类型：

1. 流程图 (Flowchart)

```mermaid
graph TD
    A[开始] --> B{是否登录?}
    B -->|是| C[显示主页]
    B -->|否| D[跳转登录页]
    C --> E[结束]
    D --> E
```

2. 时序图 (Sequence Diagram)

```mermaid
sequenceDiagram
    participant 用户
    participant 前端
    participant 后端
    participant 数据库
    
    用户->>前端: 发起请求
    前端->>后端: API 调用
    后端->>数据库: 查询数据
    数据库-->>后端: 返回结果
    后端-->>前端: JSON 响应
    前端-->>用户: 渲染页面
```

3. 类图 (Class Diagram)

```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)

```mermaid
stateDiagram-v2
    [*] --> 草稿
    草稿 --> 审核中: 提交审核
    审核中 --> 已发布: 审核通过
    审核中 --> 草稿: 审核拒绝
    已发布 --> 已归档: 归档
    已归档 --> [*]
```

5. 甘特图 (Gantt Chart)

```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)

```mermaid
pie title 技术栈分布
    "TypeScript" : 45
    "React" : 25
    "Node.js" : 20
    "MySQL" : 10
```

7. ER 图 (Entity Relationship Diagram)

```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)

```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 中添加：

- [Oak 架构设计](./architecture.md)

创建 src/architecture.md：

# 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 中添加：

[output.html.mermaid]
theme = "default"  # 可选: default, dark, forest, neutral

  1. 图表方向：

    • graph TD 或 graph TB：从上到下
    • graph LR：从左到右
    • graph RL：从右到左
    • graph BT：从下到上

  2. 节点形状：

    • [矩形]
    • (圆角矩形)
    • {菱形}
    • ((圆形))
    • [[子程序]]
    • [(圆柱)]

  3. 在线编辑器：使用 Mermaid Live Editor 在线测试图表

📚 更多资源