構建電子書＆網站 by gitbook

gitbook 是一個命令工具，幫助你把一堆md,asciidocbuild 成網頁版的電子書以及mobi, epub, pdf的檔案生成。

閱讀該文章時markdown 語法是基本常識。

因為最近不斷地整理電子書，發現了電子書的遍及格式大致有markdown格式，簡稱md，還有另外一種叫asciidoc，我初次見到到asciidoc是在bitcoinbook之後又遇見了ethereumbook，可是裡面的公式還是呈現不出來，後來遇見了gitbook，讓我很舒服的把md,asciidoc build 成網頁版的電子書以及mobi, epub, pdf 三種格式，讓大家可以在手機上就可閱讀。

gitbook 的使用過程:

  • 安裝：安裝所需的指令環境。
  • build ： 生成網頁的電子書文件。
  • gitbook 伺服：器運行一個gitbook 伺服器，讓你可以在 http://localhost:4000 的位置，喵一下樣子。
  • 編譯成書籍 mobi, epub, pdf 。

大綱

安裝 gitbook 指令

如果沒有安裝過gitbook的可以執行一下 ps. gitbook 依賴npm，npm的安裝請參考node js 下載頁面自己安裝加油嘿。

務必要安裝完才可以執行以下指令安裝gitbook，不然無效。 安裝也是需要一些時間。

sudo npm install -g gitbook-cli
sudo npm install -g gitbook

製作一本書

現在我們來創造一個名字你高興的資料夾（建議是英文書名），進去之後，指行以下指令初始化一下該資料夾（這可能會花一點時間）。

gitbook init

執行的過程，跑完恭喜你：

➜  ~ mkdir book
➜  ~ cd book
➜  book gitbook init
warn: no summary file in this book
info: create README.md
info: create SUMMARY.md
info: initialization is finished

裡面會有兩個檔案，分別為README.md, SUMMARY.md。

書本結構

SUMMARY.md文件定義了整本書的結構。 結構很簡單，就是一個簡單的markdown語法的清單。

# Summary

* [Introduction](README.md)
* [第一章](ch1.md)
	* [第一節](ch1-1.md)
	* [第二節](cd1-2.md)
* [第二章](ch2.md)
* [第三章](ch3.md)

build

執行該指令可以把SUMMARY.md引用到的文件，變成網頁。

gitbook build

build的過程，此時，資料夾內會多一個_book資料夾，裡面就是創見出來的網頁：

➜  book gitbook build
info: 7 plugins are installed
info: 6 explicitly listed
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 1 pages
info: found 0 asset files
info: >> generation finished with success in 1.2s !

運行 伺服器模式

運作成伺服器，可以即時瀏覽書籍撰寫的變化，gitbook serve會隨時偵測你存擋，刷新網頁。

gitbook serve

運行成功如下，就可以前往http://localhost:4000瀏覽：

Starting server ...
Serving book on http://localhost:4000

製作成電子書

gitbook 可以製作書籍種類

gitbook pdf
gitbook epub
gitbook mobi

如果覺得懶，已可以寫一個build-book.sh把上述程式碼貼上去，以後只要sh build-book.sh就可以自動生成勒。

問題

不過如果你直接使用會遇到以下報錯：

InstallRequiredError: "ebook-convert" is not installed.
Install it from Calibre: https://calibre-ebook.com

解決方法：

  • 前往 https://calibre-ebook.com/download ，下載mac 的版本
  • 安裝它，把他丟到應用程式裡面
  • 執行以下指令: 
    sudo ln -s /Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin

    ok，應該可以很舒服的執行勒

發佈到github page

先前準備：

  • 在 gitbub上創建一個repo
  • 把它clone 到 local 端
  • 進到 該資料夾 初始化變成書 gitbook init（已經是書的不要理我

開始發布

進到github clone 下來的 repo

  1. 先做一下手腳（這是為了可以讓自動化發布網頁鋪路）：
    • 在 主目錄創一個 文件 叫.gitignore
    • 內容如下 
       *~
 _book
 .DS_Store
    • 來gitbook build一下，刷新_book內容
    • 來推到主分之一下避免衝突 
       git commit -am "update"; git add . ;git push origin master
  2. 創建一個分支叫做gh-pages，這個執行一次就好 
     git checkout --orphan gh-pages
  3. 進到gh-pages分支
    • 移除主目錄下根本不是網頁的檔案，如果沒有做第一步的，你屎定了，文件全部都會消失。 
       git rm --cached -r .
 git clean -df
    • 把_book裡面的文件複製出來 
       cp -r _book/* .
    • 堆一波到gh-page分支 
       git commit -am "update"; git add . ;git push origin gh-pages
    • 可以回到主目錄勒，如果不知道怎麼回家的 
       git checkout master%

      * 檢查一下有沒有發布成功，網址的樣子要是`帳號名稱.github.io/倉庫名稱`，譬如`https://cypherpunks-core.github.io/bitcoinbook_2nd_zh/`，祝您旅途愉快。

自動發布腳本

請在主目錄建立一個文件叫publish.sh，把下面內容貼上並存擋。 執行sh publish.sh '更新的說明'就可以勒。

git checkout master
gitbook build 
git add .
git commit -m $1
git push -u origin master
git branch -D gh-pages
git branch  -r -d  origin/gh-pages
git push origin :gh-pages
git checkout --orphan gh-pages
git rm --cached -r .
git clean -df
cp -r _book/* .
git add .
git commit -m $1
git push -u origin gh-pages
git checkout master%

常見問題

問. 我發佈啦，怎麼無法在帳號名稱.github.io/倉庫名稱域名下看到我的網站勒？

  • 要等一段時間（看運氣），幾秒鐘到三分鐘不等
  • 你檢查一下你有推到 gh-pages分支嗎？
  • 既使你推到了gh-pages分支，你有順利的把_book中的網頁拉出來嗎？最少要index.html
  • 該 repo 的setting 選項當中，有一個預設branch 的選項，檢查一下是否設定在gh-pages分支。

參考文獻

Written on August 26, 2019