Markdown + Gitbook

优质

小牛编辑

137浏览

2023-12-01

使用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章](c1.md)  
  *  [第1节](c1s1.md)  
  *  [第2节](c1s2.md)  
*  [第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文件，其格式如下：

{  "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.jpg和cover_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后还能自动编译，生成多种电子书格式。如果你的书极为畅销的话，还能获取到捐赠或购买，没有理由不尝试的呀。

注

来源：