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-bookDo 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 contentAll 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 的基本使用方法,并演示了一个简单的构建过程。