Gitbook 制做文档教程（一）- Gitbook 入门及使用 GitBook Editor

1、GitBook 简介

GitBook 是一个基于 Node.js 的命令行工具，可以使用 Github/Git 和 Markdown 来制做精美的电子书、开发文档等。

GitBook支持输出多种文档格式： ·

• 静态站点：GitBook默认输出该种格式，生成的静态站点可直接托管搭载Github Pages服务上；
• PDF：须要安装gitbook-pdf依赖； ·
• eBook：须要安装ebook-convert； ·

 

2、GitBook 安装

 本文以Windows环境安装及使用示例

2.1 安装Node.js

下载Node.js：http://nodejs.cn/download/，选择当前系统合适版本并直接安装

 

2.2 安装Gitbook

打开CMD（管理员模式），输入命令：

npm install gitbook-cli -g

（gitbook-cli 是 GitBook 的一个命令行工具。它将自动安装所需版本的 GitBook 来构建一本书。 执行下面的命令，查看 GitBook 版本，以验证安装成功）

 

2.2 Gitbook初始化

gitbook init

（初始化后，Gitbook默认输出目录位于：C:\Users\XXX\GitBook\Library\Import）

 

3、GitBook 项目

3.1 建立Gitbook项目并对项目初始化

你能够在硬盘任意位置建立项目文件夹，好比新建 D:\book 文件夹用于存放和管理全部项目文档，再在 D:\book 新建项目文件夹，如新建一个Api接口文档项目：D:\book\MyApi

 

建完项目目录，命令行对项目目录执行初始化：

gitbook init D:\book\MyApi

（gitbook init + 项目目录 可对指定的目录执行项目初始化）

 初始化后，能够看到生成两个md文件（markdown格式）：

• README.md ： 电子书的前言或简介 (required) 
• SUMMARY.md：电子书目录 (optional) 

 

3.2 生成项目静态网页

命令行输入：

gitbook build D:\book\MyApi

 

 等待执行结果，完成后能够发现项目目录下多出一个“_book”目录，点击该目录，发现生成以下目录及文件：

•  gitbook
•  index.html
•  search_index.json

 点击 index.html，能够直接打开生成好的静态网页

 

 

3.3 运行WEB服务

 命令行输入：

gitbook serve D:\book\MyApi

 

当命令行显示以下字符时，表示项目WEB服务已开启

• Starting server ...
• Serving book on http://localhost:4000

浏览器输入：http://localhost:4000，便可直接打开项目静态网页

 

4、使用 GitBook Editor

4.1 下载及安装GitBook Editor

咱们能够借助 GitBook Editor 很方便地去编辑和管理GitBook项目文档，下载地址：https://legacy.gitbook.com/editor

下载及安装后打开：

 

 在登陆窗口点击“Do that later”，先不登陆直接使用，以后点击“GitBook Editor”菜单 - “change library path” ，设置项目存放目录，这里咱们选择 D:\book  做为项目存放目录

 

 

 设置好项目目录后点击“+New Book” 建立 文档项目，命名“Api_test”

 

 

 点击“Confirm” 肯定，建立新的文档项目

 

点击右下角“？”按钮，选择Markdown 编辑模式

 

 

 

编辑器总体界面简洁，左侧树形目录可切换章节及文件目录，中间为输入区，右侧为实时预览区，顶部为菜单及文本格式区

点击“Ctrl+s”保存项目，能够在 D:\book\Import\apitest 看到编辑器已自动生成好的项目文件

 

4.2 生成项目静态网页

命令行输入：

gitbook build D:\book\Import\apitest

 

 等待执行结果，完成后能够发现项目目录已生成静态网页文件，点击 D:\book\Import\apitest\_book\index.html，便可打开生成好的网页文件

 

 

4.3 运行WEB服务

命令行输入：

gitbook serve D:\book\Import\apitest

 

当命令行显示以下字符时，表示项目WEB服务已开启

• Starting server ...
• Serving book on http://localhost:4000

浏览器输入：http://localhost:4000，便可直接打开项目静态网页