之前寫了一本「Puppet 從入門就放棄」的 Gitbook，今年打算完成第二本「Terraform 的一百零一種姿勢」時發現 Gitbook 在 2018 年 4 月進行 V2 大改版，其中一個影響是其售價策略 Free 只能使用一個 Public Space (即一本公開書)，對於我這種只有一點點知識又沒錢的傢伙只好出走 Gitbook 另尋他路了。
除了 Gitbook 以外還有許多其他類型的免費服務可以用，例如 GitLab Pages、Github Pages，因為我個人習慣所以選擇 Github Pages (雖然被微軟買走了)，而介面當然是選很潮的工具，找來找去 VuePress 算是比較順眼的，用法也算簡單，所以就決定用 VuePress + Github Pages 當第二本書的解決方案。
由於我可能有多本圖書，所以想用 Content Path 來區別每一本書，像是
- Puppet 從入門就放棄：https://shazi7804.github.io/puppet-manage-guide/
- Terraform 的一百零一種姿勢：https://shazi7804.github.io/terraform-manage-guide/
用之前先了解 Github Pages 的用法，要用 Github Pages 當靜態網站其實只要建立 gh-pages 就可以，不過我不打算每次更新都手動推 gh-pages，所以會接上 Travis CI 代勞這件事。
以下範例可以參考 shazi7804/terraform-manage-guide 專案，先來看目錄結構
|-- .travis.yml
|-- docs
| |-- .vuepress
| | `-- config.js
| |-- README.md
| |-- basic
| | `-- install.md
| |-- intro
| | |-- what-terraform.md
| | `-- why-terraform.md
`-- package.json.travis.yml跑 Travis CI 的設定檔。docs用來放 Markdown 文件的位置。package.json用來定義 vuepress 的 script (或其他 plugin 安裝)
先用 npm 安裝 vuepress，這邊我就不多說 npm 怎麼安裝了 … 可以參考 nvm 或是 n
$ npm add -D vuepress寫一個簡單的 Markdown 到 docs 裡面
$ echo '# Hello World' > docs/README.md設定 package.json 的 scripts
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}VuePress 設定 config.js
module.exports = {
title: 'Terraform 的一百零一種姿勢',
description: 'Terraform manage guide',
base: '/terraform-manage-guide/',
repo: 'https://github.com/shazi7804/terraform-manage-guide',
themeConfig: {
sidebarDepth: 0,
sidebar: [
['/', '前言']
],
nav: [
{ text: 'Home', link: '/' },
{ text: 'Github', link: 'https://github.com/shazi7804/terraform-manage-guide' }
]
}
}位於 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 看看 …
$ npm run docs:dev
> @ docs:dev /Users/scottliao/Development/shazi7804.github/terraform-manage-guide
> vuepress dev docs
WAIT Extracting site metadata...
Compiling
DONE [14:53:29] Build 6da393 finished in 5567 ms!
> VuePress dev server listening at http://localhost:8080/terraform-manage-guide/查看本機的 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。
language: node_js
node_js:
- '8'
before_install:
- npm add -D vuepress
script:
- npm run docs:build
deploy:
provider: pages
skip-cleanup: true
local-dir: docs/.vuepress/dist
github-token: $GITHUB_TOKEN # a token generated on github allowing travis to push code on you repository
keep-history: true
on:
branch: master稍微解釋一下設定檔
- 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 檔案
