类似GitBook的文档构建工具

简介: 类似GitBook的文档构建工具

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越来越好。

相关文章
|
资源调度 前端开发
React富文本编辑器wangEditor
React富文本编辑器wangEditor
354 0
文本,vitepress两栏怎样设置,应用场景是每个导航都是单独的markdown文件
文本,vitepress两栏怎样设置,应用场景是每个导航都是单独的markdown文件
|
SQL 数据采集 JSON
Pandas 使用教程 Series、DataFrame
Pandas 使用教程 Series、DataFrame
234 0
|
存储 资源调度 JavaScript
package.json——从vue的package.json来详细说明package.json内容
package.json——从vue的package.json来详细说明package.json内容
353 0
|
域名解析 网络协议 安全
记一次 HTTPS 抓包分析和 SNI 的思考
日常听说 HTTPS 是加密协议,那现实中的 HTTPS 流量,是真的完全加密吗?答案是,不一定。原因嘛,抓个包就知道了。我们用 curl 命令触发一下!
674 1
|
Unix Linux Shell
不同RTOS中POSIX接口的实现差异
本文探讨了在开发实时应用时使用POSIX API来实现跨平台和可移植性的策略。
272 1
不同RTOS中POSIX接口的实现差异
|
安全 PHP 数据库
laravel中模型中$fillable的用法
通过正确使用 `$fillable`属性,开发者可以有效地保护应用免受批量赋值漏洞的影响。它使得只有指定的字段可以被外部用户输入影响,为应用数据的安全性提供了一道防线。在开发使用Laravel框架的应用时,恰当地设置 `$fillable`或 `$guarded`属性是一项最佳实践。
159 0
|
监控 网络安全 数据安全/隐私保护
|
编译器 PHP
php8开启jit,php8配置jit,如何在PHP8中设置开启JIT
php8开启jit,php8配置jit,如何在PHP8中设置开启JIT
1358 0