gitbook 入門教程之釋出電子書

雪之夢技術驛站發表於2019-04-08
Git

輸出目標檔案

語法格式: gitbook build [book] [output]

預設情況下,gitbook 輸出方式是靜態網站,其實 gitbook 的輸出方式有三種: website, json,和 ebook.

只不過另外兩種不是很常用,更多情況下我們是使用靜態網頁搭建個人官網,或託管到第三方平臺,或部署到私有云伺服器,但不管怎麼樣,還是離不開生成這一步.

示例:

# 預設輸出格式: `website`
$ gitbook build --format=website

# 更改輸出格式: `json`
$ gitbook build --format=json

# 更改輸出格式: `ebook`
$ gitbook build --format=ebook
複製程式碼

預設情況下輸出目錄: _book/,整個專案的入口檔案是: index.html

整合 github 網站

本教程的電子書原始碼和輸出檔案均託管到 github 網站,所以這裡介紹下如何利用 Github Pages 靜態網頁服務與 gitbook 進行整合.

什麼是 GitHub Pages ?

Github Pages 是 github 網站推出的一種免費的靜態網頁託管服務,適合搭建靜態的專案主頁或個人官網.

其中,網站專案的原始碼直接託管在 github 倉庫中,當倉庫檔案更新後,該倉庫所關聯的網站自動更新,從而實現了原始碼與官網的聯動更新.

gitbook-publish-github-pages-preview.png

如果想了解更多詳情,請參考官網: pages.github.com/

怎麼做 GitHub Pages ?

每個賬號有且只有一個主頁站點,但允許無限制多的專案站點.

啥是主頁站點,專案站點又是啥?

別急,讓我先舉個例子看一下最終效果.

假如使用者名稱: zhangsan 名下有四個公開倉庫,一個倉庫名叫做: zhangsan.github.io,另外三種分別是: project01,project02,project03 .

如果想要對外暴露上述四個倉庫作為我們的靜態網站,那麼最終效果就是下面這樣的.

注意將 zhangsan 替換成自己的 github 使用者名稱,否則八成是打不開網站,除非真的有 zhangsan 這個使用者.

其實上述規則很好理解,github 網站作為一個託管中心,有成千上萬的使用者在使用 github 並且每個使用者的使用者名稱都是唯一併且不同的,因此 *.github.io 萬用字元域名剛好充當名稱空間.

可以預料的是,不僅僅有 <username>.github.io 這種二級域名,說不定還有 api.github.io,docs.github.io 等等,畢竟只需要購買 *.github.io 萬用字元域名證書就可以支援任意多的二級域名了,感謝 github 贈送我們免費的 https 網站.

說到這裡,不得不吐槽下 gitbook 的名稱空間策略了,gitbook 也有自己的電子書託管服務,但訪問地址是 <username>.gitbook.io/<namespace> .

很顯然,gitbook 沒有區分主頁站點和專案站點,相當於全部都是專案站點,缺少主次之分.

閒言少敘,既然知道了輸入內容和輸出效果,那麼接下來的任務就是了解中間過程了,讓我們一起探討下怎麼釋出網站吧!

主頁站點

建立 <username>.github.io 公開倉庫

前往 github.com/ 網站建立名為 <username>.github.io 的公開倉庫.

比如我的使用者名稱是: snowdreams1006 ,那麼我的主頁站點倉庫就是: snowdreams1006.github.io

建立首頁 index.html 檔案

不管是線上直接建立 index.html 還是克隆到本地建立 index.html ,最終的 <username>.github.io 倉庫一定要有 index.html 首頁檔案.

示例:

# 克隆到本地
$ git clone https://github.com/username/username.github.io

# 切換到專案
$ cd username.github.io

# 建立 `index.html` 檔案
$ echo "Hello World" > index.html

# 推送到遠端倉庫
$ git add --all
$ git commit -m "Initial commit"
$ git push -u origin master
複製程式碼
訪問主頁站點 https://username.github.io

開啟瀏覽器,輸入網址: username.github.io 訪問主頁站點,顯示的內容正是我們剛剛提交的 index.html 檔案內容.

如果沒有正常顯示,清除瀏覽器快取強制重新整理試試看!

專案站點

相比主頁站點來說,專案站點命名比較隨意了,作為靜態網站不可或缺的檔案仍然是 index.html.

建立首頁 index.html 檔案

建立首頁檔案並新增測試內容,方便待會線上訪問專案站點測試是否部署成功.

設定 GitHub Pages 選項

點選倉庫首頁右上方設定(Settings)選項卡,往下翻到 GitHub Pages 選項,選擇原始碼目錄,根據實際情況選擇原始碼來源於 master 分支還是其他分支或者docs/ 目錄.

gitbook-publish-project-setting.png

方便起見,選擇第一個 master 分支即可,注意下面的主題和這一步的來源只能兩者選其一,否則主題優先順序更高!

訪問主頁站點 https://username.github.io/<repository>

開啟瀏覽器,輸入網址: username.github.io/repository 訪問專案站點,顯示的內容正是我們剛剛提交的 index.html 檔案內容.

如果沒有正常顯示,清除瀏覽器快取強制重新整理試試看!

如何整合 gitbook ?

我們已經知道 Github Pages 是提供靜態網站的免費託管,而 gitbook 預設生成的內容就是靜態網站,兩者如何結合自然不用我多說了吧?

gitbook 預設輸出目錄 _book/ 包括了靜態網站所需的全部資源,其中就包括 index.html 首頁檔案.

因此我們只需要每次生成後將 _book/ 整個目錄複製到專案根目錄,那麼推送到遠端倉庫時自然就是輸出後靜態網站了啊!

示例:

# 生成靜態網站
$ gitbook build

# 複製到專案根目錄
$ cp -r _book/* .

# 新增到本地版本庫
$ git add .
$ git commit -m "publish"

# 推送到遠端倉庫
$ git push origin master
複製程式碼

現在登入 github 網站看一下靜態網站是否成功上傳以及訪問主頁站點或專案站點看一下最新內容是否成功渲染吧!

小結

本節我們學習 gitbook 有三種輸出方式,其中預設的網頁輸出最為常用.

除此之外,還講解了如何與 github pages 進行結合,從而實現原始碼和網站的自動更新維護.

如果原始碼沒有託管到 github 這種第三方服務商,你也可以搭建自己的伺服器,比如將 _book/ 目錄全部扔到 nginx 伺服器做靜態資源伺服器等.

畢竟,原始碼和輸出內容都在你手中,想怎麼玩還不是自己說了算?

相關文章