备案控制台
探索云世界
开发者社区 开发与运维 文章 正文

gitbook 快速入门

2022-12-17 103
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介： 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
|
5月前
|
缓存 前端开发 Linux
Composer 快速入门教程
Composer 是 PHP 是 PHP5.3 以上的一个依赖管理工具，你可以在自己的项目中声明所依赖的外部工具库（libraries），Composer 会安装这些依赖的库文件
1797461441227635
548 0
二进制怪兽
|
7月前
[教程]使用gitbook写书
[教程]使用gitbook写书
二进制怪兽
35 0
theonegis
|
8月前
|
JavaScript 开发工具 git
GitBook新手入门
GitBook是使用Git管理书籍项目，使用Markdown撰写书籍，并使用GitHub和GitBook网站进行托管的一个实用工具。下面简单说一下新手如何使用该强大的工具。
theonegis
88 0
修己xj
|
6月前
|
资源调度 JavaScript 应用服务中间件
VuePress介绍及使用指南
VuePress是一个基于Vue.js的静态网站生成工具，它专注于以Markdown为中心的项目文档。VuePress具有简单易用的特性，同时提供了强大的自定义和扩展性。
修己xj
117 2
VuePress介绍及使用指南
苏凉.py
|
存储 Linux 开发工具
Git工具快速入门
Git工具快速入门
苏凉.py
117 0
llsydn
|
监控 JavaScript 前端开发
Grunt快速入门教程
Grunt入门介绍：中文主页 : http://www.gruntjs.net/ Grun是一套前端自动化构建工具，一个基于nodeJs的命令行工具 Grunt它是一个任务运行器
llsydn
88 0
爱死亡机器人
|
机器人
gitbook 插件 阅读更多
gitbook 插件 阅读更多
爱死亡机器人
134 0
爱死亡机器人
gitbook插件 github
gitbook插件 github
爱死亡机器人
106 0
村雨遥
|
JSON JavaScript 数据格式
Gitbook 使用笔记
Gitbook 使用笔记
村雨遥
239 0
Gitbook 使用笔记
AI悦创
手把手教你GitBook使用(二)
详细的记录了一步步搭建自己的电子文档笔记
AI悦创
132 0
手把手教你GitBook使用(二)

热门文章

最新文章

  • 1
    解决关于Windows Defender Antivirus Service自启造成运行python程序时，Windows的cpu和内存占用过高问题
  • 2
    订票系统不再瘫痪 阿里云确认与12306合作
  • 3
    iOS - 手动下架的应用后快速恢复上架
  • 4
    du 和 df以及lsof
  • 5
    库克：苹果不是只做富人生意，还一直坚持让世界变得更好
  • 6
    WiGig无线标准正式开始提供验证 最高可达8Gbps
  • 7
    IBM推出新的16位量子处理器
  • 8
    Android:随笔——对页面的View进行截图
  • 9
    shell MAC 地址 校验
  • 10
    【系统优化】数据库系统load飙高问题解决思路
  • 1
    DataWorks产品使用合集之DataWorks中，如果一个虚拟节点被设置为冻结状态，那么它的所有子节点也将被冻结如何解决
    24
  • 2
    DataWorks产品使用合集之DataWorks发布任务的方法如何解决
    25
  • 3
    DataWorks产品使用合集之DataWorks中，配置DataHub数据源如何解决
    23
  • 4
    Nacos 1.4.1核心功能组件及使用入门
    22
  • 5
    DataWorks产品使用合集之在 DataWorks 中，有一个 MySQL 数据表，数据量非常大且数据会不断更新将这些数据同步到 DataWorks如何解决
    14
  • 6
    基于直方图的图像阈值计算和分割算法FPGA实现,包含tb测试文件和MATLAB辅助验证
    14
  • 7
    DataWorks产品使用合集之在DataWorks中，要实现MySQL数据源的增量同步如何解决
    16

    • 相关课程

    更多
  • C++ 入门教程开发文档
  • Git 基础入门到实战详解
  • Git从入门到进阶
  • Docker完全自学手册图文教程
  • 前端开发框架Bootstrap使用教程
  • ElasticSearch 最新快速入门教程

    • 相关电子书

    更多
  • 阿里巴巴Java开发手册PDF1.2.0版（非最新版）
  • 阿里巴巴Java开发手册PDF1.1.0版（非最新版）
  • 《Java开发手册》2019最新版发布！

    • 相关实验场景

    更多
  • 基于函数计算快速搭建Hexo博客系统
    • 下一篇
    2024年阿里云免费云服务器及学生云服务器申请教程参考