AI 助理
备案控制台
开发者社区 开发与运维 文章 正文

gitbook 快速入门

2022-12-17 150
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： gitbook 快速入门

Gitbook 快速入门

文章目录

1. 介绍

Gitbook 是一款优秀的 基于 Node.js 的开源文档管理工具，具有丰富的开源插件。

GitBook 支持 Markdown 和 AsciiDoc 两种语法格式，能够输出 html，pdf，epub，mobi 等多种格式。

2. 条件

nodejs 安装 node一定要安装10.X版本，否则报如下错误：

CLI version: 2.3.2
Installing GitBook 3.2.3
/usr/local/node/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
      if (cb) cb.apply(this, arguments)
                 ^
TypeError: cb.apply is not a function
    at /usr/local/node/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
    at FSReqCallback.oncomplete (fs.js:193:5)

系统：ubuntu：18.04

3. gitbook 安装

$ npm install gitbook-cli -g
/usr/local/node/bin/gitbook -> /usr/local/node/lib/node_modules/gitbook-cli/bin/gitbook.js
+ gitbook-cli@2.3.2
added 578 packages from 672 contributors in 191.662s
#找到gitbook命令位置
$ ls /usr/local/node-v10.24.0-linux-x64/bin/
gitbook            node               node_modules/      npm                npx                package-lock.json
#添加软连接
$ ln -s /usr/local/node-v10.24.0-linux-x64/bin/gitbook /usr/local/bin/
$ ln -s /usr/local/node-v10.24.0-linux-x64/bin/book /usr/local/bin/
$ gitbook -V
CLI version: 2.3.2
Installing GitBook 3.2.3
gitbook@3.2.3 ../../../../tmp/tmp-117466TKiRhUq3ov0O/node_modules/gitbook
├── escape-html@1.0.3
├── escape-string-regexp@1.0.5
├── destroy@1.0.4
├── ignore@3.1.2
├── bash-color@0.0.4
├── gitbook-plugin-livereload@0.0.1
├── cp@0.2.0
├── nunjucks-do@1.0.0
├── graceful-fs@4.1.4
├── github-slugid@1.0.1
├── direction@0.1.5
├── q@1.4.1
├── spawn-cmd@0.0.2
├── gitbook-plugin-fontsettings@2.0.0
├── open@0.0.5
├── is@3.3.0
├── object-path@0.9.2
├── extend@3.0.2
├── json-schema-defaults@0.1.1
├── gitbook-plugin-search@2.2.1
├── jsonschema@1.1.0
├── crc@3.4.0
├── urijs@1.18.0
├── semver@5.1.0
├── immutable@3.8.2
├── front-matter@2.3.0
├── npmi@2.0.1 (semver@4.3.6)
├── resolve@1.1.7
├── gitbook-plugin-theme-default@1.0.7
├── moment@2.13.0
├── npm@3.9.2
├── dom-serializer@0.1.0 (domelementtype@1.1.3, entities@1.1.2)
├── tmp@0.0.28 (os-tmpdir@1.0.2)
├── error@7.0.2 (xtend@4.0.2, string-template@0.2.1)
├── omit-keys@0.1.0 (isobject@0.2.0, array-difference@0.0.1)
├── mkdirp@0.5.1 (minimist@0.0.8)
├── js-yaml@3.14.1 (esprima@4.0.1, argparse@1.0.10)
├── gitbook-plugin-lunr@1.2.0 (html-entities@1.2.0, lunr@0.5.12)
├── gitbook-plugin-highlight@2.0.2 (highlight.js@9.2.0)
├── gitbook-plugin-sharing@1.0.2 (lodash@3.10.1)
├── i18n-t@1.0.1 (lodash@4.17.21)
├── gitbook-markdown@1.3.2 (kramed-text-renderer@0.2.1, gitbook-html@1.3.3, kramed@0.5.6, lodash@4.17.21)
├── gitbook-asciidoc@1.2.2 (gitbook-html@1.3.3, asciidoctor.js@1.5.5-1, lodash@4.17.21)
├── send@0.13.2 (fresh@0.3.0, etag@1.7.0, statuses@1.2.1, range-parser@1.0.3, ms@0.7.1, depd@1.1.2, mime@1.3.4, debug@2.2.0, http-errors@1.3.1, on-finished@2.3.0)
├── fresh-require@1.0.3 (is-require@0.0.1, shallow-copy@0.0.1, astw@1.3.0, acorn@0.9.0, sleuth@0.1.1, escodegen@1.14.3, through2@0.6.5)
├── rmdir@1.2.0 (node.flow@1.2.3)
├── request@2.72.0 (tunnel-agent@0.4.3, aws-sign2@0.6.0, forever-agent@0.6.1, oauth-sign@0.8.2, is-typedarray@1.0.0, caseless@0.11.0, stringstream@0.0.6, aws4@1.11.0, isstream@0.1.2, json-stringify-safe@5.0.1, tough-cookie@2.2.2, node-uuid@1.4.8, qs@6.1.2, hawk@3.1.3, combined-stream@1.0.8, mime-types@2.1.34, http-signature@1.1.1, form-data@1.0.1, bl@1.1.2, har-validator@2.0.6)
├── read-installed@4.0.3 (debuglog@1.0.1, util-extend@1.0.3, slide@1.1.6, readdir-scoped-modules@1.1.0, read-package-json@2.1.2)
├── cpr@1.1.1 (rimraf@2.4.5)
├── tiny-lr@0.2.1 (parseurl@1.3.3, livereload-js@2.4.0, qs@5.1.0, debug@2.2.0, faye-websocket@0.10.0, body-parser@1.14.2)
├── cheerio@0.20.0 (entities@1.1.2, lodash@4.17.21, css-select@1.2.0, htmlparser2@3.8.3, jsdom@7.2.2)
├── juice@2.0.0 (deep-extend@0.4.2, slick@1.12.2, batch@0.5.3, cssom@0.3.1, cross-spawn-async@2.2.5, commander@2.9.0, web-resource-inliner@2.0.0)
├── chokidar@1.5.0 (async-each@1.0.3, path-is-absolute@1.0.1, inherits@2.0.4, glob-parent@2.0.0, is-glob@2.0.1, is-binary-path@1.0.1, anymatch@1.3.2, readdirp@2.2.1)
└── nunjucks@2.5.2 (asap@2.0.6, yargs@3.32.0, chokidar@1.7.0)
GitBook version: 3.2.3

4. gitbook 创建

$ mkdir gitbook-demo
$ cd gitbook-demo
#使用 gitbook init 初始化书籍目录
$ gitbook init 
warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished 
$ ls 
README.md  SUMMARY.md
#使用 gitbook build 编译书籍
$ 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 ! 
$ ls
_book  README.md  SUMMARY.md
$ ls _book/
gitbook  index.html  search_index.json
$ ls _book/gitbook/
fonts  gitbook.js  gitbook-plugin-fontsettings  gitbook-plugin-highlight  gitbook-plugin-lunr  gitbook-plugin-search  gitbook-plugin-sharing  images  style.css  theme.js
#使用 gitbook serve 编译并预览书籍
$ 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.5s ! 
Starting server ...
Serving book on http://localhost:4000

效果

1832b220aa754cd18c504acc7686a560.png

图中侧栏Introduction的内容正是README.md的内容，SUMMARY.md 是编写界面侧栏的目录结构。

$ cat README.md 
# Introduction
$ cat SUMMARY.md 
# Summary
* [Introduction](README.md)

5. SUMMARY.md

GitBook 使用文件 SUMMARY.md 来定义书本的章节和子章节的结构。文件 SUMMARY.md 被用来生成书本内容的预览表。

SUMMARY.md 的格式是一个简单的链接列表，链接的名字是章节的名字，链接的指向是章节文件的路径。子章节被简单的定义为一个内嵌于父章节的列表。以 # 开头的行为注释被忽略。

GitBook使用一个SUMMARY.md文件来定义文档的菜单。

虽说在官方文档中，它是可选的，但是它相当重要，控制了左边菜单栏的显示内容。它通过 Markdown 中的列表语法来表示文件的父子关系。紧凑型的。


创建一个目录，并编写一个markdown格式的文档

$ mkdir git
$ mv git_training.md git
$ ls
_book  book.json  book.json_bak  git  kubernetes  node_modules  README.md  SUMMARY.md
$ ls git/
1_git_introduce.md  2_git_command.md

编写SUMMARY.md

# Summary
## 前言
* [Introduction](README.md)
## git
* [git 介绍](git/1_git_introduce.md)
  * [git 命令](git/2_git_training.md)

启动

$ gitbook serve

效果：

1832b220aa754cd18c504acc7686a560.png

当 md 文件数量非常多时，我们可以利用 插件 summary 自动生成菜单 summary 文件的介绍。

6. README.md

书本的首页内容默认是从文件 README.md 中提取的。


README.md是 gitbook 最基础的文件之一，它一般用来描述这本书最基本的信息。 它呈现给读者这本书最初的样子，如果内容不够简洁明了，很可能就没有看下去的欲望了。


可以通过 gitbook init 自动创建该文件。


如果这个文件名没有出现在 SUMMARY.md (目录索引文件) 中，那么它会被添加为章节的第一个条目。


如何替代README.md


一些项目更愿意将 README.md 文件作为项目的介绍而不是书的介绍。


大部分代码托管平台将 README.md 自动显示到项目首页，如果你不喜欢这样。 从GitBook >2.0.0 起，就可以在 book.json 中定义某个文件作为README。


删除掉SUMMARY.md文档关于README.md的引用

编写information.md

$ cat information.md 
---
这是一本关于介绍git、github、gitlab、gitbook的书籍。
比起官方的理解，它更接近体验训练。

book.json添加structure参数

book.json
{
    "structure" : {
        "readme" : "information.md"
    }
}

启动

$ gitbook serve

效果：默认的首页

1832b220aa754cd18c504acc7686a560.png

7. book.json

7.1 侧栏添加链接

$ ls
_book  book.json  kubernetes  README.md  SUMMARY.md
$ vim book.json
{
    "author": "zongxun <me@zongxun.cn>",
    "description": "This is a sample book created by gitbook",
    "extension": null,
    "generator": "site",
    "links": {
        "sharing": {
            "all": null,
            "facebook": null,
            "google": null,
            "twitter": null,
            "weibo": null
        },
        "sidebar": {
            "Blog": "https://blog.csdn.net/xixihahalelehehe?spm=1000.2115.3001.5343"
        }
    },
    "output": null,
    "pdf": {
        "fontSize": 12,
        "footerTemplate": null,
        "headerTemplate": null,
        "margin": {
            "bottom": 36,
            "left": 62,
            "right": 62,
            "top": 36
        },
        "pageNumbers": false,
        "paperSize": "a4"
    },
    "plugins": [],
    "title": "GitBook Handbook",
    "variables": {}
}
$ 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.5s ! 
Starting server ...
Serving book on http://localhost:4000

效果，只看到了一个Blog链接。

1832b220aa754cd18c504acc7686a560.png

7.2 添加一个插件

编写book.json添加新theme-comscore颜色插件

$ cat book.json
{
    "author": "zongxun <me@zongxun.cn>",
    "description": "This is a sample book created by gitbook",
    "extension": null,
    "generator": "site",
    "links": {
        "sharing": {
            "all": null,
            "facebook": null,
            "google": null,
            "twitter": null,
            "weibo": null
        },
        "sidebar": {
            "Blog": "https://blog.csdn.net/xixihahalelehehe?spm=1000.2115.3001.5343"
        }
    },
    "output": null,
    "pdf": {
        "fontSize": 12,
        "footerTemplate": null,
        "headerTemplate": null,
        "margin": {
            "bottom": 36,
            "left": 62,
            "right": 62,
            "top": 36
        },
        "pageNumbers": false,
        "paperSize": "a4"
    },
    "plugins": [
     "theme-comscore" 
    ],
    "title": "GitBook Handbook",
    "variables": {}
}

安装插件

gitbook install
info: installing 1 plugins using npm@3.9.2 
info:  
info: installing plugin "theme-comscore" 
info: install plugin "theme-comscore" (*) from NPM with version 0.0.3 
/root/github/gitbook-demo
└── gitbook-plugin-theme-comscore@0.0.3 
info: >> plugin "theme-comscore" installed with success

执行

$  gitbook serve

添加主题插件前：

1832b220aa754cd18c504acc7686a560.png添加主题插件后：

1832b220aa754cd18c504acc7686a560.png

文章标签：
JavaScript
Ubuntu
爱死亡机器人
目录
相关文章
1797461441227635
|
11月前
|
缓存 前端开发 Linux
Composer 快速入门教程
Composer 是 PHP 是 PHP5.3 以上的一个依赖管理工具，你可以在自己的项目中声明所依赖的外部工具库（libraries），Composer 会安装这些依赖的库文件
1797461441227635
1048 0
二进制怪兽
[教程]使用gitbook写书
[教程]使用gitbook写书
二进制怪兽
63 0
theonegis
|
JavaScript 开发工具 git
GitBook新手入门
GitBook是使用Git管理书籍项目，使用Markdown撰写书籍，并使用GitHub和GitBook网站进行托管的一个实用工具。下面简单说一下新手如何使用该强大的工具。
theonegis
133 0
尹正杰
|
2月前
|
JavaScript
文档工具GitBook使用指南
这篇博客提供了GitBook的安装和使用指南，包括如何在本地安装Node.js和GitBook、初始化GitBook项目、生成HTML和电子书格式（PDF、mobi）的文档，以及推荐的相关阅读资源。
尹正杰
51 8
文档工具GitBook使用指南
修己xj
|
12月前
|
资源调度 JavaScript 应用服务中间件
VuePress介绍及使用指南
VuePress是一个基于Vue.js的静态网站生成工具，它专注于以Markdown为中心的项目文档。VuePress具有简单易用的特性，同时提供了强大的自定义和扩展性。
修己xj
175 2
VuePress介绍及使用指南
小马大咖
pnpm使用教程
pnpm使用教程
小马大咖
214 0
苏凉.py
|
存储 Linux 开发工具
Git工具快速入门
Git工具快速入门
苏凉.py
150 0
llsydn
|
监控 JavaScript 前端开发
Grunt快速入门教程
Grunt入门介绍：中文主页 : http://www.gruntjs.net/ Grun是一套前端自动化构建工具，一个基于nodeJs的命令行工具 Grunt它是一个任务运行器
llsydn
121 0
爱死亡机器人
|
机器人
gitbook 插件 阅读更多
gitbook 插件 阅读更多
爱死亡机器人
161 0
huc_逆天
|
Java Unix Shell
Gradle快速入门使用指南 - 安装篇
Gradle快速入门使用指南 - 安装篇
huc_逆天
337 0
Gradle快速入门使用指南 - 安装篇