Gitbook 相关

发表于 | 更新于 | 阅读次数：

Gitbook 相关。

平时写的文章都是一篇一篇的，有点散，如果使用 Gitbook 的形式组织起来，能够把同类的文章聚在一起，学习或者复习的效率会更高一些。

教程

官方教程

Gitbook 官方网站现在主要是宣传他们的文档托管，对于他们开发的 npm 平台上的工具的介绍基本没有，但是在 npm 上有对于其工具的官方介绍。

gitbook - npm

gitbook-cli - npm

除了官方插件，还有很多第三方插件，可以到 npm 官网去查。

github 官方仓库：GitbookIO/gitbook: Modern documentation format and toolchain using Git and Markdown

第三方教程

Gitbook 使用教程 - einverne

GitBook 使用教程 - blankj - 掘金

GitBook 简明教程 - chengwei

如何优雅地使用Gitbook

GitBook 插件

个人经验

常用命令

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 的对比

  1. 速度

    katex 速度快得多，网上有一个测试：KaTeX and MathJax Comparison Demo

  2. 可复制性

    偶尔一些比较简单的公式，MathJax 复制之后还是一行的，但是 katex 复制之后就是每个字符占一行。但是复杂的公式，直接复制，效果都相当于没有。

    MathJax 提供常看 LaTex 命令的功能，直接在公式上点击右键打开菜单选择即可。Katex 不支持这个功能。

    所以，从这个角度来讲，MathJax 显然更好一些，因为文章的读者可能需要复制某个公式，但是使用 Katex 就很不方便。

Gitbook 存在的一些问题

下面列出的问题，有可能是存在解决方案但是我不知道的，暂且记录下来。

mathjax

  1. 官方的 mathjax 不支持单个 $ 括起来的数学公式，只支持 $$ 括起来的数学公式。不能很好的和 Typora 语法兼容。

    把 node_moudles 文件夹中的 gitbook-plugin-mathjax 中的 index.js 文件修改一下就可以实现单美元符号的功能，但是双美元符号会出现问题，还没找到兼容的方法。

    把 gitbook-plugin-katex 中的 index.js 修改了之后，暂时可以用。过程中遇到了一些 “EOF” bug 之类的，是因为 Typora 向公式中添加了一些 ZERO-WIDTH-SPACE，导致产生错误，删除了就好了。

    github上的一些讨论：

    Changing the math deliminator

    inline formula notation issue

  2. 切换文章的时候好像是通过 js 重载页面的，mathjax 不会被加载，必须要手动刷新才可以触发 mathjax 的渲染。【经测试，这个问题可以通过把公式引擎换成katex来解决，但是还是需要 $$ 双美元符号括起来。】

共性问题

  1. 不支持类似 hexo 的 front-matter 来生成 URL，也就是生成的 HTML 的名称和文件名是一样的。而hexo中可以通过urlname自己指定一篇文章渲染之后的html的文件名。
  2. 图片加载问题。
  3. 点击每篇文章最上边的标题会回到 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目录结构小探

Hexo之坑：如何让Hexo不渲染某些文件

所以，在 gitbook 生成静态文件之后，必须把默认文件夹名称开头的下划线去掉。

工作流

  1. 执行 gitbook build 在Gitbook 生成静态文件，然后把默认生成的 _book 改名为 book。
  2. 把 book 文件夹拷贝到hexo博客文件夹下的 source 文件夹中。
  3. 然后正常提交即可。

注意：如果想修改文件夹的名字，需要修改站点配置文件中的 skip_render，以及主题配置文件的 menu 中菜单的链接。

TODO - 文章多了，所有文章都显示在左边不太好，探索一下能不能，分顶层目录和子目录，顶层只展示分类，子目录展示每篇文章

TODO - 为搜索添加高亮功能。

TODO - 彻底解决 LaTex 内联公式和行间公式的问题。

Hexo 博客和 Gitbook 如何保持一致的问题

TODO - 如果在 Hexo 博客修改了文章，如果保证 Gitbook 中也是更新的，如果 Hexo 改完，没有及时更新 Gibook 中的内容，如何设计工作流。