Skip to content

網站佈署

你可以使用 GitHub Pages 來佈署 Material for MkDocs 網站，並透過 GitHub Actions 來實現自動佈署。

🔹 1. 測試執行

可以先手動測試：

mkdocs serve  # 在本地測試

如果 mkdocs serve 能正常顯示網站，代表你的 MkDocs 設定沒問題。

Note

執行過mkdocs build或mkdocs serve之後，資料夾內會出現一個叫做site/的資料夾，裡面包含了我們的網站所有的資料。手動拷貝site/的所有內容到網站空間內，也是一種把網站佈署出去的方式。

🔹 2. 設定 gh-pages 分支

執行以下指令，讓 GitHub Pages 佈署到 gh-pages 分支：

mkdocs gh-deploy --force

📌 這會把 site/ 目錄的內容推送到 gh-pages 分支。

🔹 3. 啟用 GitHub Actions 自動佈署

在你的 GitHub 專案內，建立：

.github/workflows/mkdocs.yml

內容如下：

name: Deploy MkDocs

on:
  push:
    branches:
      - main  # 當 main 分支有變更時觸發佈署

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Setup Python
        uses: actions/setup-python@v3
        with:
          python-version: "3.9"

      - name: Install Dependencies
        run: |
          pip install mkdocs-material

      - name: Deploy to GitHub Pages
        run: |
          mkdocs gh-deploy --force
📌 這個 GitHub Actions 會在 main 分支有變更時，自動執行 MkDocs 佈署。

🔹 4. 啟用 GitHub Pages

  1. 打開 GitHub 倉庫 → 設定（Settings）
  2. 找到 Pages，選擇 gh-pages 分支
  3. 按 Save，你的網站網址會是： 
    https://你的帳號.github.io/你的倉庫/

📝 總結

步驟 指令 / 設定 說明
手動測試 mkdocs serve 確保網站顯示正常
手動佈署 mkdocs gh-deploy --force 佈署到 gh-pages
設定 GitHub Actions .github/workflows/mkdocs.yml 自動佈署
啟用 GitHub Pages 設定 gh-pages 分支 讓網站正式上線

📖 參考資料