使用Gitbook寫開源書籍，過一把做家癮

• 歡迎關注http://quanke.name/
• 轉載請註明出處，謝謝

初級（適合沒有編程基礎的童鞋看）

使用GitBook Editor 寫開源書籍

這個是gitbook官方出的編輯器，使用簡單

首先下載GitBook Editor

下載地址：https://www.gitbook.com/editor

支持Mac、Linux、Windows

安裝

Windows

• 下載gitbook-win.zip；
• 解壓；
• 打開GitBook.exe安裝；

Mac

• 下載 gitbook-mac.dmg安裝便可

Linux

• 下載 gitbook-linux32.tar.gz
• 使用tar -xvzf gitbook-linux32.tar.gz解壓
• 運行腳本 cd GitBook && ./install.sh安裝

使用

安裝完成以後，若是有github帳號直接，登陸，可是用github登陸以後也須要設置gitbook的郵箱和密碼，等會兒要用到，沒有帳號的直接註冊就好；

登陸後，能夠直接在gitbook上建立書籍，建議在gitbook網站上建立書籍，而後經過GitBook Editor clone 下來；

clone 下來以後 能夠直接寫書了，先在感受是否是特別簡單？別急，爲了更爽的寫做還須要繼續看看下面。

怎麼和github同步？

若是沒有github帳號，先註冊，以後綁定github帳號 https://www.gitbook.com/@quanke/settings#social（把鏈接中的quanke修改成本身的用戶名）

若是綁定了了github帳號，須要設置權限，https://www.gitbook.com/@quanke/settings#github（把鏈接中的quanke修改成本身的用戶名）， Reconnect GitHub Account 選擇 With access to public repositories

當受權好了以後，咱們來到書的設置（ Settings ）頁面，點擊設置github https://www.gitbook.com/book/quanke/vert-x-core-manual-for-java/settings/github（把quanke替換成你的用戶名，把vert-x-core-manual-for-java替換成書名）

若是原來這本書是github裏寫的，直接填入github的地址就好，若是帳號都是新建的，什麼都沒有，那就點擊Export to GitHub （注意填入gitbook的用戶名密碼不是github的）

若是上面的步驟沒問題，點擊 Add webhook 就OK了，給github增長了一個鉤子，也就是說當你的github更新的時候，會告訴gitbook

還有一步很關鍵,在你的GitBook Editor中，打開咱們剛纔clone下來的書，點擊菜單裏的 Book -> Repository Settings ，把這個設置成爲剛纔導到github的地址，以後就能夠在GitBook Editor寫做了。。有什麼不懂的，直接能夠留言問我

進階（適合有編程基礎的童鞋看）

gitbook 安裝

1. 安裝npm 從網站 https://nodejs.org/#download 下載node.js源代碼（點擊綠色的INSTALL）， 解壓

./configure
make
make install

成功執行後，npm就被安裝好了。

2. gitbook 安裝

npm install -g gitbook-cli

gitbook -V

查看gitbook是否安裝成功。

gitbook 使用

1. 根據目錄生成圖書結構

   1.1 README.md 與 SUMMARY編寫

README.md

這個文件至關於一本Gitbook的簡介。

$ mkdir test_gitbook
$ touch README.md

SUMMARY.md

這個文件是一本書的目錄結構，使用Markdown語法， 如咱們這本書的SUMMARY.md：

$ touch SUMMARY.md
$ vim SUMMARY.md

輸入

* [簡介](README.md)
* [第一章](chapter1/README.md)
 - [第一節](chapter1/section1.md)
 - [第二節](chapter1/section2.md)
* [第二章](chapter2/README.md)
 - [第一節](chapter2/section1.md)
 - [第二節](chapter2/section2.md)
* [結束](end/README.md)

1.2 生成圖書結構

當這個目錄文件建立好以後，咱們可使用Gitbook 的命令行工具將這個目錄結構生成相應的目錄及文件：

$ gitbook init
$ tree . #查看創建的目錄和文件

.
├── chapter1
│   ├── README.md
│   ├── section1.md
│   └── section2.md
├── chapter2
│   ├── README.md
│   ├── section1.md
│   └── section2.md
├── end
│   └── README.md
├── README.md
└── SUMMARY.md

咱們能夠看到，gitbook給咱們生成了與SUMMARY.md所 對應的目錄及文件。

每一個目錄中，都有一個README.md文件，至關於一章的說明。

2. 生成圖書

2.1 輸出爲靜態網站

你有兩種方式輸出一個靜態網站：

2.1.1 本地預覽時自動生成

當你在本身的電腦上編輯好圖書以後，你可使用Gitbook 的命令行進行本地預覽：

$ gitbook serve .

而後瀏覽器中輸入 http://localhost:4000 就能夠預覽生 成的以網頁形式組織的書籍。

這裏你會發現，你在你的圖書項目的目錄中多了一個名爲 _book的文件目錄，而這個目錄中的文件，便是生成的靜態 網站內容。

使用build參數生成到指定目錄 與直接預覽生成的靜態網站文件不同的是，使用這個命令， 你能夠將內容輸入到你所想要的目錄中去：

$ mkdir /tmp/gitbook
$ gitbook build --output=/tmp/gitbook

2.2 輸出PDF

輸入爲PDF文件，須要先使用NPM安裝上gitbook pdf：

$ sudo npm install gitbook-pdf -g

我在執行上面這條命令的時候出現了下面的錯誤：

***************************************************
Downloading http://cdn.bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-i686.tar.bz2
Saving to /usr/local/lib/node_modules/gitbook-pdf/node_modules/phantomjs/phantomjs/phantomjs-1.9.7-linux-i686.tar.bz2
Error: connect ETIMEDOUT
    at exports._errnoException (util.js:746:11)
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1010:19)
npm ERR! Linux 3.2.0-4-686-pae
npm ERR! argv "/usr/local/bin/node" "/usr/local/bin/npm" "install" "gitbook-pdf" "-g"
npm ERR! node v0.12.7
npm ERR! npm  v2.11.3
npm ERR! code ELIFECYCLE


npm ERR! phantomjs@1.9.7-5 install: `node install.js`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the phantomjs@1.9.7-5 install script 'node install.js'.
npm ERR! This is most likely a problem with the phantomjs package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     node install.js
npm ERR! You can get their info via:
npm ERR!     npm owner ls phantomjs
npm ERR! There is likely additional logging output above.


npm ERR! Please include the following file with any support request:
npm ERR!     /home/wangxq/repository/phantomjs/npm-debug.log


***************************************************

由錯誤報告內容的第一行能夠知道，發生錯誤的緣由是下載 phantomjs發生了錯誤，所以咱們須要手動下載和安裝。

解決方法：[1]

$ git clone git://github.com/ariya/phantomjs.git
$ sudo apt-get install build-essential g++ flex bison gperf ruby perl \
  libsqlite3-dev libfontconfig1-dev libicu-dev libfreetype6 libssl-dev \
  libpng-dev libjpeg-dev python libx11-dev libxext-dev       #安裝編譯須要的工具和依賴
$ cd phantomjs
$ git checkout 1.9.7  #注意：這裏的1.9.7是phantom的版本號，能夠由錯誤報告的第一行找出 
$ ./build.sh --jobs 4
$ sudo cp bin/phantomjs /bin/
$ sudo npm install gitbook-pdf -g  #從新進行安裝

而後，使用下面的命令，要PDF文件，首先安裝依賴庫：

$ sudo apt-get install calibre  
$ gitbook -v 2.1.0 pdf .

發生錯誤：

*****************************************************
info: start conversion to pdf ....ERROR


Error: Command failed: /bin/sh -c ebook-convert /tmp/tmp-29384ctltwbk/SUMMARY.html /tmp/tmp-29384ctltwbk/index.pdf --title="" --comments="這本書是gitbook的一個例子" --language="en" --book-producer="GitBook" --publisher="GitBook" --chapter="descendant-or-self::*[contains(concat(' ', normalize-space(@class), ' '), ' book-chapter ')]" --chapter-mark="pagebreak" --page-breaks-before="/" --level1-toc="descendant-or-self::*[contains(concat(' ', normalize-space(@class), ' '), ' book-chapter-1 ')]" --level2-toc="descendant-or-self::*[contains(concat(' ', normalize-space(@class), ' '), ' book-chapter-2 ')]" --level3-toc="descendant-or-self::*[contains(concat(' ', normalize-space(@class), ' '), ' book-chapter-3 ')]" --no-chapters-in-toc --max-levels="1" --breadth-first --margin-left="62" --margin-right="62" --margin-top="56" --margin-bottom="56" --pdf-default-font-size="12" --pdf-mono-font-size="12" --paper-size="a4" --pdf-header-template="<p class='header'><span></span></p>" --pdf-footer-template="<p class='footer'><span>_SECTION_</span> <span style='float:right;'>_PAGENUM_</span></p>"
Usage: ebook-convert input_file output_file [options]


Convert an ebook from one format to another.


input_file is the input and output_file is the output. Both must be specified as the first two arguments to the command.


The output ebook format is guessed from the file extension of output_file. output_file can also be of the special format .EXT where EXT is the output file extension. In this case, the name of the output file is derived the name of the input file. Note that the filenames must not start with a hyphen. Finally, if output_file has no extension, then it is treated as a directory and an "open ebook" (OEB) consisting of HTML files is written to that directory. These files are the files that would normally have been passed to the output plugin.


After specifying the input and output file you can customize the conversion by specifying various options. The available options depend on the input and output file types. To get help on them specify the input and output file and then use the -h option.


For full documentation of the conversion system see
http://manual.calibre-ebook.com/conversion.html


Whenever you pass arguments to ebook-convert that have spaces in them, enclose the arguments in quotation marks.


ebook-convert: error: no such option: --pdf-default-font-size


*****************************************************

解決方法[2]

$ sudo -v && wget -nv -O- https://raw.githubusercontent.com/kovidgoyal/calibre/master/setup/linux-installer.py | sudo python -c "import sys; main=lambda:sys.stderr.write('Download failed\n'); exec(sys.stdin.read()); main()"


$ gitbook -v 2.1.0 pdf .  # 從新執行命令生成pdf，目標文件爲book.pdf

問題

若是輸入gitbook init命令，出現Installing version 2.1.0， 須要耐性等待安裝。