使用GitBook编写项目文档

GitBook简介

GitBook 是使用 GitHub / Git 和 Markdown（或AsciiDoc）构建漂亮书籍的命令行工具（和Node.js库）；

GitBook 可以将您的内容作为网站（可定制和可扩展）或电子书（PDF，ePub或Mobi）输出；

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

GitBook环境安装（需要安装NodeJS环境）

NodeJS安装：

官方下载地址：https://nodejs.org/en/download/

windows下：

直接下载.msi安装包依照向导安装即可，安装完成后在命令行中查看版本验证成功与否。

Linux下：

$ wget https://nodejs.org/dist/v10.9.0/node-v10.9.0-linux-x64.tar.xz    // 下载
$ tar xf  node-v10.9.0-linux-x64.tar.xz       // 解压
$ cd node-v10.9.0-linux-x64/                  // 进入解压目录
$ ./bin/node -v                               // 执行node命令 查看版本
v10.9.0

解压文件的 bin 目录底下包含了 node、npm 等命令，我们可以使用 ln 命令来设置软连接：

$ ln -s /usr/software/nodejs/bin/npm   /usr/local/bin/
$ ln -s /usr/software/nodejs/bin/node   /usr/local/bin/

GitBook安装：

Gitbook是使用NPM来进行安装的，可以在命令行中输入下面的命令进行安装：

$ npm install gitbook-cli -g

gitbook-cli 是 GitBook 的一个命令行工具。它将自动安装所需版本的 GitBook 来构建一本书，

安装完成之后，你可以使用下面的命令来检验是否安装成功。

$ gitbook -V
CLI version: 2.3.
GitBook version: 3.2.

Gitbook命令行使用

初始化一本书：

gitbook init

在使用 gitbook init 之后本地会生成两个文件 README.md 和 SUMMARY.md ，这两个文件都是必须的，一个为介绍，一个为目录结构。

编辑电子书：

首先，GitBook使用SUMMARY.md文件组织整个内容的目录，比如可以新建 Faq.md 文件，来记录常见问题，并在 SUMMARY.md 文件中添加目录。

# Summary

* [简介](README.md)
* [常见问题](Faq.md)

安装插件:

在book.json文件下配置插件后，执行命令统一安装。

gitbook install

本地预览：

当内容书写完毕后，可以在终端中输入如下命令，实现实时预览。

gitbook serve
gitbook serve ./{book_name}

gitbook serve 命令实际会先调用 gitbook build 编译书籍，完成后打开 web 服务器，默认监听本地 4000 端口，在浏览器打开 http://localhost:4000 即可浏览电子书。

发布电子书：

gitbook build
gitbook build ./{book_name} --output=./{outputFolde}
gitbook build ./ --log=debug --debug

当电子书内容制作好之后，可以使用如下命令来生成 HTML 静态网页版电子书。该命令会在当前文件夹中生成 _book 文件夹，这个文件夹中的内容就是静态网页版电子书。

使用 --log=debug --debug 可以用来调试，会打印出 stack trace。

查看帮助：

gitbook -h

GitBook项目结构

一个基本的 GitBook 电子书结构通常如下：

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

简单的介绍下每个文件的作用：

book.json：    记录电子书的配置 (可选)

README.md：    前言 或者 电子书的介绍 (必须)

SUMMARY.md：    电子书的目录 (可选)

GLOSSARY.md：    术语表 (可选)

使用语法

　　在Gitbook中所有文字的编写都使用Markdown语法。

README.md:

这个文件相对于是一本Gitbook的简介，比如 :

# Gitbook 使用入门

> GitBook 是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书。

SUMMARY.md:

这个文件相对于是一本书的目录结构，比如 :

* [介绍](README.md)
* [基本安装](installation/README.md)
   * [Node.js安装](installation/nodejs-install.md)
   * [Gitbook安装](installation/gitbook-install.md)
   * [Gitbook命令行速览](installation/gitbook-cli.md)
* [图书项目结构](book/README.md)
   * [README.md 与 SUMMARY编写](book/file.md)
   * [目录初始化](book/prjinit.md)
* [图书输出](output/README.md)
   * [输出为静态网站](output/static.md)
   * [输出PDF](output/pdfandebook.md)
* [发布](publish/README.md)
   * [发布到Github Pages](publish/gitpages.md)
   * [发布到公司文档服务器](publish/companyserver.md)
* [结束](end/README.md)

book.json:

这个文件保存对Gitbook的配置。

变量	描述
root	包含所有图书文件的根文件夹的路径，除了 book.json
structure	指定自述文件，摘要，词汇表等的路径
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” 的条件

插件与主题:

插件及其配置也在 book.json 中指定。有关详细信息。

自 3.0.0 版本开始，GitBook 可以使用主题。有关详细信息，请参阅  the theming section 。