GitBook初试🍺

GitBook 是一个基于 Node.js 的命令行工具,可使用 Github/Git 和 Markdown 来制作精美的电子书,GitBook 并非关于 Git 的教程。😜

完成后的成果预览地址:https://zkbook.zam9.com/

1.安装

npm install gitbook-cli -g

报错:

npm WARN checkPermissions Missing write access to /usr/lib/node_modules

原因:安装全局的包,没有权限

解决办法:在安装命令前加上 sudo ,输入用户的登陆密码,提升权限进行安装。

sudo npm install gitbook-cli -g

2.初始化

新建一个文件夹,如 gitbook ,cd 到 gitbook ,然后:

gitbook init
  • README.md: 书的介绍文字,如前言、简介,在章节中也可做为章节的简介。
  • SUMMARY.md: 定制书籍的章节结构和顺序。

3.开始编写你的目录及文件

如你可以在 gitbook 下新建一个 part01 目录与 README.md 和 SUMMARY.md 同级,然后在该目录下新建 md 文件即可。

SUMMARY.md 文件作为书籍的目录结构:

#Summary

- [Introduction](README.md)
- Part I
    - [登录流程介绍](part01/login.md)
    - [test01](part01/test01.md)
    - [test02 参考](part01/test02.md)
        - [概览](part01/test.md)
        - [Test](part01/Test.md)
        - [Test](part01/Test.md)
        - [Test](part01/Test.md)
- Part II
    - [Test](part01/Test.md)
    - [Test](part01/Test.md)
    - [Test](part01/Test.md)

4.预览

  • 执行命令 gitbook serve ,gitbook 会启动一个 4000 端口用于预览。
    gitbook serve

  • 第二种预览方式,运行 gitbook build 命令后会在书籍的文件夹中生成一个 _book 文件夹, 里面的内容即为生成的 html 文件. 我们可以使用下面命令来生成网页而不开启服务器。
    gitbook build

5.关于生成静态HTML侧边栏无法点击问题

百度到的结果是:从 3.0.0 版起, gitbook build 生成的 website 就不支持 local 打开了, 必需要 webserver 开启;实在要完全静态的, 就安装 2.6.7 版吧。使用2.6.7版本,会自动安装并生成,左侧目录可点击,Firefox、Chrome暂无任何问题

解决办法:

gitbook build --gitbook=2.6.7   //生成对应版本的,本地无此版本会自动下载

但是又碰到如下报错:

Error loading version latest: Error: Cannot find module 'internal/util/types'

解决:将 node 版本降低

// 1.安装node管理 n
sudo npm install -g n 

// 2. 降低版本,更新npm
sudo n 6
sudo npm install npm -g

// 3.此时运行gitbook2.6.7的命令即可。
gitbook build --gitbook=2.6.7
// 4. 待转换完成后,将npm版本(例如9.10.0)切回来即可,以免影响其他模块
sudo n 8.16.1

6.关于侧边栏折叠问题和底部打赏功能

如果有多个目录,Gitbook 在浏览器上打开时,默认所有的目录都会打开,当目录比较多时,全部显示不利于阅读。

可以使用插件配置目录折叠,使得打开浏览器时这些目录默认是关闭的。

在执行 gitbook init 主目录下增加 book.json 文件做定制化配置

配置目录折叠功能如下:

{
  "plugins":[
    "expandable-chapters",
    "donate"
  ],
  "pluginsConfig": {
    "donate": {
      "wechat": "https://test1-1256003521.cos.ap-guangzhou.myqcloud.com/images/123444.png",
      "alipay": "https://test1-1256003521.cos.ap-guangzhou.myqcloud.com/images/662.png",
      "title": "",
      "button": "Donate",
      "alipayText": "支付宝捐赠",
      "wechatText": "微信捐赠"
    }
  }
}

然后:

gitbook install

GitBook插件地址:https://plugins.gitbook.com/

⬆️

写的不错,赞助一下主机费

扫一扫,用支付宝赞赏
扫一扫,用微信赞赏
Gogs 2018-04-10
Git基础操作👣 2018-07-10

暂无评论~~