GitBook使用教學
料理食材(內文內容)
- Gitbook的簡介
- node、nodejs、npm、nvm的差別
- 安裝Gitbook
- 使用Gitbook
誰可以安心食用(適合誰讀)
- 知道Markdown語法
- 會操作terminal
- 你的電腦是Mac
服用完你會獲得什麼
- 知道Gitbook是什麼
- 知道如何安裝Gitbook(超重要)
- 知道如何使用Gitbook
Gitbook的簡介
GitBook是一個非常好用文件管理器,以框架的文件來說,需要的僅有目錄和內容,而Gitbook所產生出的靜態網頁則十分符合這種簡潔的需求,它的呈現就像以下:
左邊有一個
side bar
放文章目錄,中間則是內文
作為一個呈現文件資訊的網頁,這樣子頁面就很足夠了。
安裝Gitbook
- 安裝
nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
- 使用nvm安裝
node v10.23.3
(一定要用v10.23.3
,不然gitbook
會裝不了)
nvm install 10.23.0
- 安裝
gitbook-cli
npm install -g gitbook-cli
node、nodejs、nvm、npm的差別
這幾個是我當初在安裝nodejs時,常常會搞混的一些東西,因此放在這裡記錄。
node
v.snodejs
這兩個是相同的東西,用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
進行切換
- 執行
gitbook
初始化
gitbook init
如果執行正確,你會看到以下訊息:
- 啟動
gitbook
服務
gitbook serve
之後瀏覽http://127.0.0.1:4000
就會看到以下畫面:
完成到這一步代表你的gitbook
安裝正確。
編寫Gitbook專案
在你的專案中目前會有三個檔案
README.md
SUMMARY.md
_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
整理網頁即可看到變化。
你就可以看到以下畫面:
如果你希望Test
是Introduction
的其中一個章節,你也可以將SUMMARY.md
更改為以下:
# Summary
* [Introduction](README.md)
* [Test](Test.md)
這樣子目錄就會變成這樣:
當文件編寫完成後,可以考慮部署至Github Pages,關於如何部署可以參考這裡
加入插件
Gitbook的預設功能雖然已經夠用了,但人類總是貪婪的,而網路上有許多善心人士為了滿足人類的貪婪,於是就做了幾種邪惡的套件,讓用過的人再也回不去單純的Gitbook,如何使用還請繼續看:
- 在gitbook專案的根目錄中新增
book.json
這個檔案 - 填入以下內容
{ "plugins": [ "-search", "search-pro","back-to-top-button","chapter-fold","copy-code-button","advanced-emoji","splitter" ] }
- 至該目錄執行
gitbook install
,安裝gitbook插件 - 開啟gitbook服務
gitbook serve
之後你就可以看到加入插件後的gitbook了
善心人士提供的實用gitbook plug大全
結語
Gitbook是一個寫文件非常好用的利器,近期我在與卡米哥一同編寫kamigo框架的文件時,也是決定使用GitBook作為編寫文件的工具,雖然它十分容易上手,但卻非常難安裝,多虧了網路上許多tral and error的苦主,最終才確定node v10.23.3
可以正常安裝,真是感謝!