MDBook 使用指南

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

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

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

安装与配置

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

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

bash 复制代码

cargo install mdbook

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

bash 复制代码

mdbook --version

初始化项目

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

bash 复制代码

mdbook init my-book

根据提示填写相应信息：

bash 复制代码

❯ 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 的新目录，其中包含项目的配置文件和目录结构：

bash 复制代码

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

文件结构

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

toml 复制代码

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

[output.html]
theme = "light"

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

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

md 复制代码

# Summary

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

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

构建和预览

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

bash 复制代码

mdbook build

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

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

bash 复制代码

mdbook serve

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

bash 复制代码

mdbook serve -p 8080 -n 0.0.0.0 -d book

总结

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