使用 VuePress 與 GitLab Pages 架設靜態網站

有時候你只想要做個簡單的網頁，像是偏重文字的公開筆記，就可以用 GitLab Pages 來託管。
而 VuePress 是個蠻簡單使用的靜態網站產生器，預設的佈景主題也很通用。

安裝

1. 安裝 Node.js

推薦使用 v12.x，因為
– VuePress 是在 v12.x 下開發的
– 最新版的 v14.x 經測試，雖然可以執行，但 Yarn 有幾個相依套件宣稱與 v14.x 不相容

2. 安裝 Yarn

使用 npm，Node.js 內附的套件管理器，來安裝另外一個套件管理器

npm install -g yarn

雖然 Yarn 的版本已經到 2.x 了，但是預設還是會幫你裝 1.x 的最新版本。要使用 Yarn 2 的話，得在專案特別指定。
但 VuePress 本來就希望使用 Yarn 1.x，所以沒有問題。

建立最小專案

打開安裝 Node.js 時附帶的 cmd

1. cd 找到適當的地方，建立專案資料夾，名為 vuepress-starter，並且進入專案資料夾

mkdir vuepress-starter && cd vuepress-starter

2. 用套件管理器來初始化專案
實際上就是建立 package.json，會問你問題來填寫所需的欄位

yarn init

完成後可以看看多出來的 package.json，應該會像下面這樣

{
  "name": "vuepress-starter",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "private": true,

  "devDependencies": {
    "vuepress": "^1.8.2"
  }
}

3. 專案安裝 VuePress
這個過程中會產生 yarn.lock 檔案，包含了所有相依套件的版本，推薦加入到 git 管理

yarn add -D vuepress

4. 做一個首頁，只寫一行 H1 大小的標題
README.md 這個檔名代表每個層級的頁面，放在 docs 的根目錄，就等於首頁了

# 如果你不熟悉 echo，要注意 > 前面不要加多餘的空白字元，會被算進去
mkdir docs && echo # Hello VuePress> docs/README.md

打開 package.json，加上官方推薦的 2 個執行指令

{
  "name": "vuepress-starter",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "private": true,
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  },
  "devDependencies": {
    "vuepress": "^1.8.2"
  }
}

這樣就完成最小專案了，馬上使用剛剛指令來預覽

yarn docs:dev

VuePress 會啟動可以”即時更新”的伺服器 (真的是即時更新喔！可以修改首頁試試看)
移至 http://localhost:8080 可以看到剛剛做的首頁

按 Ctrl+C 來停止伺服器

配置檔案

1. 在 docs 資料夾建立 .vuepress 資料夾

# 如果要巢狀建立資料夾，要加引號才會合法
mkdir "docs/.vuepress"

2. 在 .vuepress 資料夾內建立 config.js 檔案

# 建立空檔案的語法，cmd 沒有 touch 語法可以用
copy nul "docs/.vuepress/config.js" > nul

3. 打開 config.js，指定網站的標題和描述

module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around'
}

使用 GitLab Pages 的準備

1. 繼續編輯 config.js

module.exports = {
  title: 'Hello VuePress',
  description: 'Just playing around',

  // 注意前後都要有 / ，假如你在 GitLab 上用的專案名稱不是 vuepress-starter，
  // 要置換成你自己的專案名稱
  base: '/vuepress-starter/',
  // public 這個名稱是固定的
  dest: 'public'
}

2. 在專案根目錄建立 .gitlab-ci.yml，打開編輯

image: node:12.22.1  # 應該要對應開發環境所使用的 Node.js 版本
pages:
  cache:
    paths:
    - node_modules/
  script:
  - yarn install
  - yarn docs:build
  artifacts:
    paths:
    - public  # 對應 config.js 的 dest
  only:
  - main  # 代表只有在 main 分支有新提交時才會觸發

P.S. 大家應該都知道預設分支已經從 master 變成 main 了吧，
我在 GitLab 的 Web IDE 胡亂測試時才發現…

4. 新增 .gitignore
因為嚴格來說並不是在開發 Node.js 專案，加上都丟給 GitLab CI 去建置，
所以不需要拿 GitHub 上的 template，我們只加入 node_modules/ 就好

node_modules/

5. 開 GitLab 的新專案
專案名稱：vuepress-starter
分支名稱：main

6. Push 之後，到 GitLab 專案頁面已經可以看到 Pipeline 在運作了，大概等個1分半左右，就會完成

7. Setting -> Pages 可以找到你的網站連結
格式會是 https://<你的帳號>.gitlab.io/<專案名稱>

大功告成

你的專案現在看起來會是這樣子

.
├─ docs
│ ├─ .vuepress
│ │ └─ config.js
│ └─ README.md
└─ .gitignore
└─ gitlab-ci.yml
└─ package.json
└─ yarn.lock

系統這樣就完成了，在開始量產之前，你應該會想要加入其它元素。
預設的佈景主題有左側邊欄和右上導航列的功能，可以到說明文件看看。
https://vuepress.vuejs.org/theme/default-theme-config.html