本文共 7955 字，大约阅读时间需要 26 分钟。
00. 目录
文章目录
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 -VCLI version: 2.3.2Installing GitBook 3.2.3
03. GitBook使用
3.1 GitBook初始化
打开一个文件夹 test使用 gitbook init 初始化文件夹，会自动生成两个必要的文件 README.md 和 SUMMARY.md
deng@itcast:~/test$ gitbook initwarn: 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 serveLive reload server started on port: 35729Press 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 buildinfo: 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端口用于预览，可以在浏览器打开网址： 预览效果。
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 lsGitBook 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. 在线文档云平台
如果希望托管在平台，请根据项目数量选择使用GitBook或者看云
如果自建，轻量级的推荐docsify，内容多推荐DokuWiki
08. 附录
8.1 GitBook官方网站
网站：
8.2 插件博客
网站：
8.3 MarkDown笔记
网站：
8.4 参考博客
网站：转载地址：https://dengjin.blog.csdn.net/article/details/107059577 如侵犯您的版权，请留言回复原文章的地址，我们会给您删除此文章，给您带来不便请您谅解！
发表评论
最新留言
关于作者
