【Tools】GitBook简明教程

00. 目录

文章目录

00. 目录
01. GitBook简介
02. GitBook安装
03. GitBook使用
04. GitBook命令
05. GitBook配置
06. GitBook插件
07. 在线文档云平台
08. 附录

01. GitBook简介

GitBook是一个使用 Git 和 Markdown 来构建书籍的工具。它可以将你的书输出很多格式：PDF，ePub，mobi，或者输出为静态网页。
GitBook工具链是开源并且完全免费的，它的源码可以在 GitHub 上获取。

02. GitBook安装

2.1 安装npm工具

deng@itcast:~$ sudo apt install npm

2.2 安装GitBook

deng@itcast:~$ sudo npm install gitbook-cli -g

2.3 验证是否安装成功

deng@itcast:~$ gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3

03. GitBook使用

3.1 GitBook初始化

打开一个文件夹 test使用 gitbook init 初始化文件夹，会自动生成两个必要的文件 README.md 和 SUMMARY.md

deng@itcast:~/test$ gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished
deng@itcast:~/test$

文件	说明
README.md	书的介绍文字，如前言、简介，在章节中也可做为章节的简介。
SUMMARY.md	定制书籍的章节结构和顺序。

README.md 和 SUMMARY.md 是 GitBook 制作电子书的必要文件。

3.2 GitBook预览

方式一：通过网络访问

deng@itcast:~/test$ gitbook serve
Live reload server started on port: 35729
Press CTRL+C to quit ...info: 7 plugins are installed
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 0.3s ! Starting server ...
Serving book on http://localhost:4000

在浏览器输入http://ip:4000

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-6NQWiroc-1593573700671)(assets/image-20200701101235013.png)]

方式二：生成静态页面

deng@itcast:~/test$ gitbook build
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 0.4s !
deng@itcast:~/test$

生成.html静态文件，配置后可以直接访问预览

04. GitBook命令

GitBook命令都可以通过shell或者cmd环境下执行。

4.1 安装命令

deng@itcast:~/test$ npm install gitbook-cli -g

4.2 初始化命令

初始化新建一个文件夹，例如新建 test，然后在该目录下执行命令

deng@itcast:~/test$ gitbook init

会自动生成两个必要的文件 README.md 和 SUMMARY.md。

4.3 预览命令

deng@itcast:~/test$ gitbook serve

gitbook会启动一个4000端口用于预览，可以在浏览器打开网址： http://localhost:4000 预览效果。

4.4 编译命令

deng@itcast:~/test$ gitbook build

运行该命令后会在根文件夹生成一个 book 文件夹，包含了书籍的所有 html 文件. 可以使用该命令来生成网页而不开启服务器，也可以将book文件夹部署到服务器上。

4.5 help命令

deng@itcast:~/test$ gitbook --helpUsage: gitbook [options] [command]

输出gitbook的帮助信息

4.6 serve命令

deng@itcast:~/test$ gitbook serve

生成静态网页并运行服务器

4.7 build命令

deng@itcast:~/test$ gitbook build

生成静态网页

deng@itcast:~/test$ gitbook build --gitbook=3.2.3

生成静态网页时指定gitbook的版本，如果本地没有将先下载

deng@itcast:~/test$ gitbook build --log=debug

指定log级别

deng@itcast:~/test$ gitbook build --debug

输出错误信息

4.8 ls命令

deng@itcast:~/test$ gitbook ls
GitBook Versions Installed:* 3.2.3Run "gitbook update" to update to the latest version.
deng@itcast:~/test$

列出所有的gitbook版本

4.9 ls-remote命令

deng@itcast:~/test$ gitbook ls-remote

列出远程可用的gitbook版本

4.10 update命令

deng@itcast:~/test$ gitbook update

更新到gitbook的最新版本

4.11 uninstall命令

deng@itcast:~/test$ gitbook uninstall 3.2.3

卸载对应的gitbook版本

4.12 install命令

deng@itcast:~/test$ gitbook install

安装依赖

05. GitBook配置

变量	描述
root	包含所有图书文件的根文件夹的路径，除了 book.json
structure	指定自述文件，摘要，词汇表等的路径，参考 Structure paragraph.
title	您的书名，默认值是从 README 中提取出来的。在 GitBook.com 上，这个字段是预填的。
description	您的书籍的描述，默认值是从 README 中提取出来的。在 GitBook.com 上，这个字段是预填的。
author	作者名。在GitBook.com上，这个字段是预填的。
isbn	国际标准书号 ISBN
language	本书的语言类型 —— ISO code 。默认值是 en
direction	文本阅读顺序。可以是 rtl （从右向左）或 ltr （从左向右），默认值依赖于 language的值
gitbook	应该使用的GitBook版本。使用 SemVer 规范，并接受类似于 “> = 3.0.0” 的条件。

root

包含所有图书文件的根文件夹的路径， book.json 文件除外。

"root" : "./docs"

structure

指定 Readme、Summary、Glossary 和 Languages 对应的文件名。

title

电子书的书名，默认值是从 README 中提取出来的。在 GitBook.com 上，这个字段是预先填写的。

"title" : "gitbook-notes"

description

电子书的描述，默认值是从 README 中提取出来的。在GitBook.com上，这个字段是预先填写的。

"description" : "C++教程"

author

作者姓名，在GitBook.com上，这个字段是预先填写的

"author" : "Ming Li"

direction

文本的方向。可以是 rtl 或 ltr，默认值取决于语言的值。

"direction" : "ltr"

gitbook

应该使用的GitBook版本。使用SemVer规范，接受类似于 >=3.0.0 的条件。

"gitbook" : "3.0.0",
"gitbook" : ">=3.0.0"

language

Gitbook使用的语言, 版本2.6.4中可选的语言如下： en, ar, bn, cs, de, en, es, fa, fi, fr, he, it, ja, ko, no, pl, pt, ro, ru, sv, uk, vi, zh-hans, zh-tw

"language" : "zh-hans",

links

在左侧导航栏添加链接信息

"links" : {"sidebar" : {"Home" : "https://github.com/json/gitbook-notes"}
}

styles

自定义页面样式，默认情况下各generator对应的css文件

"styles": {"website": "styles/website.css","ebook": "styles/ebook.css","pdf": "styles/pdf.css","mobi": "styles/mobi.css","epub": "styles/epub.css"
}

例如要使 h1、h2 标签有下边框，可以在 website.css 中设置

h1 , h2{border-bottom: 1px solid #EFEAEA;
}

plugins 插件列表

可以在插件前面加-符号删除默认插件，默认五种插件如下，更多插件

highlight：代码高亮
search：导航栏查询功能（不支持中文）
sharing：右上角分享功能
font-settings：字体设置（最上方的"A"符号）
livereload：为GitBook实时重新加载
pluginsConfig 配置插件的属性

综合实例

{"title": "GItBook笔记","description": "GitBook笔记","author": "tom","output.name": "site","language": "zh-hans","gitbook": "3.2.3","root": ".","links": {"sidebar": {"首页": "http://www.json.com"}},"plugins": ["code","-search","search-pro","github","splitter","tbfed-pagefooter","donate","-sharing","sharing-plus","prism","-highlight","styles-less","toggle-chapters","multipart","ancre-navigation"],"pluginsConfig": {"github": {"url": "https://github.com/json"},"code": {"copyButtons": true},"tbfed-pagefooter": {"copyright": "Copyright © lijiam 2019","modify_label": "本书发布时间：","modify_format": "YYYY-MM-DD HH:mm:ss"},"donate": {"wechat": "/assets/images/wxpay.png","alipay": "/assets/images/alipay.png","title": "","button": "赏","alipayText": "支付宝打赏","wechatText": "微信打赏"},"sharing": {"facebook": true,"twitter": true,"weibo": true,"qq": true,"all": ["douban","google","qzone","linkedin"]},"prism": {"css": ["prismjs/themes/prism-solarizedlight.css"],"lang": {"flow": "typescript"}}},"styles": {"website": "assets/styles/website.less","ebook": "assets/styles/ebook.less","pdf": "assets/styles/pdf.less","mobi": "assets/styles/mobi.less","epub": "assets/styles/epub.less"}
}

06. GitBook插件

在根目录下创建book.json文件

6.1 配置

在book.json的plugins参数中添加插件名。

{"plugins": ["mathjax"]
}

6.2 安装

gitbook install#或者
npm install gitbook-plugin-插件名

6.3 重启服务
如果使用gitbook install安装的很慢，建议使用npm init初始化一个package.json文件，然后每个包通过npm命令安装，以后就可以通过npm install一键快速安装依赖包了。

温馨提示：

1、插件一定先要在book.json文件里面plugins中才能生效，如果只是安装了插件，而没配置的话是不会生效的。

2、gitbook命令安装慢，而且是全部插件都安装一遍，如果只安装一个插件的话建议使用NPM命令安装。

6.4 插件列表

配置使用的插件

"plugins": ["-search","back-to-top-button","expandable-chapters-small","insert-logo"
]

其中-search中的 - 符号代表去除默认自带的插件

Gitbook默认自带有5个插件：

插件	说明
highlight	代码高亮
search	导航栏查询功能（不支持中文）
sharing	右上角分享功能
font-settings	字体设置（最上方的"A"符号）
livereload	为GitBook实时重新加载

6.5 插件属性

配置插件的属性例如配置insert-logo的属性：

  "pluginsConfig": {"insert-logo": {"url": "images/logo.png","style": "background: none; max-height: 30px; min-height: 30px"}}

6.6 实用插件

记录一些实用的插件用法：在book.json中添加"plugins"和"pluginConfig"字段。然后执行gitbook install，或者使用NPM安装npm install gitbook-plugin-插件名，也可以从源码GitHub地址中下载，放到node_modules文件夹里（GitHub地址在进入插件地址右侧的GitHub链接）

07. 在线文档云平台

VuePress
看云
语雀
BookStack
docsify
Docute
MinDoc
Wikitten
DokuWiki
MkDocs
Penflip

如果希望托管在平台，请根据项目数量选择使用GitBook或者看云

如果自建，轻量级的推荐docsify，内容多推荐DokuWiki

08. 附录

8.1 GitBook官方网站

网站：https://www.gitbook.com/

8.2 插件博客

网站：https://blog.csdn.net/fghsfeyhdf/article/details/88403548

8.3 MarkDown笔记

网站：https://www.jianshu.com/p/b03a8d7b1719

8.4 参考博客
网站：http://gitbook.hushuang.me/themes/