Markdown + Gitbook

使用Gitbook制作电子书

Gitbook是一个命令行工具,可以把你的Markdown文件汇集成电子书,并提供PDF等多种格式输出。你可以把Gitbook生成的HTML发布出来,就形成了一个简单的静态网站。Gitbook还有一个同名的平台(gitbook.io),可以发布和销售电子书,并提供了一个Markdown客户端工具(支持Mac、Windows和Linux)帮助写作。以下是我在使用Gitbook中的笔记。

首先Gitbook和Git/Github都没有什么关系。它只是一个build book的工具而已。但它的Git前缀的确引起了许多人的迷惑,起初我认为至少它也是个和Github类似的Git平台吧,但其实没什么关系,你只要懂几条markdown语法,不必理解任何与Git相关的东西就能用Gitbook了,不要为其名字迷惑。

第0步 安装npm(Node Package Manager)。从node.js的官网上下载安装程序,即可完成Node.js和npm的安装。

第1步 通过npm安装Gitbook。

$ npm install gitbook -g

完成后花10分钟阅读下Gitbook的帮助文档。如果你没耐心看手册,那就继续往下读吧 :D

第2步 了解Gitbook的基本规则。

Gitbook需要2个基本文件:

  • README.md
  • SUMMARY.md

README.md是关于你的书的介绍,而SUMMARY.md中则包含了书目,即章节结构,它的格式大致是:

  1. * [第1章](c1.md)
  2. * [第1节](c1s1.md)
  3. * [第2节](c1s2.md)
  4. * [第2章](c2.md)

剩下的东西就很好理解了,你只需要编写相应章节即可。在编辑完README.md和SUMMARY.md后,你可以运行以下命令:

$ gitbook serve -p 8080 .

Gitbook首先把你的Markdown文件编译为HTML文件,并根据SUMMARY.md生成书的目录。所有生存的文件都保存在当前目录下的一个名为_book的子目录中。完成这些工作后,Gitbook会作为一个HTTP Server运行,并在8080端口监听HTTP请求。

运行以上命令后,打开浏览器,在地址栏输入:http://localhost:8080即可看到你的书页了。

其中位于左侧书目顶部的Introduction一节就编译自README.md,而书目本身自编译自SUMMARY.md。你要在自己的网站上发布新书,只需把_book目录复制到服务器相应目录即可。至此Gitbook的基本用法就介绍完毕。下面简单讨论下Gitbook的其他应用,包括Gitbook的插件、与Github的融合、Gitbook客户端、Gitbook平台,以及Gitbook的问题。

Gitbook的插件支持

Gitbook可以生成HTML,因此它支持一些外部的JavaScript文件嵌入到HTML中,例如Google统计、Disqus评论系统等。以下以页面中嵌入Disqus评论为例。

首先是安装Gitbook的Disqus插件。

$ npm install gitbook-plugin-disqus

然后建立一个book.json文件,其格式如下:

  1. { "plugins": ["disqus"], "pluginsConfig": { "disqus": { "shortName": "NAME-FROM-DISQUS" } } }

把上面的NAME-FROM-DISQUS修改为你在Disqus上的项目名即可。

再次运行命令:

$ gitbook serve -p 8080 .

并刷新浏览器,即可看到附加了Disqus评论的页面。

与Github的融合

Gitbook的博客上说Github提供了对Gitbook的特殊支持,但我没有测试。只是依然把源文件保存在Github上,然后用Gitbook去编译。期待Gitbook做的更好。

Gitbook客户端

Gitbook客户端支持Mac、Windows、Linux。我在Mac和Windows简单尝试了这个客户端,总体而言可以用。但也仅仅是可以用而已。你可以在客户端里编辑Markdown文件,并提供一个实时的预览窗口;可以关联到你的Gitbook账户,并把内容同步到gitbook.io,并为你生成PDF等。说句题外话,如果你要Markdown的客户端的话,飞象马克更好用,至少Vim编辑模式你得支持啊。

Gitbook的问题

Gitbook网站的访问速度很慢。可以在生成_book目录后,把其中的HTML文件和gitbook子目录(包含字体和js文件等)复制到自己的网站上。

Gitbook提供的push功能不能用。push.gitbook.io这个地址无法访问,不知是否是临时性服务故障。

Gitbook生成PDF的中文字体极其难看。万分期待改进。话说Gitbook生存的HTML上的中文非常漂亮。

在我的手机上看Gitbook的页面时,会让浏览器挂掉。

使用Gitbook发布电子书

上次说到用GitBook制作电子书,侧重在使用gitbook这个命令行工具,今天要说的重点是GitBook这个平台。当你把书放到GitBook上后,可以设置书的价格(每笔交易GitBook抽走20%作为佣金),也可以设置为免费,以及接受捐赠。如果你要收费或接受捐赠,则需要一个PayPal账户。在开始前,我要友情提示一句,在国内访问GitBook的速度很慢,通过VPN访问才好。

第-1步 用git这个源代码管理工具来管理你的Markdown文件。最好有个GitHub账户,这样每次push到GitHub时,GitBook都会自动为你的更新build新的版本(同时生成HTML、PDF、ePUB、MOBI这4个版本)。

第0步 注册一个GitBook帐号。

第1步 在GitBook添加一本书,填写书名等基本信息即可。完成后,GitBook会为你生成一个git仓库,其格式为:

https://push.gitbook.io/{author}/{book}.git

author即你的GitBook用户名,book即你的书名,如我创建的书的git仓库:

https://push.gitbook.io/berlinix/guaidanuniversity.git

这样你可以在编写完Markdown后,通过git push同步到GitBook。

第2步 把你本地的Markdown文件push到GitBook。我发现git push时常失败(服务器返回5xx错误),因此还有一种方法就是把你的GitHub项目与GitBook关联。每次push到GitHub时,会通过GitBook的webhook自动同步到GitBook上。

在Book Setting中简单配置一下即可,如我的配置为:berlinix/gdu (GitHub用户名为berlinix,GitHub仓库名为gdu)

在第一次push后,就可以看到你在GitBook上的电子书了,其访问地址为:

http://{author}.gitbooks.io/{book}/

这是你电子书的主页,从这个页面可以直接打开HTML版本,或下载PDF等电子书版本,一般用户也可以为你的书添加评论。如:

http://berlinix.gitbooks.io/guaidanuniversity/

要直接访问HTML版本,可以通过链接:

https://www.gitbook.io/read/book/{author}/{book}

直接访问,如:

https://www.gitbook.io/read/book/berlinix/guaidanuniversity

至此,GitBook平台的基本用法就介绍完毕。下面是我的一些使用经验。

个性化域名

HTML版本的URL很复杂,可以使用个性化域名简化之。在域名注册商那里添加一条CNAME记录即可,如:

CNAME gdu.berlinix.com www.gitbook.io 300

并把gdu.berlinix.com配置到Book Setting中去,这样可以通过简单的gdu.berlinix.com来取代https://www.gitbook.io/read/book/berlinix/guaidanuniversity。同理,电子书的主页也可设置个性化域名,就不再赘述。

删除电子书

同样是在Book Setting中,可以删除电子书。在电子书列表中没有删除接口。

GitBook电子书封面

可以为电子书添加封面。只需添加2个名为cover.jpgcover_small.jpg的两个图片即可。官方建议cover.jpg尺寸18002360,cover_small.jpg尺寸200262。花2元即可在淘宝上找个做封面的人为你制造一个简单的封面,做得好就要花更多一些了 :)

GitBook帐号头像

似乎只接受Gravatar.com的头像。把Gravatar帐号关联过去即可。Gravatar提供的服务是把你的邮箱和头像关联起来,当你在其他网站注册时就不用每次都上传同一个头像,只需简单与Gravatar帐号关联即可。这样替换头像也方便了,一次替换、处处生效。

访问优化

按GitBook的访问速度,如果真让人访问GitBook上的HTML页面真是自寻死路啊,因此最好是把GitBook编译后的HTML放在自己的网站上。同时,为自己网站的HTML生成Disqus支持。例如你可以访问我放到自己服务器后的页面(用手机访问效果也非常好):

http://www.berlinix.com/gdu/index.html

电子书Bug

上次说到GitBook生成PDF的中文字体非常丑陋,另外还有一个问题,那就是生成的PDF可能是残全不全的。我编译后发现内容只剩一半。我已邮件过去报告这个Bug,还在等回信 :)

总体而言,GitBook还是很好玩,比起其他写作平台而言,要自由、简单,并舒服得多,可以用Vim编辑,支持Markdown语法,用git管理,关联GitHub后每次push后还能自动编译,生成多种电子书格式。如果你的书极为畅销的话,还能获取到捐赠或购买,没有理由不尝试的呀。

来源: