写作需求

为什么要使用mdbook?

我的写作需求:

记笔记

支持目录层级的创建

生成pdf定期查看

支持mermaid的语法

原来有使用过gitbook, 只能说gitbook的使用一言难尽，在不同的机器上安装时，可能遇到各种各样的问题，文件较多时，反应就特别慢，但这些都不是问题，关键是没有人维护，gitbook团队专心做线上编辑，不再更新开源的npm库了.

之前也有尝试过docsify的这种文档，当时页面等太花哨了，不太适合我对文档的审美。

最终听说了有一个软件mdbook,基本上可以从gitbook 完美的迁移到mdbook, 且同时也支持各种插件，且各种插件也比较完美的符合我的需求，且界面简单不花哨，社区一直在做更新和维护，mdbook 可以做到实时update, 除非你使用了一些插件(mdbook-pdf)需要花费额外的时间, 否则可以秒同步, so I like it.

安装和使用

首先mdbook 这个玩意使用的rust编写的，所以需要先安装rust的环境，这个时候会有选项，默认选择即可。

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

配置国内镜像源，加快访问速度进入~/.cargo/目录 touch config 创建config文件配置如下

[source.crates-io]
replace-with = 'tuna'

[source.tuna]
registry = "https://mirrors.tuna.tsinghua.edu.cn/git/crates.io-index.git"

然后就是安装mdbook 不过最好下载一下mdbook的源码，mdbook不支持pdf的书签？可能在后续不久可以直接安装，目前mdbook-pdf的作者正在提交PR，直到我今天(2023/2/19)写这个文章为止，还没能直接合入到主线分支内。所以目前使用源码是最好的选择。

git clone git@github.com:HollowMan6/mdBook.git

然后需要使用一个patch, 所以需要使用上方这个作者提供的fork库, 大家可以关注这个mdbook-pdf的作者github.com/HollowMan6最新的这个PR的进展 github.com/rust-lang/m… 如果提交入库后，可以直接使用进行安装

cargo install mdbook

如果还没有入库，源码的安装方式,进入源码目录

cd mdBook // 下载的HollowMan6的源码
cargo install .

安装完成后初始化一个文档

mdbook init 书籍路径

会在当前的目录下生成一个src路径和book.toml配置文件

目录或文件名	描述
book	主要用于存储mdbook server或mdbook build中生成的大量的中间文件
book.toml	主要用于存储关于书籍的配置，如书籍名称，插件等信息
src/SUMMARY.md	书籍目录
src/chapter_1.md	书籍内容

在使用时，使用方法和docsify以及gitbook差别不大，主要是使用命令mdbook server 书籍路径即可，然后就可以在浏览器中访问http://127.0.0.1:3000即可.

安装mdbook-pdf 首先安装一下mdbook-pdf，非小白可以参考一下github.com/HollowMan6/…

cargo install mdbook-pdf

注意:mdbook-pdf中有两种输出方式

一种是使用google-chrome的pdf输出方式
另一种是使用wkhtmltopdf 这里依赖了一个pip的安装，这个是python的环境，如果有不会的同学，请自行百度. pip install mdbook-pdf-outline

上方的使用wkhtmltopdf中使用有一些小问题，在遇到中文时，可能会出现问题，使用第一种方式即可了.如果乐意使用第二种，可以自己修改一个mdbook-pdf-outline中的中文编码问题导致的无法生成文件.

第一种的配置方法如下,在book.toml中添加下方的文件

# 这个时mdbook-插件要求先生成output.pdf文件，生成别的名称可能出错
[output.pdf]
# 这个是需要生成pdf的toc，也就是侧边栏的目录时，需要配置的
[output.pdf-outline]

可以在不使用时关闭上方的两个选项，否则每次编译都会同步，速度会比较慢。

安装mdbook-mermaid

cargo install mdbook-mermaid

使用 mdbook-mermaid install 书籍路径 配置生成相关的文件

生成完成后在book.toml中就自动添加了如下内容，同时新增了两个文件"mermaid.min.js", "mermaid-init.js"

因为目前mermaid有部分属于拓展的功能，主模块不支持，所以需要去找到 mermaid.js.org/syntax/mind… 这个路径下cdn.jsdelivr.net/npm/mermaid…的压缩的mermaind.min.js文件,替换到本地的文件.

需要删除原来mermaid-init.js中的内容，使用如下内容进行替换

mermaid.registerExternalDiagrams([window["mermaid-mindmap"]]).then(() => mermaid.initialize({startOnLoad:true}));

具体情况请参考: github.com/badboy/mdbo…

支持的mindmap的渲染图

再看一下掘金的渲染图, 目前还无法渲染

mindmap
  操作系统硬件架构
    id))x86架构((
      amd32
      amd64
      Ia32
      Ia64
    id))arm系列((
      arm32
      arm64
    id))riscv((
      rv32I
      rv32E
      rv64I
      rv128I
    id))mips架构((
      mips32
      mips64

安装mdbook-toc

cargo install mdbook-toc

这个插件主要用于我们在使用时，如果编写了较大的一个markdown文件，可以使用这个作为单markdown文件的html页面中的导航栏进行浏览。

配置文件

[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]

mdbook-toc还支持各种层级配置，大家可以自行探索 github.com/badboy/mdbo…

整体配置文件如下所示:

然后到源码目录下使用mdbook server . 就可以享受mdbook了

mdbook 写作真的好用

写作需求

安装和使用