# 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)