# 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的[官网](http://nodejs.org/#download)上下载安装程序，即可完成Node.js和npm的安装。 **第1步** 通过npm安装Gitbook。 > $ npm install gitbook -g 完成后花10分钟阅读下Gitbook的[帮助文档](http://help.gitbook.io/)。如果你没耐心看手册，那就继续往下读吧 :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制作电子书](http://www.ituring.com.cn/article/127645)，侧重在使用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尺寸1800*2360，cover_small.jpg尺寸200*262。花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后还能自动编译，生成多种电子书格式。如果你的书极为畅销的话，还能获取到捐赠或购买，没有理由不尝试的呀。 ## 注 来源： + [使用Gitbook制作电子书](http://www.ituring.com.cn/article/127645) + [使用GitBook平台发布电子书](http://www.ituring.com.cn/article/127744)