VitePress部署在GitHub上

Requirements

下載安裝Node.js
準備好GitHub帳號
VS Code

Step. 1: Create a new repository

在GitHub上建立新的儲存庫，並設定為public，然後按下Create repository。

.gitignore可以先不用選擇，等會在自己建立。 License可以選擇跟VitePress官方一樣的MIT。

將該儲存庫clone下來，並用VS Code開啟：

<USERNAME>改成自己的GitHub帳號，<PROJECT>則是剛才建立的儲存庫名稱

shell

$ git clone https://github.com/<USERNAME>/<PROJECT> && cd <PROJECT>
$ code .

初始化npm：

shell

$ npm init -y

Step. 2: Install VitePress

利用npm安裝VitePress：

shell

$ npm install --dev vitepress vue

建立第一個文件：

shell

$ mkdir docs && echo '# Hello VitePress' > docs/index.md

修改package.json中的scripts，加入dev、build、serve：

json

{
  ...
  "scripts" : {
    "dev": "vitepress dev docs",
    "build": "vitepress build docs",
    "serve": "vitepress serve docs"
  },
  ...
}

回到終端機執行下列指令來運行看看本地server：

shell

$ npm run dev

如果出現底下的畫面表示成功，我們就不要動他，讓他持續幫我們運行這個本地server。

接著用瀏覽器開啟http://localhost:5173，就能看到剛才建立的Hello VitePress

Step 3. Configuration

在docs資料夾中創建一個.vitepress資料夾，這是用來放置跟vitepress設置相關文件的地方。此時的架構大概是下面這個樣子：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  └─ index.md
└─ package.json

其中config.js的設置如下：

javascript

/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  lang: 'zh-Hant-TW',
  title: 'VitePress',
  description: 'Just playing around.'
}

export default config

若想知道還有哪些設定可以調整，請參考官網介紹

另外，由於config.js是新建立的，所以如果要測試網頁的話，可能需要重新執行npm run dev

Step 4. Prettify home page

添加新的頁面：

shell

$ echo '# Getting Started' > docs/getting-started.md

修改首頁docs/index.md：

---
layout: home

title: VitePress
titleTemplate: Vite & Vue Powered Static Site Generator

hero:
  name: VitePress
  text: Vite & Vue Powered Static Site Generator
  tagline: Simple, powerful, and performant. Meet the modern SSG framework you've always wanted.
  actions:
    - theme: brand
      text: Get Started
      link: /getting-started
    - theme: alt
      text: View on GitHub
      link: https://github.com/zxkyjimmy/blog
---

此時我們就有一個漂亮的首頁

Step 5. Deploy on GitHub

設定base

由於GitHub幫我們Host(託管)的網站，會包含儲存庫的名稱，因此我們需要修改config.js來讓生成的網站連結正確：

javascript

/**
 * @type {import('vitepress').UserConfig}
 */
const config = {
  base: '/blog',  // 儲存庫名稱
  lang: 'zh-Hant-TW',
  title: 'VitePress',
  description: 'Just playing around.'
}

export default config

此時本地路徑會變成http://localhost:5173/blog/

建立GitHub Actions

在.github/workflows中建立deploy.yml：

-p這個參數可以讓mkdir一次建立多層的資料夾

shell

$ mkdir -p .github/workflows && touch .github/workflows/deploy.yml

此時架構大致如下：

.
├─ .github
│  └─ workflows
│     └─ deploy.yml
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ getting-started.md
│  └─ index.md
└─ package.json

其中deploy.yml內容設定如下：

yaml

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          cache: npm
      # 讓npm根據package.json和package-lock.json中的內容，安裝對應的套件
      - run: npm ci

      # 建置網站
      - name: Build
        run: npm run build

      # 部署到gh-pages分支
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/.vitepress/dist

忽視非必要記錄的檔案

創建.gitignore檔案，並把我們不想讓git管理的內容寫在裡面：

.vscode
node_modules
dist

node_modules裏面儲存的是npm install --dev vitepress vue時下載下來的套件，底下一共有一千多個檔案，管理起來會太過臃腫。

dist是如果我們使用npm run build時會產生的網站資料夾。

上傳到GitHub

在上傳之前，先確認一下我們的資料夾有以下的東西：

.
├─ .github
│  └─ workflows
│     └─ deploy.yml
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ getting-started.md
│  └─ index.md
├─ .gitignore
├─ package-lock.json
└─ package.json