跳至主要内容

[Docusaurus] 安裝與部署

建立 docusaurus 環境​

npx create-docusaurus@latest my-website classic

設定 docusaurus.config.js​

整個 docusaurus 的設定檔大概可以分成幾部分：

  1. 個人資料設定，這是跟網站名稱與網址相關的部分
title: 'Jeremy Ho',
tagline: '前端工程師 aka 遊戲開發設計師',
favicon: 'img/favicon.ico',
url: 'https://jeremyho.tw',
baseUrl: '/',
  1. Github page 部署相關設定。如果是用 Vercel 部署，這邊填不填都無所謂。
organizationName: '', // Usually your GitHub org/user name.
projectName: '', // Usually your repo name.
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
  1. i18n 語系設定，預設是英文。這裡如果面向是中文讀者，還是建議設成 zh-Hant，整體 UI 會換成中文會提高 UX。
i18n: {
  defaultLocale: 'zh-Hant',
  locales: ['zh-Hant'],
},
  1. presets 設定。主要是用來設定 docs、blog、theme 相關。(presets 範例)
  2. plugins 設定。這裡主要用來設定並引用一些插件。(plugins 範例)
  3. themeConfig 設定。這裡主要用來設定網站的主題樣式、導航列、側邊欄等。(themeConfig 範例)

然後其他一些較特殊的插件會需要額外撰寫在 docusaurus.config.js 中做引用，比如說專門畫圖表的 mermaid。

Vercel 部署​

建立 Vercel 帳號​

注意

這裡默認已經有 GitHub 帳號並把之前的練習上傳到 GitHub repo 上了。

Vercel 選擇 hobby 免費方案，使用 GitHub 登入即可。

Vercel 部署​

辦完 Vercel 帳號後可以直接連通 GitHub repo，import 專案後可以直接一鍵部署。
如果打算使用自定義網名的話，Vercel 也會做對應的引導，並且也會明確指引說在網域提供商 (ex: Gandi) 上需要進行哪些對應設定。

GitHub page 佈署​

注意

因為我最早的 docusaurus blog - CodeFictionist 就是用 GitHub page 佈署的，我得說，千萬別用。
GitHub page 的佈署方式不只繁瑣，而且部署後進站的速度是很明顯遠低於 Vercel 的。
那既然一樣免費，為何不選一個方便又迅速的呢？

  1. 先把程式碼打包成可以佈署的形式
npm build
  1. 佈署
GIT_USER=chungyingho npm run deploy

自動佈署​

  1. GitHub settings > Developer settings > Personal access tokens > Tokens(classic) > Generate new token
  2. Select scopes 選 repo:status 跟 public_repo 權限。
  3. 複製好 token。
  4. 前往專案 repo > Settings > Secrets > Actions > New repository secret，把剛剛複製的 token 貼上。
  5. 前往專案 (vscode)，在根目錄下新增一個 .github 資料夾，在裡面再建立一個 workflows 資料夾，裡面再建立一個 deploy.yml 自動佈署腳本以及一個測試腳本 test-deploy.yml。
  6. 腳本內容如下：
部署用 yml 檔
deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    // 改成自己要部署的分支
    branches:
      - action

permissions:
  contents: write

jobs:
  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: npm

      - name: Install dependencies
        run: npm ci
      - name: Build website
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.DEPLOY_SECRET }}
          publish_dir: ./build
          user_name: github-actions[bot]
          user_email: 41898282+github-actions[bot]@users.noreply.github.com
test-deploy.yml
name: Test deployment

on:
  pull_request:
    // 改成自己要部署的分支
    branches:
      - action

jobs:
  test-deploy:
    name: Test deployment
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: npm

      - name: Install dependencies
        run: npm ci
      - name: Test build website
        run: npm run build
注意

如果一開始在 docusaurus.config.js 中有設定 deploymentBranch，可以把它刪掉了，因為這裡的自動部屬指令會把打包後的程式碼推到 gh-pages 這條分支上。

自定義域名​

  1. 前往溝買網址的網站，比如 Ganti.net，設置 A紀錄與 CNAME。
    • A 紀錄：GitHub 的 IP，有四個可以選填 - 185.199.108.153、185.199.109.153、185.199.110.153、185.199.111.153。
    • CNAME：找到 www 的 CNAME，將值設為 ＠。
  2. 先在 GitHub 上設置自定義域名，需等待一段時間。
  3. 在專案中的 static 資料夾新增一個 CNAME 檔案，填入自己的域名。(對，就這麼簡單，檔案名就是 CNAME)
  4. 更改 docusaurus.config.js
const config = {
  // 直接抄 GitHub page 上給的網址
  url: 'https://codefictionist.com/',
  baseUrl: '/',
}
  1. 打包、佈署。