MDBook 使用指南

MDBook 是一个灵感来自 Gitbook 的强大工具，专门用于创建电子书和文档。它能够将 Markdown 编写的内容编译成静态网站，非常适合项目文档、教程和书籍的发布。

个人实践过许多文档方案，如 hexo、hugo、WordPress、docsify 和 mdbook 等，每种方案各有其优势和适用场景。对于博客而言，hexo 适合更新零散文章且维护简单； WordPress 提供了丰富的功能和主题配置，但配置起来相对麻烦；在文档生成方面，docsify 适合内容不多的团队文档，而 mdbook 则非常适合长篇文档和书籍的场景。

今天，我们主要介绍 MDBook 的基本用法。

安装与配置

首先，安装 Rust。具体步骤参阅 Rust 入门指南。

然后通过 Rust 的包管理器 Cargo 安装 MDBook：

cargo install mdbook

安装完成后，通过以下命令来验证安装：

mdbook --version

初始化项目

创建一个新的 MDBook 项目，执行以下命令：

mdbook init my-book

根据提示填写相应信息：

❯ mdbook init my-book

Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book? 
MDBook demo
2024-11-12 00:14:39 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...

这样将会创建一个名为 my-book 的新目录，其中包含项目的配置文件和目录结构：

my-book
├── book
├── book.toml
└── src
    ├── chapter_1.md
    └── SUMMARY.md

文件结构

book.toml 是 MDBook 的配置文件，用于定义书籍的标题、作者及其他配置选项。示例如下：

[book]
authors = ["rexwzh"]
language = "en"
multilingual = false
src = "src"
title = "MDBook demo"

[output.html]
theme = "light"

这里的 src 项指定了源码目录，可以替换为 docs 或其他名称。

src 目录存储 Markdown 源文件，特别地， SUMMARY.md 文件定义了目录结构，示例内容如下：

# Summary

- [Chapter 1](./chapter_1.md)

而 chapter_1.md 是章节内容，它被 SUMMARY.md 所引用。

构建和预览

在完成文档内容的编写和调整后，进入项目根目录，运行以下命令进行构建：

mdbook build

这将在 book 目录下生成静态网页，可以通过 -d 参数指定输出目录。

为了更便捷地预览文档，可以启动本地服务器进行交互式查看：

mdbook serve

默认服务器在 localhost:3000 上启动。也可以通过以下命令指定不同的参数：

mdbook serve -p 8080 -n 0.0.0.0 -d book

总结

以上，我们介绍了 MDBook 的基本使用方法，并演示了一个简单的构建过程。