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,而MacOSXhomebrew則是使用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

如果你希望TestIntroduction的其中一個章節,你也可以將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可以正常安裝,真是感謝!