一直用gitbook命令行工具来管理自己的文档和电子书，但它早已停止更新开发，而且bug也不少，一直想寻找它的替代。

$ gitbook --version
CLI version: 2.3.2
GitBook version: 3.2.3

gitbook的一些问题

链接匹配错误

如果链接中包含)，生成的链接会有问题:

[波拉地区](https://en.wikipedia.org/wiki/Pola_(Italian_province))

会变成波拉地区)，右边的)被当成了文字，文字对应的链接也是错的，应该是正则写的不对。这个问题很好解决，将)用url encode：

[波拉地区](https://en.wikipedia.org/wiki/Pola_%28Italian_province%29)

脚注跳转失效

脚注如果是自定义文本，生成过程没有报错，显示的脚注也没有错误，但实际无法跳转。

in full expectation of victory.[^440.1]

[^440.1]: The Annals of Piacenza throw a new light on the history of Conradin

section267.html#fn_440.1脚注的链接实际是带fragment的url，但浏览器无法跳转，不确定是浏览器不支持这种写法的跳转还是生成链接的过程不对，还是个人写的格式有误（脚注是不是不能带.？），没时间研究了。

脚注不支持多行

很多书脚注也是带段落的，比如:

这个问题2016年就有人提了，然而从来没解过！这种情况markdown表现力一般，即使用纯html也不好实现，但最基本的段落至少应该支持一下。hexo是可以支持的，脚注的下一段落只要以4个空格开头就可以作为块结构被视为脚注的一部分。

网上找到一种解法，只适用于gitbook，那就是在段落后加引用符或列表符：

> Que per valor et per noble coratge
>
> Mantenia W Enricx Vonrat linhalge
>
> De Colradi ah honrat vassalatge ;
>
> E'l reys W Anfos, ab son noble barutage
>
> Que a cor ric
>
> Den demandar tost sonfrair EN Enric,
>

注意，后面每行不单独加空行还是会被连接成一个段落，有点丑陋，但能达到解决到这种程度已经不错了。

词汇表不匹配)

gitbook的词汇表GLOSSARY是我非常喜欢的功能之一，词汇表可以将正文中的文本段生成注释，鼠标悬浮即可显示额外解释性文字，而且对于长句有助力于区分句子结构，容易减少歧意。

但是如下形式的单词居然不能作为词汇表的key：

## Heinrich (VII)

估计和链接不匹配)的问题是一样的，然而不能用%29这种方式解决，这实在是不给力，得看源码才能知道是怎么回事。

词汇表不匹配非英文字符

中文地名无法作为词汇表的key：

亲自护送囚犯到帕莱斯特里纳附近的圣彼得罗 GLOSSARY.md中:

## 帕莱斯特里纳

要达到效果只能在正文中加入英文单词并用英文单词作为key:

亲自护送囚犯到帕莱斯特里纳(Palestrina)附近的圣彼得罗，在GLOSSARY.md中:

## Palestrina

帕莱斯特里纳是意大利拉齐奥大区罗马首都广域市的一个市镇。

其实这个问题准确的说是不能匹配非英文字符结尾的单词，如果出现一些其它语言的字符也不能作为词汇表的key，如Brancaleone von Andalò，但如果出现在中间，如Connétable就没问题。

构建速度慢

一旦有大量章节和文件，gitbook就比较慢了，手头有本书是多语言的，每种语言有168个md文件，再加上词汇表有大量词语，要搜索匹配文本，慢得一塌糊涂，构建一次快5分钟了。

不能热更新

gitbook似乎自带liveload插件，一旦修改文件照理能自动热更的，然而实际并没有，可能有好用的插件，但没有仔细找过。

pdf效果很差

在book.json里设置pdf的marign参数，本地用gitbook生成的pdf文件根本不生效，生成的目录也很丑陋，总是以1.打头，有点不舒服。

试用mkdocs

$ mkdocs -V
mkdocs, version 1.3.0

mkdocs是用python实现的，也是比较常用的markdown工具。

mkdocs兼容gitbook

使用mkdocs一个首要问题便是，如何兼容已有的大量的gitbook项目，如果一个一个的改配置，绝对无法忍受。研究了一下mkdocs，似乎它主要功能是为了生成静态站点，不是针对电子书。

固定的格式 mkdocs根目录需要有mkdocs.yml配置文件，源文件全部在根目录的docs/目录下，而且也不能配置。

自动生成目录 不像gitbook需要一个固定的SUMMARY.md文件来表示目录，mkdocs根据docs/的目录结构自动生成目录索引。

典型的gitbook多语言项目的目录:

LANGS.md
de/
  book.json
  SUMMARY.md
  README.md
en/
  book.json
  SUMMARY.md
  README.md
zh/
  book.json
  SUMMARY.md
  README.md
  GLOSSARY.md

当然可以新建docs目录，再将各语言目录移动到docs目录下，然而这样git会生成一大坨改动记录，没有做很好的兼容，可以用软链接达到这一目的：

docs/
  de -> ../de
  en -> ../en
  zh -> ../zh

用命令ln -s ../en docs/en就可以了，mkdocs.yml添加常规的属性就行，没有什么特别。

脚注自动生成序列

mkdocs本身不支持脚注，需要以扩展的形式在配置文件mkdocs.yml中加入：

markdown_extensions:
  - footnotes

mkdocs把所有的脚注都按顺序自动生成了从1开始的数字序列，这样浏览器是可以识别的，成功跳转。

脚注同样不支持多行

mkdocs的脚注不支持多行，也没有解法，使用引用符显示会不正确。

不支持词汇表

mkdocs看起来比较灵活，似乎需要以自定义的形式写一些类似预处理器，没有再进一步研究了。

构建速度

python应该是快一点的，但没有benchmark的基准测试没有定论。

不能生成电子书格式

---

试用mdbook

用mdbook最好是直接使用它的二进制命令，而不是通过包管理器安装，那样很麻烦

直接安装命令

下载相应系统的压缩包并解压：

wget https://github.com/rust-lang/mdBook/releases/download/v0.4.17/mdbook-v0.4.17-x86_64-unknown-linux-gnu.tar.gz

tar -zxvf mdbook-v0.4.17-x86_64-unknown-linux-gnu.tar.gz
mv mdbook ~/.local/bin

解压完当前目录有一个可执行的文件mdbook，移动至~/.local/bin就可以直接引用命令了。如果用包管理器安装，需要先安rust语言的包管理器cargo，再用cargo安装mdbook。

$ mdbook --version
mdbook v0.4.17

mdbook可以说是最接近gitbook的工具了，从目录结构与用法上，基本无缝支持。

mdbook兼容gitbook

mdbook如果非要支持多语言项目本身也不难，只需写一个SUMMARY.md文件，包含各语言的目录就没问题了。然而麻烦的是，对于已有的gitbook项目要如何支持呢，写一个包含所有目录的SUMMARY.md文件比较琐碎，而且分散在各个语言目录下的SUMMARY.md就得作废，只能从mdbook的配置文件book.toml入手。

可配置的格式 mdbook默认使用根目录下的src作为源码的目录，显然不能新建src再把所有源码目录移入，它的构建目录也不一样，还好这些都可以配置。

只能在各语言目录下分别构建自己的项目了，也就是说各语言目录下再多一个book.toml，这个问题不大，因为原本各语言就有一个自己的book.json。

de/
  book.toml
en/
  book.toml
zh/
  book.toml

book.toml如下，最关键的是src,build-dir两个key:

[book]
title = "罗马城中世纪史"
description = "从第五世纪到第十六世纪"
author = "[德] 斐迪南·格雷戈罗维乌斯, 译 林鹿"
multilingual = true
src = "."

[build]
build-dir = "_book"
create-missing = false

运行时，分别在各语言目录下执行mdbook serve， 这样能比较完整的支持已经有项目了。

脚注自动生成序列

与mkdocs一样，mdbook也自动生成数字序列，跳转无误。

脚注同样不支持多行

效果与mkdocs一样

不支持词汇表

可能需要按照mdbook的规范写一些preprocessor，得深入研究一下。

构建速度

当然它的构建速度按照预想应该相当快。

不能生成电子书

---

总体来说，目前这2个替代工具用起来也不是特别顺手，只能先继续用gitbook，要彻底解决非得深入gitbook源码了。但这么长时间没有更新，也没见社区开源爱好者们在这个基础上继续贡献，是有人改了没人合进主线还是源码太庞大不好改？也没有人另起炉社。