gitbook的使用

---

1 gitbook的安装

GitBook 是一个基于 Node.js 的命令行工具，可使用Github/Git和 Markdown 来制作精美的电子书。
用户首先需要安装 nodejs，以便能够使用npm 来安装gitbook。

1.1 Linux下gitbook的安装

1、安装nodejs

sudo apt-get install nodejs-legacy
# 安装完之后查看
node -v 或 node --version

2、安装npm
当然也可以采用源码的形式安装nodejs但是比较麻烦，需要进行编译，不建议使用编译的方法

sudo apt-get intall npm

3、安装gitbook
gitbook 1.xxx版本是用sudo npm install -g,gitbook 2.xxx版本的安装如下：

sudo npm install gitbook-cli -g

# 安装完之后可以查看版本，检测是否安装成功
shliang@shliang-vm:~$ gitbook -V
CLI version: 2.3.2
GitBook version: 3.2.3

1.2 gitbook编辑器

官方编辑器，下载地址： https://www.gitbook.com/editor

2 gitbook的入门使用

2.1 基础使用

1、创建一个gitbook的工作目录并初始化

>>>mkdir MyGitbook
>>>cd MyGitbook

>>>gitbook init

显示结果如下：

shliang@shliang-vm:~/shliang/learn/1_gitbook_learn/MyGitbook$ gitbook init
warn: no summary file in this book 
info: create README.md 
info: create SUMMARY.md 
info: initialization is finished 
shliang@shliang-vm:~/shliang/learn/1_gitbook_learn/MyGitbook$ 

初始化后的MyGitbook目录中会出现“README.md”和“SUMMARY.md”两个基本文件，说明一下这两个文件的作用：

• README.md：在其中编辑的内容相当与是一本书的简介

例如：

# Gitbook 使用入门


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

本书将简单介绍如何安装、编写、生成、发布一本在线图书。

• SUMMARY.md：在其中编辑的内容相当与是一本书的目录
  例如：

# Summary

* [Introduction](README.md)
* [基本安装](howtouse/README.md)
   * [Node.js安装](howtouse/nodejsinstall.md)
   * [Gitbook安装](howtouse/gitbookinstall.md)
   * [Gitbook命令行速览](howtouse/gitbookcli.md)
* [图书项目结构](book/README.md)
   * [README.md 与 SUMMARY编写](book/file.md)
   * [目录初始化](book/prjinit.md)
* [图书输出](output/README.md)
   * [输出为静态网站](output/outfile.md)
   * [输出PDF](output/pdfandebook.md)
* [发布](publish/README.md)
   * [发布到Github Pages](publish/gitpages.md)
* [结束](end/README.md)

初始化之后查看文件中的内容：

shliang@shliang-vm:~/shliang/learn/1_gitbook_learn/MyGitbook$ cat README.md 
# Introduction

shliang@shliang-vm:~/shliang/learn/1_gitbook_learn/MyGitbook$ cat SUMMARY.md 
# Summary

* [Introduction](README.md)

```ls


2、建立好目录结构之后，再次初始化
在SUMMARY.md文件中写上目录结构，这里的目录结构是通过缩进实现的
```python
shliang@shliang-vm:~/shliang/learn/1_gitbook_learn/MyGitbook$ vi SUMMARY.md 
shliang@shliang-vm:~/shliang/learn/1_gitbook_learn/MyGitbook$ gitbook init
info: create howtouse/README.md 
info: create howtouse/nodejsinstall.md 
info: create howtouse/gitbookinstall.md 
info: create howtouse/gitbookcli.md 
info: create book/README.md 
info: create book/file.md 
info: create book/prjinit.md 
info: create output/README.md 
info: create output/outfile.md 
info: create output/pdfandebook.md 
info: create publish/README.md 
info: create publish/gitpages.md 
info: create end/README.md 
info: create SUMMARY.md 
info: initialization is finished 
shliang@shliang-vm:~/shliang/learn/1_gitbook_learn/MyGitbook$ ls
book  end  howtouse  output  publish  README.md  SUMMARY.md
shliang@shliang-vm:~/shliang/learn/1_gitbook_learn/MyGitbook$ ls book/
file.md  prjinit.md  README.md

生成文件目录结构：

shliang@shliang-vm:~/shliang/learn/1_gitbook_learn/MyGitbook$ tree
.
├── book
│   ├── file.md
│   ├── prjinit.md
│   └── README.md
├── end
│   └── README.md
├── howtouse
│   ├── gitbookcli.md
│   ├── gitbookinstall.md
│   ├── nodejsinstall.md
│   └── README.md
├── output
│   ├── outfile.md
│   ├── pdfandebook.md
│   └── README.md
├── publish
│   ├── gitpages.md
│   └── README.md
├── README.md
└── SUMMARY.md

5 directories, 15 files

可以看到，每个一级目录下都生成了一个文件夹，二级目录则生成一个markdown类型的文件，而且每个目录中，都有一个README.md文件，用于描述这一章的说明。

2.2 生成gitbook图书

目前为止，Gitbook支持如下输出：

• 静态HTML，可以看作一个静态网站
• PDF格式
• eBook格式
• 单个HTML文件
• JSON格式

我们这里着重说下如何输出静态的HTML和PDF文件。

2.2.1 输出为静态的网页

1、输出为静态网页
生成为静态的网页，其实就是生成一个HTML文件，可以直接用浏览器打开，这里我们只是用于测试，就不对每一个目录下的md文件编辑内容啦

gitbook serve gitbook-name

例如，此时需要退回到自己的

cd ..
gitbook serve MyGitbook    

你会发现，在你编辑的gitbook项目的目录中会多一个_book目录，而这个目录中就是生成的本地预览的静态网站内容。

2、使用gitbook build参数
与直接预览生成的静态网站不一样的时，使用这个命令，你可以将内容输出到你想要的目录。

$ gitbook build --output=/tmp/gitbook

无论哪种方式，你都可以将这个静态网站打包，发布到你想要发布的服务器上，或者直接将这个打包文件给阅读者。

2.2.1 输出为pdf文件

输出为PDF文件，需要先安装gitbook pdf

$ sudo npm install gitbook-pdf -g
如果在安装gitbook-pdf时，觉得下载phantomjs包太慢的话，你可以到phantomjs的官方网站上去下载。

http://phantomjs.org/

这个包的安装方式，参考其官网的说明文档。

然后，用下面的命令就可以生成PDF文件了。

$ gitbook pdf {book_name}
如果，你已经在编写的gitbook当前目录，也可以使用相对路径。

$ gitbook pdf .
然后，你就会发现，你的目录中多了一个名为book.pdf的文件。

3 gitbook上传到github上

3.1 先在本地创建仓库

git init
git add . 
git comming -m "第一次提交"
# 在github上创建一个仓库，然后吧仓库的clone链接复制过来
git remote add origin https://github.com/shliang0603/gitbook_test.git
git push -u origin master

https://shliang0603.github.io/gitbook_test/

3.2 在github上创建好仓库之后克隆到本地

1 创建一个gh-pages分支
将生编写好的格式为.md的文件通过Gitbook处理，然后再发布到Github Gages上去。我个人比较喜欢将源码，即.md文件与Github Pages静态文件存放在一个仓库中。.md文件为master分支，而hmtl文件为gh-pages分支。具体流程是这样的：

• 登录到Github，创建一个新的仓库，名称我们就命令为book，这样我就就得到了一个book的空仓库。
• 克隆仓库到本地：git clone https://github.com/shliang0603/gitbook_test.git。
• 创建一个新分支：git checkout -b gh-pages，注意，分支名必须为gh-pages。
• 将分支push到仓库：git push -u origin gh-pages。
• 切换到主分支: git checkout master。

经过这一步处理，我们已经创建好gh-pages分支了，有了这个分支，Github会自动为你分配一个访问网址：https://shliang0603.github.io/gitbook_test/ (在仓库主页的setting中可以看到这个链接)。当然，由于我们内容还没有上传所以你点开链接，也只是一个404页面。

2 同步静态网站代码到分支
下面我们就可以将build好的静态网站代码同步到gh-pages分支中去了：

• 切换出master分支目录。我们需要将gh-pages分支内容存放到另一个目录中去。
• 克隆gh-pages分支：git clone -b gh-pages https://github.com/shliang0603/gitbook_test.git book-end。这步我们只克隆了gh-pages分支，并存放在一个新的目录book-end里面。
• Copy静态多站代码到book-end目录中。
• Push到仓库。

参考：
1、nodejs在不同平台上安装：https://blog.gtwang.org/web-development/install-node-js-in-windows-mac-os-x-linux/

2、gitbook的使用：https://tonydeng.github.io/gitbook-zh/gitbook-howtouse/output/README.html

3、https://blog.csdn.net/cc_want/article/details/83536586

4、windows下安装使用：https://www.jianshu.com/p/cf4989c20bd8

5、https://www.jianshu.com/p/4d814123db82

---

---

♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠ ⊕ ♠