MdBook | GitBook的替代者

1、前言

前面，我们已经介绍过很多的文档构建工具，比如Docsify、MkDocs、Nikola、Pelican等等。今天我们来介绍一款号称是GitBook替代者的文档构件工具，它就是MdBook。

MdBook是一款使用Rust开发的文档构建工具，它特别轻量，不依赖开发环境，仅仅一个可执行文件就能完成文档构建。而且构建出的文档网站具备代高亮、本地搜索、markdown渲染等功能。

2、MdBook实践

2.1、获取MdBook

我们从MdBook的Github release页面去根据操作系统下载我们需要的软件包即可。

下载解压后，就可以得到mdbook.exe，我们在mdbook.exe所在路径下直接使用mdbook.exe即可进行项目创建和开发了。

2.2、创建项目

我们可以对当前目录进行初始化，也能指定文件夹进行初始化。

创建项目命令：mdbook.exe init ./docs

2.3、项目结构

docs/
├── book
├── book.toml
└── src
    ├── chapter_1.md
    └── SUMMARY.md

以上，book是mdbook帮我们构建完的静态工程，book.toml是项目的配置文件，src才是原始的md文档。

我们向src中增加一个目录，然后向其中添加一个md文件，启动mdbook的开发服务器查看效果。

2.4、预览文档

命令：.\mdbook.exe serve .\doc\

如上，mdbook构建的文档和gitbook还是非常相似的。

2.5、自定义侧边栏

mdbook的侧边栏是在项目根目录下的SUMMARY.md中定义的， 我们只需要将我们自己开发的文档在SUMMARY.md中进行配置，即可实现侧边栏导航。

SUMMARY.md

# Summary

- [Chapter 1](./chapter_1.md)
- [我自己的文档](./chapter_2.md)
  - [安装](./panyun/hostover_install.md)
  - [升级](./dsds.md)

文档结构

└─src
        │  chapter_1.md
        │  chapter_2.md
        │  dsds.md
        │  SUMMARY.md
        │
        └─my
                hostover_install.md
                hostover_portal_upgrade.md
                hostover_upgrade.md

预览效果

mdbook支持配置SUMMARY.md自动生成文件，非常适合预先构建文档结构的场景。

3、小结

经过简单的使用体验，我们可以发现mdbook构建文档是非常的简单，但是它也存在一些问题。

1. 不支持中文搜索。
2. 不支根据文档标题自动生成侧边目录。
3. 代码块行间距太小。
4. 不支持提示块。
5. 不支持顶部导航。

新兴项目能做到这样已经很不错了，期待mdbook越来越好。