【mdBook】4 mdBook 命令行工具详解

mdbook 命令行工具用于创建和构建书籍。安装 mdbook 后，您可以在终端中运行 mdbook help 命令来查看所有可用命令。

以下各节详细介绍了不同的可用命令。

命令列表及功能说明

mdbook init <directory>

• 功能: 创建一个新的书籍项目
• 说明: 生成包含最小样板文件的新书目录结构，帮助您快速开始编写
• 示例:

  mdbook init my-book
  

mdbook build

• 功能: 渲染构建书籍
• 说明: 将 Markdown 源文件编译成 HTML 静态网站，输出到 book/ 目录
• 用途: 用于生成最终的发布版本

mdbook watch

• 功能: 监听文件变化并自动重建
• 说明: 监控源文件的变化，一旦检测到修改就自动重新构建书籍
• 优势: 提高开发效率，无需手动重复执行构建命令

mdbook serve

• 功能: 启动本地服务器并提供实时预览
• 说明:
  • 启动 Web 服务器（默认端口 3000）
  • 自动检测文件变化并重新构建
  • 支持浏览器自动刷新
• 使用场景: 编写过程中的实时预览和调试

mdbook test

• 功能: 测试 Rust 代码示例
• 说明: 运行书籍中所有的 Rust 代码块，确保示例代码能够正确编译和执行
• 重要性: 保证技术文档中代码示例的准确性和可靠性

mdbook clean

• 功能: 清理构建输出
• 说明: 删除 book/ 目录中所有已渲染的文件，用于清理构建缓存或重新开始构建
• 用途: 解决构建问题或释放磁盘空间

mdbook completions

• 功能: 生成 Shell 自动补全脚本
• 说明: 为不同的 Shell（bash、zsh、fish 等）生成自动补全配置，提高命令行使用效率
• 使用方法:

  mdbook completions bash > /etc/bash_completion.d/mdbook
  

工作流程示例

典型的 mdbook 使用流程：

1. 初始化项目

   mdbook init my-documentation
   cd my-documentation
   

2. 开发时实时预览

   mdbook serve --open
   

3. 最终构建发布

   mdbook build
   

4. 清理构建文件

   mdbook clean
   

注意事项

• 大多数命令需要在包含 book.toml 配置文件的目录中运行
• serve 和 watch 命令支持热重载，适合开发阶段使用
• test 命令需要系统安装 Rust 工具链
• 各命令都支持额外的配置选项，可通过 --help 查看详细用法