gitbook-cli早已停止维护,推荐使用其分支honkit

目录

  • 背景
  • 我发现的不同之处
  • gitbook/honkit的快速入手
    • 首先安装honkit
    • 1 初始化电子书
    • 2 写SUMMARY
    • 编写书本配置(信息以及插件)
      • 推荐的latex渲染插件
    • 3 build和serve
    • 打包电子书

背景

  因为gitbook-cli[1]停止维护了,所以在新版本的nodejs环境安装gitbook-cli会出现许多问题,比如TypeError: cb.apply is not a function和gitbook init报TypeError [ERR_INVALID_ARG_TYPE],要么降级到对应的nodejs版本使用(当然可以用版本管理工具,只不过我是在Termux里面版本管理工具架构不支持),要么像前面两个链接里的大佬那样去修改程序代码以使程序正常运行。
  而在搜索gitbook的插件的时候,偶然发现一个叫honkit的东西,发现他是一个仍然在更新的gitbook分支,HonKit[2]的介绍,可以去他的github[2]页面或者文档[3]查看。

我发现的不同之处

  • 默认打开liveloading、highlight、search、lunr、fontsettings、theme-default这些插件,不需要在book.json额外编写开启,否则会报错。
  • 插件无法通过gitbook install ./一键安装,需要用npm install gitbook-plugin-\ --save-dev来安装。可以到npmjs.com去搜索安装,搜索gitbook-plugin-插件名或者honkit-plugin-插件名来查找,前者比较常用,可以按质量Q排序,综合质量和最后更新时间来选择。

gitbook/honkit的快速入手

首先安装honkit

npm install -g honkit --save-dev

  如果-g全局安装插件也要全局安装,如果不加-g那么插件也不加-g,而且每次执行honkit都要在前面加个npx

npx honkit init

1 初始化电子书

  先进入到电子书目录,然后初始化

cd mybook/
honkit init

  然后该目录就会出现README.md、SUMMARY.md,README.md就不说了,主要说一下SUMMARY.md

2 写SUMMARY

  这里放一个简易的目录作为一个例子,这个SUMMARY.md不仅仅是用来看的目录,他还会帮我们自动生成相关的文件,我觉得挺好用的。

# Summary

* [Introduction](README.md)
* 搭建
    * [搭建](deployment/deployment.md)
    * [TypeError: cb.apply is not a function](deployment/TypeError_cb_apply_is_not_a_function.md)
    * [TypeError [ERR_INVALID_ARG_TYPE]: The "data" argument must be](deployment/TypeError_ERR_INVALID_ARG_TYPE_The_data_argument_must_be.md)
* 使用
    * [简介和目录的书写](usage/README_and_SUMMARY.md)
    * [book.json](usage/book_json.md)

  写完之后,再运行一次honkit init即可按照SUMMARY生成相应的目录结构。之后就是编辑涉及到的各个文档。

编写书本配置(信息以及插件)

  书本信息(标题作者等)和插件的配置都是在book.json文件里面配置的,书本信息我就略过了,我现在一般都还不写。
  插件配置的例子如下

{
	"plugins": [
		"sharing",
		"katex-pro",
		"-null"
	]
}

  注意是"plugins"而不是"plugin",带"-"号则标明指定关闭相应插件。npm install gitbook-plugin-katex-pro --save-dev安装插件,那么插件名字就是katex-pro,而不是katex,有时候和readme写的不是很一样

推荐的latex渲染插件

katex-pro: katex轻量,可以单个$符号作为内嵌公式,渲染正常,而且可以使用中文。
mathjax-single-dollar: mathjax功能强大,对比mathjax-pro,这个可以使用单个$符号进行内嵌。当然,mathjax-pro应该也好用。

3 build和serve

  build可以构建电子书,但是serve命令会自动执行build。所以一般直接serve即可。

honkit serve

  运行结果如下

Live reload server started on port: 35729
Press CTRL+C to quit ...

Starting server ...
info: 6 plugins are installed
info: 6 explicitly listed
info: plugin "livereload" is loaded
info: plugin "highlight" is loaded
info: plugin "search" is loaded
info: plugin "lunr" is loaded
info: plugin "fontsettings" is loaded
info: plugin "theme-default" is loaded
info: found 6 pages
info: found 1 asset files
info: >> generation finished with success in 3.4s !
Serving book on http://localhost:4000

  然后访问localhost:4000或者本机ip:4000即可本地或者远程访问该电子书

打包电子书

  电子书可以打包成各种文件格式,比如PDF,gitbook-cli的打包需要下载额外的库,honkit的我还没试过需不需要。更多功能可以去看honkit或者gitbook的文档或者honkti --help

[1] GitbookIO/gitbook-cli - Github
[2] honkit/honkit -Github
[3] honkit的文档

你可能感兴趣的:(linux,gitbook,honkit,笔记,gitbook报错)