gitbook asciidoc 项目生成PDF 教程

环境

操作系统： win7
npm: 3.10.10

需求

今天在gitbook看elasticsearch权威指南时，发现与官网的有些不一样，或者说官网上的中文文档依然有些错别字或者翻译不对的地方。而gitbook上的源码目前视乎还在更新，但是源码看起来又特难受，于是乎我就折腾怎样将其生成为PDF文件来看。

折腾一晚上总于又眉目啦

步骤

①安装好gitbook环境
②将gitbook项目源码；也就是GitHub项目clone下来。
③安装ebook-convert。
④执行gitbook命令生成PDF

安装gitbook环境

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

所以我们要先安装Node.js。

安装Node.js

这里我就不介绍啦！

安装gitbook

在安装好Node.js之后在命令行中执行如下命令：

npm install gitbook-cli -g

验证安装是否成功：

C:\Users\yutao>npm -v
3.10.10

这里也简单介绍下gitbook命令：

本地预览

C:\Users\lenovo> gitbook serve ./图书名称

输出一个静态网站

C:\Users\lenovo> gitbook build 图书目录 输出目录

上面命令的路径是项目路径的上一层。也就是不要进入到项目文件夹中。

查看帮助

C:\Users\lenovo> gitbook help

build [book] [output]          build a book
--format     Format to build to (Default is website; Values are website, jso
n, ebook)
--log        Minimum log level to display (Default is info; Values are debug
, info, warn, error, disabled)

pdf [book] [output]    build a book to pdf
--log        Minimum log level to display (Default is info; Values are debug
, info, warn, error, disabled)

epub [book] [output]   build a book to epub
--log        Minimum log level to display (Default is info; Values are debug
, info, warn, error, disabled)

mobi [book] [output]   build a book to mobi
--log        Minimum log level to display (Default is info; Values are debug
, info, warn, error, disabled)

serve [book]   Build then serve a gitbook from a directory
--port       Port for server to listen on (Default is 4000)
--lrport     Port for livereload server to listen on (Default is 35729)
--watch      Enable/disable file watcher (Default is true)
--format     Format to build to (Default is website; Values are website, jso
n, ebook)
--log        Minimum log level to display (Default is info; Values are debug
, info, warn, error, disabled)

install [book]         install plugins dependencies

init [directory]       create files and folders based on contents of SUMMARY.m
d

安装 ebook-convert

ebook-convert 下载地址

我下载的是Windows版。

安装一下就可以，记得要启动下，设置书库路径。

clone 项目

我clone的项目是：

git clone git@github.com:elasticsearch-cn/elasticsearch-definitive-guide.git

这里重点来了：
首先，这个项目的文件格式是asciidoc的，网上大部分教程都是Markdown。
这就导致我查阅的资料很少，执行命令时总是报错。

后来我才知道，这种类型格式的项目需要两个文件：
① README.adoc 文件
② SUMMARY.adoc 文件

README.adoc 类似于这本书的介绍。
SUMMARY.adoc 就这本书的目录结构。

这两个文件都需要，书的介绍可以没有，也就是README.adoc这个文件你可以什么都不写空着就行。

但是SUMMARY.adoc是生成PDF时的关键。

编写SUMMARY.adoc有两种方式：

第一种
使用官方格式编写目录：

= Summary

. link:chapter-1/README.adoc[Chapter 1]
.. link:chapter-1/ARTICLE1.adoc[Article 1]
.. link:chapter-1/ARTICLE2.adoc[Article 2]
... link:chapter-1/ARTICLE-1-2-1.adoc[Article 1.2.1]
. link:chapter-2/README.adoc[Chapter 2]
. link:chapter-3/README.adoc[Chapter 3]
. link:chapter-4/README.adoc[Chapter 4]
.. Unfinished article
. Unfinished Chapter

对于我的项目而言就是：

= Summary

. link:00_Getting_started.asciidoc[入门基础]
.. link:010_Intro/05_What_is_it.asciidoc[一切为了搜索]
.. link:010_Intro/10_Installing_ES.asciidoc[安装es]
.. link:010_Intro/15_API.asciidoc[15_API.asciidoc]
//我没有写全，只写了一部分。。。

在执行：

E:\document\elasticsearch-definitive-guide>gitbook pdf ./ ./es.pdf

其中document是我自己创建的一个文件夹，我的项目结构：

执行完了后，项目中就多了个es.pdf 文件。

---

第二种 方法

利用 asciidocfx软件中的PDF导出功能；
SUMMARY.adoc 文件要这么编写：

include::010_Intro/05_What_is_it.asciidoc[]

include::010_Intro/10_Installing_ES.asciidoc[]

include::010_Intro/15_API.asciidoc[]

include::010_Intro/20_Document.asciidoc[]

include::010_Intro/25_Tutorial_Indexing.asciidoc[]

include::010_Intro/30_Tutorial_Search.asciidoc[]

include::010_Intro/35_Tutorial_Aggregations.asciidoc[]

include::010_Intro/40_Tutorial_Conclusion.asciidoc[]

include::010_Intro/45_Distributed.asciidoc[]

include::010_Intro/50_Conclusion.asciidoc[]

再用asciidocfx这个软件打开这个项目并打开定位到SUMMARY.adoc文件后，点击右上方的PDF按钮，等一会就会生成PDF文件。

---

参考地址：

https://tonydeng.github.io/gitbook-zh/gitbook-howtouse/output/pdfandebook.html

https://www.gitbook.com/book/yuzeshan/gitbook-studying/details

https://chrisniael.gitbooks.io/gitbook-documentation/content/format/asciidoc.html

https://yuzeshan.gitbooks.io/gitbook-studying/content/output/pdfandebook.html

https://www.gitbook.com/book/melody/asciidoc/details

https://www.gitbook.com/book/gitbookio/docs-toolchain/details

https://github.com/elasticsearch-cn/elasticsearch-definitive-guide