Skip to content

網站佈署

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

沒有 gh-deploy

Zensical 不提供 mkdocs gh-deploy 這類指令。請改用 GitHub Actions 建置，或把 site/ 上傳到任何靜態空間。

測試執行

可以先手動測試：

zensical serve

如果 zensical serve 能正常顯示網站，代表設定沒問題。

Note

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

本機建置

zensical build --clean

輸出目錄預設為 site/。

若使用本專案的 uv 工作流程：

uv sync
uv run zensical serve
uv run zensical build --clean

啟用 GitHub Actions 自動佈署

在你的 GitHub 專案內 建立（本專案已有 .github/workflows/ci.yaml）：

.github/workflows/ci.yaml

內容可參考：

name: ci
on:
  push:
    branches:
      - master
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5

      - name: Set up uv
        uses: astral-sh/setup-uv@v6
        with:
          python-version-file: ".python-version"
          enable-cache: true

      - name: Install dependencies
        run: uv sync --frozen

      - name: Build site
        run: uv run zensical build --clean

      - name: Configure GitHub Pages
        uses: actions/configure-pages@v5

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: site

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

📌 這個 GitHub Actions 會在 main 分支有變更時，自動建置並佈署。

若沒用 uv，也可以改成 pip install zensical 再執行 zensical build --clean。

啟用 GitHub Pages

  1. 打開 GitHub 倉庫 → 設定（Settings）
  2. 找到 Pages
  3. Source 選 GitHub Actions
  4. 推送後網站網址會類似： 
    https://你的帳號.github.io/你的倉庫/

記得在 zensical.toml 設定正確的 site_url，搜尋與 instant navigation 才會正常。

總結

步驟 指令 / 設定 說明
手動測試 zensical serve 確保網站顯示正常
手動建置 zensical build --clean 產生 site/
設定 GitHub Actions .github/workflows/ci.yaml 自動佈署
啟用 GitHub Pages Source = GitHub Actions 讓網站正式上線

參考資料