Gitbook使用入門

GitBook · 發表 2019-01-24 01:56:16

摘要：不像Readthedocs那麼複雜，Gitbook所需的檔案和設定極其少，而且原生支援Markdown和Github倉庫自動同步。一般本地無需安裝，只要在Github中存入相應的Markdown檔案就能自動生成了。不過為了隨時測試和預覽，有必要在本地也弄一套。 ...

不像Readthedocs那麼複雜，Gitbook所需的檔案和設定極其少，而且原生支援Markdown和Github倉庫自動同步。

一般本地無需安裝，只要在Github中存入相應的Markdown檔案就能自動生成了。

不過為了隨時測試和預覽，有必要在本地也弄一套。

參考：GitBook 簡明教程

安裝(不要安裝舊版的gitbook ，而應該是gitbook-cli )：

$ sudo npm install gitbook-cli -g

常見安裝問題：

#如果提示`npm`版本過低，則升級npm：
$ npm i npm@latest -g

#如果提示網路問題，則用-d引數
$ npm install gitbook -g -d

#如果網路還是有問題，則用代理聯網
$ npm config set proxy http://127.0.0.1:1080
$ npm config set https-proxy http://127.0.0.1:1080

gitbook程式和npm的問題太多，我在Mac本機、Ubuntu國外伺服器上測試都裝不好。所以只能使出最終殺器：docker .

gitbook有官方的Docker Hub賬號，但是好像沒有官方的gitbook程式image。推薦第三方排名較高的 billryan/gitbook 。

在本機已有docker的情況下，如此執行：

# 對當前資料夾進行gitbook初始化（容器在命令執行完後會自動消失 因為--rm選項）
$ docker run --rm -v "$PWD:/gitbook" -p 4000:4000 billryan/gitbook gitbook init

# 對當前資料夾的gitbook編譯並提供預覽（容器在命令執行完後會自動消失 因為--rm選項）
$ docker run --rm -v "$PWD:/gitbook" -p 4000:4000 billryan/gitbook gitbook serve

# build
$ docker run --rm -v "$PWD:/gitbook" -p 4000:4000 billryan/gitbook gitbook build

# 最高將docker變成alias快捷鍵，相當於本機的gitbook命令了
$ alias gitbook='docker run --rm -v "$PWD":/gitbook -p 4000:4000 billryan/gitbook gitbook'

以上docker會把當前資料夾對映為虛擬系統裡的/gitbook 資料夾，並且將4000埠對映到本機的4000.而且由於--rm選項，docker不會儲存container。這樣一來就和本機安裝的gitbook沒什麼兩樣了。

本地專案建立及初始化：

# 初始化本地一個專案
$ cd book
$ gitbook init

# 編譯並預覽書籍（生成好後，會顯示一個本地連結，可以在瀏覽器裡開啟預覽）
$ gitbook serve

如果提示類似這樣的錯誤：Error: ENOENT: no such file or directory, stat '/gitbook/_book/gitbook/gitbook-plugin-lunr/lunr.min.js'
那麼就需要安裝外掛。首先要在專案根目錄下新建一個book.json 檔案，內容如下：

{
"plugins": [
"fontsettings",
"sharing",
"lunr",
"search",
"highlight",
"livereload"
]
}

然後執行命令gitbook install 安裝這些外掛。之後就應該沒問題了。

基本檔案結構：

[站外圖片上傳中...(image-878a3d-1548159627560)]

Gitbook至少需要兩個檔案:

README.md
SUMMARY.md

SUMMARY.md 目錄檔案格式：

Gitbook的目錄最多支援3級。

標準格式：

* [第一章](section1/README.md)
* [第一節](section1/example1.md)
* [第二節](section1/example2.md)
* [第二章](section2/README.md)
* [第一節](section2/example1.md)

利用標題或分割線：

# Summary

### Part I

* [Introduction](README.md)
* [Writing is nice](part1/writing.md)
* [GitBook is nice](part1/gitbook.md)

### Part II

* [We love feedback](part2/feedback_please.md)
* [Better tools for authors](part2/better_tools.md)

----

* [Last part without title](part3/title.md)

Gitbook使用入門

您可能也會喜歡…