Gitbook 简易入门

Published on 2015 - 02 - 10

Node.js 是一个基于Chrome JavaScript 运行时建立的一个平台, 用来方便地搭建快速的, 易于扩展的网络应用· Node.js 借助事件驱动, 非阻塞 I/O 模型变得轻量和高效, 非常适合 run across distributed devices 的 data-intensive 的实时应用

Node.js的安装,请移步这里:

在Windows、MacOS X与Linux中安装Node.js

安装完成这后,你可以在终端模式下检验一下:

$ node -v
v0.10.28

看到些提示,就表示你已成功安装上了 Node.js

Gitbook安装

Gitbook是从NPM安装的,命令行:

$ npm install gitbook -g

安装完之后,你可以检验下是否安装成功:

$ gitbook -V
0.4.2

如果你看到了与上面类似的版本信息,则表示你已成功完装上了Gitbook。

Gitbook命令行速览

Gitbook是一个命令行工具,使用方法:

本地预览

$ gitbook serve ./图书名称

输出一个静态网站

$ gitbook build ./repository --output=./outputFolder

查看帮助

$ gitbook -h

Usage: gitbook [options] [command]

Commands:

build [options] [source_dir] Build a gitbook from a directory
serve [options] [source_dir] Build then serve a gitbook from a directory
pdf [options] [source_dir] Build a gitbook as a PDF
ebook [options] [source_dir] Build a gitbook as a eBook
init [source_dir]      Create files and folders based on contents of SUMMARY.md

Options:

-h, --help     output usage information
-V, --version  output the version number

图书项目结构

README.mdSUMMARY.md是Gitbook项目必备的两个文件,也就是一本最简单的gitbook也必须含有这两个文件,它们在一本Gitbook中具有不同的用处。

README.md 与 SUMMARY编写

README.md

这个文件相当于一本Gitbook的简介。
SUMMARY.md

这个文件是一本书的目录结构,使用Markdown语法,如我们这本书的SUMMARY.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)

列表加链接,链接中可以使用目录,也可以不必使用。

目录初始化

当这个目录文件创建好之后,我们可以使用Gitbook的命令行工具将这个目录结构生成相应的目录及文件:

$ gitbook init
$ ls
LICENSE    SUMMARY.md book       output
README.md      howtouse   publish
$ tree .
.
├── LICENSE
├── README.md
├── SUMMARY.md
├── book
│   ├── README.md
│   ├── file.md
│   └── prjinit.md
├── howtouse
│   ├── Nodejsinstall.md
│   ├── README.md
│   ├── gitbookcli.md
│   └── gitbookinstall.md
├── output
│   ├── README.md
│   ├── outfile.md
│   └── pdfandebook.md
└── publish
├── README.md
└── gitpages.md

我们可以看到,gitbook给我们生成了与SUMMARY.md所对应的目录及文件。
每个目录中,都有一个README.md文件,相当于一章的说明。

图书输出

本章内容讲述如何将编写好的图书输出为我们所需要的格式。目前为止,Gitbook支持如下输出:

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

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

输出为静态网站

你有两种方式输出一个静态网站:

本地预览时自动生成
当你在自己的电脑上编辑好图书之后,你可以使用Gitbook的命令行进行本地预览:

$ gitbook serve ./图书目录

这里会启动一个端口为4000用于预览的服务器:

$ gitbook serve .
Press CTRL+C to quit ...

Starting build ...
Successfuly built !

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

你可以你的浏览器中打开这个网址:http://localhost:4000

这里你会发现,你在你的图书项目的目录中多了一个名为_book的文件目录,而这个目录中的文件,即是生成的静态网站内容。

使用build参数生成到指定目录。

与直接预览生成的静态网站文件不一样的是,使用这个命令,你可以将内容输入到你所想要的目录中去:

$ mkdir /tmp/gitbook
$ gitbook build --output=/tmp/gitbook
Starting build ...
Successfuly built !
$ ls /tmp/gitbook/
LICENSE           howtouse          manifest.appcache search_index.json
book              imgs              output
gitbook           index.html        publish

无论哪种方式,你都可以将这个文件打包,然后把你的书发给你的朋友们了!

输出PDF

输入为PDF文件,需要先使用NPM安装上gitbook pdf

$ npm install gitbook-pdf -g

我在安装这个模块的时候,当下载一个名为phantomjs的包时,出现请求未能响应的情况,这时,你可以到这个应用的网站上去下载:
http://phantomjs.org/
这个包的安装方法,请看网站上的说明

然后,使用下面的命令,可生成PDF文件了:

$ gitbook pdf ./图书目录

如果你在图书目录内容,也可以这样做:

$ gitbook pdf .

然后,你会发现你的目录里多了一个名为book.pdf的文件,就是它了!

但是,我在测试的时候发现,生成的PDF文件在排版上不是合理,如页面的边距明显过小,如果是图文混排的话,整个版面感觉有些零乱。

发布到github pages

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

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

经过这一步处理,已经创建好gh-pages分支了,有了这个分支,Github会自动为你分配一个访问网址:

http://USERNAME.github.io/book

你可以在项目页面右下settings中看到:

当然,由于我们内容还没有上传所以你点开链接,也只是一个404页面。

同步静态网站代码到分支

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

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

然后,等十来分钟的样子,你就可以访问到你的在线图书了。而后,每次修改之后,都可以将生成的代码Copy到book-end目录,再Push一下就OK了。

当然,对于gh-pages存放问题,你也可以直接在master分支目录中直接git clone gh-pages分支,假如名称为book-end,然后修改一下.gitignore文件,将book-end/添加进去,这样主分支就不会理会book-end内容的修改了。

笔者曾试过直接使用gitbook build --output=/PATH/book-end这个方式输出到gh-pages分支目录中,但发现gitbook在build的时候,相当于删除存在的这个目录,然后再新建目录,再写入内容,原来的git信息会完全删除掉,显示这不是我们想要看到的,所以只能Copy才行。

结束

这是笔记在试用了一天的Gitbook之后记录下来的,觉得这真是一个伟大的发明,以前使用过Sphinx,可以使用在线工具直接生成一个静态网站。而后来我喜欢上了更简单的Markdown语法,却发现对于阅读类似于书籍的Markdown时,得自己一个个的文件点开才能进行阅读。

而gitbook则是将这些独立的文件组合起来,做成一个静态站或是生成PDF,且是真正精美的,一下便喜欢上了。