用 VuePress + Github Pages 取代小氣鬼的 Gitbook 吧

2019-02-22 Github

之前寫了一本「Puppet 從入門就放棄」的 Gitbook,今年打算完成第二本「Terraform 的一百零一種姿勢」時發現 Gitbook 在 2018 年 4 月進行 V2 大改版,其中一個影響是其售價策略 Free 只能使用一個 Public Space (即一本公開書),對於我這種只有一點點知識又沒錢的傢伙只好出走 Gitbook 另尋他路了。

除了 Gitbook 以外還有許多其他類型的免費服務可以用,例如 GitLab PagesGithub Pages,因為我個人習慣所以選擇 Github Pages (雖然被微軟買走了),而介面當然是選很潮的工具,找來找去 VuePress 算是比較順眼的,用法也算簡單,所以就決定用 VuePress + Github Pages 當第二本書的解決方案。

由於我可能有多本圖書,所以想用 Content Path 來區別每一本書,像是

用之前先了解 Github Pages 的用法,要用 Github Pages 當靜態網站其實只要建立 gh-pages 就可以,不過我不打算每次更新都手動推 gh-pages,所以會接上 Travis CI 代勞這件事。

以下範例可以參考 shazi7804/terraform-manage-guide 專案,先來看目錄結構

  • .travis.yml 跑 Travis CI 的設定檔。
  • docs 用來放 Markdown 文件的位置。
  • package.json 用來定義 vuepress 的 script (或其他 plugin 安裝)

先用 npm 安裝 vuepress,這邊我就不多說 npm 怎麼安裝了 … 可以參考 nvm 或是 n

寫一個簡單的 Markdown 到 docs 裡面

設定 package.json 的 scripts

VuePress 設定 config.js

位於 docs/.vuepress/config.js 這隻檔案是 VuePress 的主要設定檔,這邊解釋幾個重要項

  • title、description 沒什麼好解釋的 …
  • base:URL 的 content path,如:localhost/terraform-manage-guide/
  • repo:提供 repository 的位置給讀者參考。
  • themeConfig:VuePress 介面主要設定值。
    • sidebar:側邊欄的顯示方式,範例是使用 Multiple Sidebars
    • sidebarDepth:預設側邊欄顯示幾個階層 (h1, h2 …)
    • nav:Navbar 會顯示在 Header 的地方。

Ready 後就執行 vuepress 看看 …

查看本機的 http://localhost:8080/terraform-manage-guide/ 應該可以看到 Hello World 或者你也可以 clone shazi7804/terraform-manage-guide 專案來測試。

加上 Travis CI 佈署到 Github Pages

要關聯 Github 和 Travis CI 的話可以參考「一條龍佈署 CI/CD 從 Github 跑 Travis 到 AWS CodeDeploy – 介紹及授權 Travis 到 Github」,關聯好之後只需要一個 .travis.yml 檔案就可以設定 Deploy Github Pages。

稍微解釋一下設定檔

  • Travis CI 透過 language、node_js 幫你把指定的 Container 抓下來。
  • before_install 用來安裝 vuepress。
  • npm run docs:build 會產生 VuePress 要的 html 靜態檔案到 docs/.vuepress/dist
  • 關鍵在 deploy 這段
    • local-dir 把 docs/.vuepress/dist 目錄推到 gh-pages 這個 branch。
    • github-token 到你的 Github 產生 token 權限

Github Token 千萬不要明碼寫在 .travis.yml

實際上 Github Token 是存在 Travis CI 的 Environment,然後在 .travis.yml 用 $GITHUB_TOKEN 抓進來使用。

這樣就可以 git push 自動 deploy 到 Github Pages 囉,要查驗產生出來的 html 可以到 gh-pages 看產生的 html 檔案

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *

彙整

分類

展開全部 | 收合全部

License

訂閱 Mr. 沙先生 的文章

輸入你的 email 用於訂閱

%d 位部落客按了讚: