Skip to main content

Docusaurus - 安裝與設定

建立 dosaurus 環境​

npx create-docusaurus@latest my-website classic

設定 docusaurus.config.js​

info

在建了好幾個 docusaurus 後，我發現如果要用 vercel 部署，那這裡其實不仔細填也沒差。

const config = {
  // 通常會設置為 GitHub page 的網址
  url: 'https://chungyingho.github.io',
  // 會設置為 GitHub 的專案名稱
  baseUrl: '/CodeFictionist/',
  // 部屬的分支
  deploymentBranch: 'deployment',
  // 在 GitHub 上的用戶名
  organizationName: 'chungyingho',
  // 通常是 repo 的名稱
  projectName: 'CodeFictionist', 
}

GitHub page 佈署​

  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
warning

如果一開始在 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. 打包、佈署。

Vercel 部署​

建立 Vercel 帳號​

warning

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

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

Vercel 部署​

辦完 Vercel 帳號後可以直接連通 GitHub repo，import 專案後可以直接一鍵部署。

Buy Me A Coffee