GitBook 3.2.3入门

Posted 2020-12-03 gjb724332682

简介

GitBook 是一个基于 Node.js 的命令行工具，可使用 GitHub / Git、Markdown、AsciiDoc来制作精美的电子书。GitBook 可以将文档作为静态网站或电子书（PDF，ePub或Mobi格式）输出。

GitBook.com 是使用 GitBook 格式创建和托管图书的在线平台，它提供托管，协作功能和易于使用的编辑器。

本文示例运行的系统为CentOS Linux release 7.4.1708，nodejs版本为v8.11.3。

 

安装nodejs

访问nodejs官网，下载nodejs，下载后的文件名为node-v8.11.3-linux-x64.tar.xz。

1.执行 tar -Jxvf node-v8.11.3-linux-x64.tar.xz，将nodejs解压到当前目录。

2.需要创建软链接，执行 ln -s /usr/local/mine/node-v8.11.3-linux-x64/bin/node /usr/local/bin/node、ln -s /usr/local/mine/node-v8.11.3-linux-x64/bin/npm /usr/local/bin/npm。

 

安装GitBook

1.执行 npm install gitbook-cli -g安装GitBook命令行工具，自动选择版本，同时也会安装GitBook。

2.安装完成后，可以在nodejs目录里的bin目录下看到gitbook软连接文件，执行 ln -s /usr/local/mine/node-v8.11.3-linux-x64/bin/gitbook /usr/local/bin/gitbook，让该命令全局可用。

npm命令的-g选项是指全局安装，将模块安装到全局目录中，全局目录可以用npm config get prefix 命令获取以及用npm config set prefix ""命令设置，不加-g则是将模块下载到当前命令行所在目录。

npm update gitbook-cli -g是更新命令，npm uninstall gitbook-cli -g是卸载命令。

 

GitBook命令

gitbook -h显示GitBook 帮助信息，gitbook help显示GitBook可用命令。

GitBook可以在本地安装多个版本并在执行命令的时候指定某个版本，如果指定的版本还没安装就会自动下载安装，下载后的GitBook会被放到~/.gitbook目录下。相关操作有：

gitbook ls：列出本地已安装的gitbook版本

gitbook current：列出当前活动的gitbook版本

gitbook ls-remote：列出远程可以下载安装的gitbook版本

gitbook fetch [version]：下载安装某个gitbook版本

gitbook uninstall [version]：卸载某个gitbook版本

gitbook update：更新到最新的gitbook版本

如 gitbook -v 4.0.0-alpha.6 current会显示GitBook version is 4.0.0-alpha.6，而gitbook -V会显示gitbook和gitbook cli的运行版本。

 

初始化GitBook

1.执行 mkdir gitbook-demo && cd gitbook-demo 创建一个gitbook-demo目录并进入到该目录。

2.执行gitbook init 初始化GitBook，会在当前目录下生成 README.md 和 SUMMARY.md文件。SUMMARY.md是GitBook的目录文件。README.md是电子书介绍文件，必须存在。

也可以先手动创建SUMMARY.md，再执行gitbook init，如果SUMMARY.md中配置的文件夹和文件不存在，就会自动创建文件夹和文件，已经存在的文件夹和文件不会被覆盖。一般情况下是先在gitbook-demo目录下执行gitbook init，然后将要制作文档的md文件放到gitbook-demo里，接着再修改SUMMARY.md。

gitbook init的更多用法参考gitbook help。

 

生成静态网站

在gitbook-demo目录下执行 gitbook build，会在gitbook-demo目录下生成一个 _book 目录，里面的内容为静态网站的文件，可以将 _book 目录下的文件拷贝到nginx、httpd等web服务器内，也可以使用gitbook serve命令启动一个web服务，默认端口是4000。

gitbook build和gitbook serve的更多用法参考gitbook help。

 

GitBook目录结构

基本结构如下：

├── book.json

├── README.md

├── SUMMARY.md

├── chapter-1/

| ├── README.md

| └── something.md

└── chapter-2/

├── README.md

└── something.md

book.json：全局配置数据 （可选）

README.md：介绍电子书（必须）

SUMMARY.md：目录 （可选）

GLOSSARY.md：词汇、术语列表（可选）

 

SUMMARY.md格式

基本格式为：* [描述](文件路径或者http超链接)。文件路径是相对于SUMMARY.md所在的目录的。

支持多级目录，每级目录多缩进4个空格。例如：

* [介绍](README.md)

* [概述](index.md)

* [接口](api.md)

* [注意事项](note.md)

 

GLOSSARY.md格式

基本格式是一组h2标题加上描述，在其他页面用到这些词汇时会突出显示，鼠标放上去就会显示术语描述。术语暂不支持中文。

例如：

## test

测试定义

 

book.json格式

GitBook 允许使用灵活的配置自定义电子书，这些选项在 book.json 文件中指定，格式为json。

root：包含除了 book.json外的所有电子书文件的根目录。

structure：指定readme, summary, glossary和 languages的文件名，参考 Structure paragraph。

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

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

author：作者名。在GitBook.com上，这个字段是预填的。

isbn：国际标准书号 ISBN。

language：本书的语言类型 ，默认值是 en。

direction：文本阅读顺序，可以是 rtl （从右向左）或 ltr （从左向右），默认值依赖于 language 的值。

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

 

Structure paragraph

除了 root 属性之外，还可以指定readme, summary, glossary和 languages 的文件名，而不是使用默认名称，如README.md。这些文件必须在项目的根目录下，不接受的路径。

structure.readme：readme 文件名（默认值是 README.md ）

structure.summary：summary 文件名 (默认值是 SUMMARY.md)

structure.glossary：glossary 文件名(默认值是 GLOSSARY.md)

structure.languages：languages 文件名 (默认值是 LANGS.md)