环境
操作系统: 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
我下载的是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