安装 mdBook

cargo install mdbook

启动

mdbook serve --open

默认访问地址：

http://localhost:3000

构建

mdbook build

生成的 HTML 位于：

target/mdbook/

入口页面：

target/mdbook/index.html

测试 Markdown 中的 Rust 代码

mdbook test

该命令会编译和测试 Markdown 中能够执行的 Rust 代码块，以及通过 {{#playground}} 引用的 Rust 文件。

新增知识章节

例如新增“RUST基础/表达式”：

book/src/RUST基础/表达式/
└── README.md

然后在 book/src/SUMMARY.md 中添加：

- [表达式](RUST基础/表达式/README.md)

只有被 SUMMARY.md 引用的 Markdown 页面才会显示在 mdBook 导航中。

为知识点创建可调试 Demo

需要代码示例时，在知识点目录中创建固定名称的 demo Cargo Package：

cargo new "book/src/RUST基础/表达式/demo" --name expressions_demo

建议将多个独立示例放入 src/bin/：

表达式/
├── README.md
└── demo/
    ├── Cargo.toml
    └── src/bin/
        ├── statements.rs
        └── expressions.rs

每个 .rs 文件需要包含自己的 main() 函数。

根目录 Cargo.toml 使用以下配置自动发现 Demo：

[workspace]
members = ["book/src/*/*/demo"]
resolver = "2"

因此，不需要手动将每个 Demo 添加到 workspace。

运行指定 Demo：

cargo run -p expressions_demo --bin expressions

检查全部 Demo：

cargo check --workspace

在 mdBook 页面中展示并运行真实 Demo

知识点的 README.md 可以直接引用同目录 Demo：

{{#playground demo/src/bin/expressions.rs editable}}

这样同一份代码可以：

• 在 mdBook 页面展示和编辑。
• 通过 Rust Playground 在线运行。
• 通过 mdbook test 检查。
• 通过 Cargo 编译和运行。
• 在 RustRover 中断点调试。

页面运行依赖在线 Rust Playground，适合单文件和标准库示例。包含本地文件、复杂依赖、网络服务或异步运行时的示例，应通过 Cargo 和 RustRover 运行。

主要配置文件

• book.toml：mdBook 配置，包括源码路径、输出目录和 Playground 设置。
• book/src/SUMMARY.md：知识库目录和导航结构。
• Cargo.toml：根 Cargo workspace 配置。
• AGENTS.md：项目目标、目录结构、命名规则和操作约束。