• GitBook
    • 支持格式
    • Gitbook项目地址
  • 基本安装
    • Node.js安装
    • Gitbook安装
    • Gitbook命令行速览
  • 图书项目结构
    • README.md 与 SUMMARY编写
      • README.md
      • SUMMARY.md
    • 目录初始化
  • 图书输出
    • 输出为静态网站
    • 输出PDF
  • 发布
    • 发布到github pages
      • 创建仓库与分支
      • 同步静态网站代码到分支
  • 结束

    GitBook

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

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

    支持格式

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

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

    Gitbook项目地址

    • GitBook项目官网：http://www.gitbook.io
    • GitBook Github地址：https://github.com/GitbookIO/gitbook

    基本安装

    本章内容讲述Gitbook的安装及命令行的功能快速预览说明。

    Node.js安装

    GitBook - 图1

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

    Node.js的安装，请移步这里：

    在 Windows、Mac OS X 與 Linux 中安裝 Node.js 網頁應用程式開發環境

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

    1. $ node -v
    2. v0.10.28

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

    Gitbook安装

    Gitbook是从NMP安装的，命令行：

    1. $ npm install gitbook -g

    安装完之后，你可以检验下是否安装成功：

    1. $ gitbook -V
    2. 0.4.2

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

    Gitbook命令行速览

    Gitbook是一个命令行工具，使用方法：

    本地预览

    1. $ gitbook serve ./图书名称

    输出一个静态网站

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

    查看帮助

    1. $ gitbook -h
    3.   Usage: gitbook [options] [command]
    5.   Commands:
    7.     build [options] [source_dir] Build a gitbook from a directory
    8.     serve [options] [source_dir] Build then serve a gitbook from a directory
    9.     pdf [options] [source_dir] Build a gitbook as a PDF
    10.     ebook [options] [source_dir] Build a gitbook as a eBook
    11.     init [source_dir]      Create files and folders based on contents of SUMMARY.md
    13.   Options:
    15.     -h, --help     output usage information
    16.     -V, --version  output the version number

    图书项目结构

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

    README.md 与 SUMMARY编写

    README.md

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

    SUMMARY.md

    这个文件是一本书的目录结构，使用Markdown语法，如我们这本书的SUMMARY.md：

    1. * [基本安装](howtouse/README.md)
    2.  - [Node.js安装](howtouse/Nodejsinstall.md)
    3.  - [Gitbook安装](howtouse/gitbookinstall.md)
    4.  - [Gitbook命令行速览](howtouse/gitbookcli.md)
    5. * [图书项目结构](book/README.md)
    6.  - [README.md 与 SUMMARY编写](book/file.md)
    7.  - [目录初始化](book/prjinit.md)
    8. * [图书输出](output/README.md)
    9.  - [输出为静态网站](output/outfile.md)
    10.  - [输出PDF](output/pdfandebook.md)
    11. * [发布](publish/README.md)
    12.  - [发布到Github Pages](publish/gitpages.md)
    13. * [结束](end/README.md)

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

    目录初始化

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

    1. $ gitbook init
    2. $ ls
    3. LICENSE    SUMMARY.md book       output
    4. README.md      howtouse   publish
    5. $ tree .
    6. .
    7. ├── LICENSE
    8. ├── README.md
    9. ├── SUMMARY.md
    10. ├── book
    11. │   ├── README.md
    12. │   ├── file.md
    13. │   └── prjinit.md
    14. ├── howtouse
    15. │   ├── Nodejsinstall.md
    16. │   ├── README.md
    17. │   ├── gitbookcli.md
    18. │   └── gitbookinstall.md
    19. ├── output
    20. │   ├── README.md
    21. │   ├── outfile.md
    22. │   └── pdfandebook.md
    23. └── publish
    24.     ├── README.md
    25.     └── gitpages.md

    我们可以看到，gitbook给我们生成了与SUMMARY.md所对应的目录及文件。

    每个目录中，都有一个README.md文件，相当于一章的说明。

    图书输出

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

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

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

    输出为静态网站

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

    本地预览时自动生成

    当你在自己的电脑上编辑好图书之后，你可以使用Gitbook的命令行进行本地预览：

    1. $ gitbook serve ./图书目录

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

    1. $ gitbook serve .
    2. Press CTRL+C to quit ...
    4. Starting build ...
    5. Successfuly built !
    7. Starting server ...
    8. Serving book on http://localhost:4000

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

    GitBook - 图2

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

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

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

    1. $ mkdir /tmp/gitbook
    2. $ gitbook build --output=/tmp/gitbook
    3. Starting build ...
    4. Successfuly built !
    5. $ ls /tmp/gitbook/
    6. LICENSE           howtouse          manifest.appcache search_index.json
    7. book              imgs              output
    8. gitbook           index.html        publish

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

    输出PDF

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

    1. $ npm install gitbook-pdf -g

    笔者在安装这个模块的时候，当下载一个名为phantomjs的包时，出现请求未能响应的情况，这时，你可以到这个应用的网站上去下载：

    http://phantomjs.org/

    这个包的安装方法，请看网站上的说明。

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

    1. $ gitbook pdf ./图书目录

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

    1. $ gitbook pdf .

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

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

    发布

    本章内容讲述如何使用Github Pages服务将我们的发布到网络上去。我们假设你已经会使用Git命令和Github的仓库管理。

    发布到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中看到：

    GitBook - 图3

    当然，由于我们内容还没有上传所以你点开链接，也只是一个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，且是真正精美的，一下便喜欢上了。

    本书记录的内容是简单的，甚至有些地方是含糊的，由于水平尚浅，以至于出现错误，还请详解，如果你有好的想法，也欢迎Fork这个项目。