跳轉至

網站佈署

你可以使用 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 new 建立專案時，會自動產生 .github/workflows/docs.yml。它在 main（或 master）分支有推送時，安裝 Zensical、執行 zensical build --clean，再把 site/ 上傳並佈署到 GitHub Pages。官方目前不建議在 CI 使用快取，因為快取機制之後會為了效能而調整。

想在連結壞掉時阻止佈署，把建置指令改成 zensical build --clean --strict，見 連結驗證。

佈署到 GitLab Pages

如果程式碼託管在 GitLab，可以用 GitLab CI 佈署到 GitLab Pages。在儲存庫根目錄建立 .gitlab-ci.yml：

.gitlab-ci.yml
pages:
  stage: deploy
  image: python:latest
  script:
    - pip install zensical
    - zensical build --clean
  pages:
    publish: site
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

預設分支有新的提交時，就會自動建置並佈署，網站網址是 <username>.gitlab.io/<repository>。

GitLab Pages 設定

GitLab Pages 預設會使用帶有隨機字串的網域。正式佈署時，請在 GitLab Pages 設定取消勾選 Use unique domain。若要公開網站，也要到 Settings > General > Visibility 設定 Pages 的可見度。

其他託管平台

官方沒辦法涵蓋所有的託管服務，社群提供了這些指南：

  • Azure Static Web Apps（搭配 GitHub Actions）
  • Azure Static Web Apps（搭配 Azure DevOps）
  • Read the Docs

因為 Zensical 輸出的是純靜態的 site/ 資料夾，所以任何能託管靜態檔案的服務（Netlify、Vercel、自架的 nginx 等）都可以使用。

總結

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

參考資料