Gitbook 相关
Gitbook 相关。
平时写的文章都是一篇一篇的,有点散,如果使用 Gitbook 的形式组织起来,能够把同类的文章聚在一起,学习或者复习的效率会更高一些。
教程
官方教程
Gitbook 官方网站现在主要是宣传他们的文档托管,对于他们开发的 npm 平台上的工具的介绍基本没有,但是在 npm 上有对于其工具的官方介绍。
除了官方插件,还有很多第三方插件,可以到 npm 官网去查。
github 官方仓库:GitbookIO/gitbook: Modern documentation format and toolchain using Git and Markdown
第三方教程
个人经验
常用命令
gitbook init
gitbook init
会根据当前目录下的 SUMMARY.md
文件在当前目录生成对应的目录和文件。
- 如果
SUMMARY.md
中命名的文件已经存在,那么执行本命令不会覆盖原有文件
TODO - 个人感觉,手动编辑 SUMMARY.md
文件太麻烦了,有时间要写一个根据目录和文件反向生成 SUMMARY.md
的工具。或许有用,到时候再根据工作流评估一下。
gitbook build
构建。
安装插件
把需要的插件写到 book.json
中,然后在 gitbook 目录下执行 gitbook install ./
,gitbook 会自动根据 book.json
中的信息安装插件。
每次在 book.json
中配置了新插件,执行 gitbook install ./
会重新安装以前的插件,导致之前自己修改的 katex 插件就失效了。
mathjax 和 katex 的对比
速度
katex 速度快得多,网上有一个测试:KaTeX and MathJax Comparison Demo
可复制性
偶尔一些比较简单的公式,MathJax 复制之后还是一行的,但是 katex 复制之后就是每个字符占一行。但是复杂的公式,直接复制,效果都相当于没有。
MathJax 提供常看 LaTex 命令的功能,直接在公式上点击右键打开菜单选择即可。Katex 不支持这个功能。
所以,从这个角度来讲,MathJax 显然更好一些,因为文章的读者可能需要复制某个公式,但是使用 Katex 就很不方便。
Gitbook 存在的一些问题
下面列出的问题,有可能是存在解决方案但是我不知道的,暂且记录下来。
mathjax
官方的 mathjax 不支持单个 $ 括起来的数学公式,只支持 $$ 括起来的数学公式。不能很好的和 Typora 语法兼容。
把
node_moudles
文件夹中的gitbook-plugin-mathjax
中的index.js
文件修改一下就可以实现单美元符号的功能,但是双美元符号会出现问题,还没找到兼容的方法。把
gitbook-plugin-katex
中的index.js
修改了之后,暂时可以用。过程中遇到了一些 “EOF” bug 之类的,是因为 Typora 向公式中添加了一些 ZERO-WIDTH-SPACE,导致产生错误,删除了就好了。github上的一些讨论:
切换文章的时候好像是通过 js 重载页面的,mathjax 不会被加载,必须要手动刷新才可以触发 mathjax 的渲染。【经测试,这个问题可以通过把公式引擎换成katex来解决,但是还是需要 $$ 双美元符号括起来。】
共性问题
- 不支持类似 hexo 的 front-matter 来生成 URL,也就是生成的 HTML 的名称和文件名是一样的。而hexo中可以通过urlname自己指定一篇文章渲染之后的html的文件名。
- 图片加载问题。
- 点击每篇文章最上边的标题会回到 introduction界面。
Typora 的问题
Typora 会在内联公式中添加 ZERO-WIDTH-SPACE(U+200B)
TODO - 需要写一个脚本删除Hexo 所有文章中这个字符U+200B。
一些技巧
使用正则处理文件名之后,拷贝到 SUMMARY.md
处理剑指Offer文件名的正则表达式:
匹配:((.*)(剑.*)\.md)
替换: * [\3](jian-zhi-offer/\1)
处理 LeetCode 的正则表达式
匹配:((.*?)(L.*)\.md)
(其中使用了 .*?
,最后一个问号防止贪心匹配)
替换: * [\3](leetcode/\1)
TODO - 还需要写一个根据 剑指Offer 和 LeetCode 题号来排序的脚本。
当前结局方案,使用正则+Excel,
先使用正则提取出题号:
匹配:.*?([0-9]+)\..*
替换:\1
然后把文件名和题号分为两裂一起复制到 Excel 中,然后根据题号排序,之后再把文件名复制出来即可。
批处理命令快速获取当前目录所有文件名
1 | DIR *.* /B >fileName.txt |
使用方法:新建一个纯文本文件,把这个内容输进去,然后另存为后缀名为 .bat
的文件,然后双击执行,当前目录下会自动生成一个名字为 fileName.txt
的纯文本文件,包含当前目录所有的文件名。
Hexo 集成 Gitbook
在执行 hexo g
之前把 gitbook 的静态文件夹放到了hexo 文件夹中,然后执行 hexo g
,这种情况下,gitbook 文件夹中的 json 文件会被解析,而且会提示错误,所以只能把json 文件改为别的后缀名。
看到网上有人说可以在 hexo g 之后,hexo d 之前把文件放到合适的位置。
其实是这样的,hexo 会把 source 文件夹中的所有md文件或者html文件处理一下,如果不希望hexo 处理,可以在站点的配置文件中添加 skip_render
参数。
但是注意,如果想要忽略一个文件夹下的所有文件,应该这么写 skip_render: XXX/**
。
参考:如何不处理source目录下某个子目录的所有文件,仅仅是将其copy到public目录中对应目录?
Hexo 中 source 文件夹下以下划线开头的文件夹会被忽略,不会渲染,也不会放到public文件夹中。
参考:hexo目录结构小探
所以,在 gitbook 生成静态文件之后,必须把默认文件夹名称开头的下划线去掉。
工作流
- 执行
gitbook build
在Gitbook 生成静态文件,然后把默认生成的_book
改名为book
。 - 把 book 文件夹拷贝到hexo博客文件夹下的 source 文件夹中。
- 然后正常提交即可。
注意:如果想修改文件夹的名字,需要修改站点配置文件中的 skip_render
,以及主题配置文件的 menu 中菜单的链接。
TODO - 文章多了,所有文章都显示在左边不太好,探索一下能不能,分顶层目录和子目录,顶层只展示分类,子目录展示每篇文章
TODO - 为搜索添加高亮功能。
TODO - 彻底解决 LaTex 内联公式和行间公式的问题。
Hexo 博客和 Gitbook 如何保持一致的问题
TODO - 如果在 Hexo 博客修改了文章,如果保证 Gitbook 中也是更新的,如果 Hexo 改完,没有及时更新 Gibook 中的内容,如何设计工作流。