GitBook 安装以及使用

GitBook 的使用笔记

因为近期想翻译一些英文技术文档和英文技术书籍,需要左右带有目录栏的电子书籍格式,所以找到了 GitBook。

GitBook 是目前最流行的开源书籍写作方案,下面记录一下初次集成使用过程。

本文介绍的是命令行工具使用 GitBook.

本地通过 NPM 安装 GitBook 命令行工具

运行下面的命令进行安装

$ npm install gitbook-cli -g

其中 gitbook-cli 是 gitbook 的一个命令行工具, 通过它可以在电脑上安装和管理 gitbook 的多个版本.

BUT 执行上述命令,我的终端报错:

npm WARN  checkPermissions Missing write access to /usr/local/lib/node_modules
npm ERR! path /usr/local/lib/node_modules
npm ERR! code EACCES
npm ERR! errno -13
npm ERR! syscall access
npm ERR! Error: EACCES: permission denied, access '/usr/local/lib/node_modules'
npm ERR!  { Error: EACCES: permission denied, access '/usr/local/lib/node_modules'
npm ERR!   stack: 'Error: EACCES: permission denied, access \'/usr/local/lib/node_modules\'',
npm ERR!   errno: -13,
npm ERR!   code: 'EACCES',
npm ERR!   syscall: 'access',
npm ERR!   path: '/usr/local/lib/node_modules' }
npm ERR! 
npm ERR! Please try running this command again as root/Administrator.

报错原因是:Mac 安装 npm 的全局包,报错没有权限。

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

$ sudo npm install gitbook-cli -g

安装成功后,执行gitbook -V查看版本信息。此命令会默认同时安装 GitBook。

至此,安装成功。

GitBook 创建以及预览

1.初始化

  1. 打开一个文件夹 MyGitBook,使用 gitbook init 初始化文件夹,会自动生成两个必要的文件 README.md 和 SUMMARY.md。
$ gitbook init
  • README.md: 书的介绍文字,如前言、简介,在章节中也可做为章节的简介。
  • SUMMARY.md: 定制书籍的章节结构和顺序。

README.md 和 SUMMARY.md 是 GitBook 制作电子书的必要文件,可用 gitbook init 命令自动生成。

  1. 在 MyGitBook 文件夹下面增加其他章节下的文件,文件目录如下:
文件目录
  1. GitBook 使用 SUMMARY.md 文件作为书籍的目录结构,可以用来制作书籍目录。
// SUMMARY.md

# Summary
* [Introduction](README.md)
* Part I
    * [从命令行进行测试](Chapter1/CommandLine.md)
    * [Monkey](Chapter1/Monkey.md)
    * [monkeyrunner 参考](Chapter1/MonkeyrunnerReference.md)
        * [概览](Chapter1/MonkeyrunnerSummary.md)
        * [MonkeyDevice](Chapter1/MonkeyDevice.md)
        * [MonkeyImage](Chapter1/MonkeyImage.md)
        * [MonkeyRunner](Chapter1/MonkeyRunner.md)
* Part II
    * [Introduction](Chapter2/c1.md)
    * [Introduction](Chapter2/c2.md)
    * [Introduction](Chapter2/c3.md)
    * [Introduction](Chapter2/c4.md)

2.预览

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

你可以你的浏览器中打开这个网址: http://localhost:4000 预览电子书效果。

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

另外,如果想发布在 GitBook.com ,可以参考:https://segmentfault.com/a/1190000015012209

注意⚠️
当出现执行 gitbook serve 后报错找不到 fontsettings.js ,谷歌了一下,有 issue 在反应这个问题。
其他人的解决办法是降低版本,比如我的版本是GitBook version: 3.2.3 切换至 2.6.7~2.6.4 即可解决。我不倾向降版本。

我个人的解决办法是:如果执行 gitbook serve 后报上述错,那么先执行一次 gitbook build ,成功后再执行 gitbook serve 就不会报错找不到 fontsettings.js 了。

GitBook 插件

当遇到「左侧的目录折叠」这种需求的时候,就用到 GitBook 插件了。

官方获取插件地址: https://plugins.gitbook.com/

安装插件

安装插件只需要在书籍目录下增加 book.json 文件,例如增加 折叠目录 的插件,需要在 book.json 内增加下面代码:

{
    "plugins": ["expandable-chapters-small"],
    "pluginsConfig": {
        "expandable-chapters-small":{}
    }
}

然后终端执行 install 来安装插件即可:

$ gitbook install

其他链接

  1. 去官网注册 GitBook。官网链接>>

  2. 本地安装 GitBook 客户端。 客户端下载链接>>

参考:

推荐阅读更多精彩内容

  • 概述 GitBook 是使用 GitHub / Git 和 Markdown(或AsciiDoc)构建漂亮书籍的命...
    辉这样说阅读 1,048评论 0 4
  • 本文详细讲解了 Gitbook 生成电子书的完整过程,内容包括:安装、命令、配置、文档结构、生成电子书、部署。限于...
    静默虚空阅读 6,150评论 9 133
  • Gitbook是一个命令行工具,可以把你的Markdown文件汇集成电子书,并提供PDF等多种格式输出。你可以把G...
    陳云峰阅读 2,258评论 1 7
  • 序言 首先看下我们要实现的效果是怎么样的。通过下面的图片,可以看到,左边就是书籍目录的导航栏,导航栏的上面还有全局...
    chenHanMao阅读 578评论 1 7
  • 首先先献上 我的 GitBook 地址,可以在我的 博客 导航栏处找到,下面进行相关的介绍。 背景 由于之前都把零...
    Blankj阅读 92,177评论 9 134