gitbook迁移mkdocs,mdbook及其之间的比较
一直用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源码了。但这么长时间没有更新,也没见社区开源爱好者们在这个基础上继续贡献,是有人改了没人合进主线还是源码太庞大不好改?也没有人另起炉社。
转载自:https://juejin.cn/post/7086386302861443103