开源电子书：mdBook

现在写书，比以往任何时候都要方便。

有很多不错的工具来让我们写“在线书籍”或“技术文档”，人人都可以成为作者。

GitBook 和 mdBook 都是不错的工具，都使用Markdown语法。个人更喜欢mdBook，因为它开源，完全免费，底层使用Rust语言来将Markdown文件渲染为html网页，拥有极高的性能。更重要的是，所有的源文件、配置、编译脚本都在本地，不必担心某个公司破产或倒闭导致你的书消失。

另外，它还有一个特色，如果你用它编写Rust的演示代码，它直接可以在网页上运行！

总之，如果你喜欢本地控制感、追求极致速度，mdBook是不容错过的。

好了，让我们来看看如何用它来快速写一本书吧。

安装 Rust

第一步，先安装Rust：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

执行上面命令，会在你的电脑上安装Rust。完成后，关闭当前终端，再打开一个新终端，输入：

rustc --version

会在控制台打印出已经安装的rust的版本，rustc是rust的编译命令，和javac类似。

安装 mdBook

接下来，安装mdBook。也很简单：

cargo install mdbook

直接使用Rust自带的cargo命令安装即可。

第一本书

完成后，就用它来编写我们的第一本书吧。

mdbook init my-book

执行后，会在当前目录下创建一个名称为my-book的目录。该目录类似如下：

为了写书，你需要使用如下命令开启一个http server：

mdbook serve --open

默认开启的是3000端口，运行后，会自动打开电脑上的默认浏览器。现在，你就能在浏览器上边写书边预览了。

book.toml

该文件是整个 mdBook 项目的核心配置文件，其主要作用如下：

• 定义书籍元数据：通过 [book] 区块，设置书名、作者、版本等基本信息 。
• 控制构建行为：在 [build] 区块中，可配置输出目录路径、是否启用搜索等功能 。
• 启用与配置插件：实现功能扩展，比如安装 preprocessor 插件来检查文档内的代码示例能否正确运行。

由于这个工具是老外开发的，英文的段落开头没有缩进。但中文的段落开头需要二个汉字的缩进，可以在该文件中新增配置：

[output.html]
additional-css = ["custom.css"]

然后，在项目根目录下新增custom.css文件，内容如下：

.content p {
  text-indent: 2em;
}

这样，就能达到缩进的效果。

src目录

这个是最重要的，该目录是存放我们思想（markdown源文件）的地方。其中，里面有一个SUMMARY.md文件，它的作用是用来生成左边的大纲。

比如，如下内容：

# Summary

[前言](./preface.md)

- [第一章 入门](./chap01/chap_1.md)
  - [第一小节](./chap01/chap_1_1.md)
  - [第二小节](./chap01/chap_1_2.md)
- [第二章 基本类型](./chap02/chap_2.md)
  - [整数](./chap02/chap_2_1.md)
  - [浮点数](./chap02/chap_2_2.md)
  - [布尔值](./chap02/chap_2_3.md)

会被渲染成如下的大纲：

这个大纲会放在网站的左边位置。

book

这个book存放的是编译后得到的静态文件（html, css, js等），你可以通过如下命令构建：

mdbook build

然后，将book目录下的静态文件放到服务器中，就可以在互联网上共享了。

关于中文搜索

因为这个工具是老外写的，目前不支持中文搜索，个人觉得无伤大雅，全局搜索功能很多时候也用不到。如果真的纠结，可以到Github上提提issue，好像有人用其他方法实现了中文搜索功能。

参考

• mdBook Documentation