GitBook介绍

gitbook网站是一个简单的个人在线书籍网站,在这里可以把自己的文档整理成书籍发布出来,便于阅读。

gitbook官网:https://www.gitbook.com/

本文主要讲解在gitbook网站上发布一个书籍文档和使用gitbook提供的工具在本地开发一个书籍文档部署到自己的服务上

GitBook特性

GitBook是一个基于 Node.js 的命令行工具,可使用 Github/Git 和 Markdown 来制作精美的电子书,GitBook 并非关于 Git 的教程。
GitBook支持输出多种文档格式:

  • ·静态站点:GitBook默认输出该种格式,生成的静态站点可直接托管搭载Github Pages服务上;
  • ·PDF:需要安装gitbook-pdf依赖; ·eBook:需要安装ebook-convert; ·
  • 单HTML网页:支持将内容输出为单页的HTML,不过一般用在将电子书格式转换为PDF或eBook的中间过程;
  • ·JSON:一般用于电子书的调试或元数据提取。

GitBook安装教程

安装 Node.js(已安装跳过)

GitBook 是一个基于 Node.js 的命令行工具,下载安装 Node.js,安装完成之后,你可以使用下面的命令来检验是否安装成功。

node -v
v7.7.1

安装 GitBook

输入下面的命令来安装 GitBook。

npm install gitbook-cli -g
或者(前提使用下面的命令安装了cnpm):cnpm install gitbook-cli -g

此处建议用户使用淘宝镜像,默认的npm速度较慢,cnpm安装命令:

npm install -g cnpm --registry=https://registry.npm.taobao.org

安装完成之后,你可以使用下面的命令来检验是否安装成功。注意-V是大写的

gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

编辑器

可以用 VsCode、Typora 等自己喜欢的来编辑。

先睹为快

GitBook 准备工作做好之后,我们进入一个你要写书的目录,也就是项目文件夹,输入如下命令。

gitbook init

显示下面的几行语句就成功了
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

可以看到他会创建 README.md 和 SUMMARY.md 这两个文件,README.md 应该不陌生,就是说明文档,而 SUMMARY.md 其实就是书的章节目录,其默认内容如下所示:

# Summary

* [Introduction](README.md)

接下来,我们输入 $ gitbook serve 命令,然后在浏览器地址栏中输入 http://localhost:4000 便可预览书籍。
20191013164141398.png

运行该命令后会在书籍的文件夹中生成一个 _book 文件夹, 里面的内容即为生成的 html 文件,我们可以使用下面命令来生成网页而不开启服务器。

gitbook build

下面我们来详细介绍下 GitBook 目录结构及相关文件。

目录结构

GitBook 基本的目录结构如下所示:

.
├── book.json
├── README.md
├── SUMMARY.md
├── chapter-1/
|   ├── README.md
|   └── something.md
└── chapter-2/
    ├── README.md
    └── something.md

下面我们主要来讲讲 book.json 和 SUMMARY.md 文件。

book.json
该文件主要用来存放配置信息。
相信很多节点自己也能猜到是什么意思,我还是简单介绍下吧。

title
本书标题

author
本书作者

description
本书描述

language
本书语言,中文设置 "zh-hans" 即可

gitbook
指定使用的 GitBook 版本

styles
自定义页面样式

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

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

plugins
配置使用的插件

pluginsConfig
配置插件的属性

SUMMARY.md
这个文件主要决定 GitBook 的章节目录,它通过 Markdown 中的列表语法来表示文件的父子关系,下面是一个简单的示例:

# Summary

* [Introduction](README.md)
* [Part I](part1/README.md)
    * [Writing is nice](part1/writing.md)
    * [GitBook is nice](part1/gitbook.md)
* [Part II](part2/README.md)
    * [We love feedback](part2/feedback_please.md)
    * [Better tools for authors](part2/better_tools.md)