GitBook使用教學

料理食材(內文內容)

  • Gitbook的簡介
  • node、nodejs、npm、nvm的差別
  • 安裝Gitbook
  • 使用Gitbook

誰可以安心食用(適合誰讀)

  • 知道Markdown語法
  • 會操作terminal
  • 你的電腦是Mac

服用完你會獲得什麼

  • 知道Gitbook是什麼
  • 知道如何安裝Gitbook(超重要)
  • 知道如何使用Gitbook

Gitbook的簡介

GitBook是一個非常好用文件管理器，以框架的文件來說，需要的僅有目錄和內容，而Gitbook所產生出的靜態網頁則十分符合這種簡潔的需求，它的呈現就像以下：

image

左邊有一個side bar放文章目錄，中間則是內文

作為一個呈現文件資訊的網頁，這樣子頁面就很足夠了。

安裝Gitbook

  1. 安裝nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
  1. 使用nvm安裝node v10.23.3(一定要用v10.23.3，不然gitbook會裝不了)
nvm install 10.23.0
  1. 安裝gitbook-cli
npm install -g gitbook-cli

node、nodejs、nvm、npm的差別

這幾個是我當初在安裝nodejs時，常常會搞混的一些東西，因此放在這裡記錄。

  • node v.s nodejs

這兩個是相同的東西，用Ubuntu使用sudo apt-get install -y nodejs安裝node，而MacOSX的homebrew則是使用brew install node，在踩了幾次坑後，我一律都用nvm來下載node，確保不會有名稱錯誤的問題。

  • nvm

nvm是一個管理node版本的工具，就如同rvm是管理ruby版本的工具，要下載特定版本時可以使用nvm install 14或是nvm install node安裝最新版，安裝後可以使用nvm use 14進行版本切換。

  • npm

網路上有許多經由node製作的包，而npm就是用來管理這些包的工具，類似於RubyGem用為管理Ruby的包，如果要安裝特定的包可以使用npm install gitbook@2.3.0，不加後面的@2.3.0就會安裝最新版的包。

建立Gitbook專案

首先先建立一個空的資料夾 mkdir mybook && cd mybook

重開terminal後可能導致你node版本變為預設的最新版，使用nvm use 10.23.3進行切換

  1. 執行gitbook初始化
gitbook init

如果執行正確，你會看到以下訊息： image

  1. 啟動gitbook服務
gitbook serve

之後瀏覽http://127.0.0.1:4000就會看到以下畫面： image

完成到這一步代表你的gitbook安裝正確。

編寫Gitbook專案

在你的專案中目前會有三個檔案

  1. README.md
  2. SUMMARY.md
  3. _book/

接著我們打開SUMMARY.md，可以發現裡面含有以下的內容：

# Summary

* [Introduction](README.md)

簡單來說，這是一個表達目錄的檔案，接著我們為其新增一個章節，在該檔案 內加入一行* [Test]](Test.md)

之後再專案中建立一個檔案Test.md，並在其中填入以下內容：

# Test
Hello, World!

完成後開啟gitbook服務gitbook serve，瀏覽器開啟http://127.0.0.1:4000，如果已開啟的話按下Shift + CMD + R整理網頁即可看到變化。

你就可以看到以下畫面：

image

如果你希望Test是Introduction的其中一個章節，你也可以將SUMMARY.md更改為以下：

# Summary

* [Introduction](README.md)
    * [Test](Test.md)

這樣子目錄就會變成這樣：

image

當文件編寫完成後，可以考慮部署至Github Pages，關於如何部署可以參考這裡

加入插件

Gitbook的預設功能雖然已經夠用了，但人類總是貪婪的，而網路上有許多善心人士為了滿足人類的貪婪，於是就做了幾種邪惡的套件，讓用過的人再也回不去單純的Gitbook，如何使用還請繼續看：

  1. 在gitbook專案的根目錄中新增book.json這個檔案
  2. 填入以下內容 
    {
"plugins": [
    "-search", "search-pro","back-to-top-button","chapter-fold","copy-code-button","advanced-emoji","splitter"
    ]

}
  3. 至該目錄執行gitbook install，安裝gitbook插件
  4. 開啟gitbook服務gitbook serve 之後你就可以看到加入插件後的gitbook了

善心人士提供的實用gitbook plug大全

結語

Gitbook是一個寫文件非常好用的利器，近期我在與卡米哥一同編寫kamigo框架的文件時，也是決定使用GitBook作為編寫文件的工具，雖然它十分容易上手，但卻非常難安裝，多虧了網路上許多tral and error的苦主，最終才確定node v10.23.3可以正常安裝，真是感謝！