目 录CONTENT

文章目录

MdBook | GitBook的替代者

phyger
2022-06-02 / 0 评论 / 4 点赞 / 2,426 阅读 / 1,124 字 / 正在检测是否收录...

1、前言

前面,我们已经介绍过很多的文档构建工具,比如Docsify、MkDocsNikolaPelican等等。今天我们来介绍一款号称是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越来越好。

4

评论区