Skip to content

基本操作指令

Zensical 是靜態網站產生工具，可以把寫好的 Markdown 文件迅速轉換成網站。

安裝

Zensical 以 Python 套件發布，建議在虛擬環境中安裝。

如果專案已經有 pyproject.toml：

uv add --dev zensical
uv run zensical

之後請一律用 uv run zensical ...，確保用到專案鎖定的版本。

python -m venv .venv
.venv\Scripts\activate
pip install zensical

macOS / Linux 啟動虛擬環境請改用 source .venv/bin/activate。

本教學專案

這個網站本身就是用 Zensical 建的。在專案根目錄執行 uv sync 後，就可以用 uv run zensical serve 預覽。

基本使用說明

建立新的專案

如果要使用當下目錄作為專案目錄：

# 在當下的目錄建立新專案
zensical new .

如果要建立新的目錄：

# 建立一個新專案，並將專案資料夾命名為 projectname
zensical new projectname

建立後會得到類似結構：

.
├── .github/workflows
│   └── docs.yml
├── docs/
│   ├── index.md
│   └── markdown.md
└── zensical.toml

Note

zensical new 不會覆寫既有檔案。如果目錄裡已經有 zensical.toml，指令會失敗。

啟動伺服器來檢視網站

zensical serve

預設會在 http://localhost:8000 開啟預覽，修改檔案後瀏覽器會自動重新整理。

常用選項：

zensical serve --open          # 自動打開瀏覽器
zensical serve --dev-addr localhost:3000

建立網站

指令:

zensical build

zensical build --clean

說明:

1️⃣ zensical build

  • 讀取 zensical.toml（或 mkdocs.yml）設定
  • 解析 docs/ 目錄下的 Markdown 文件
  • 產生靜態 HTML 檔案
  • 輸出到 site/ 目錄

2️⃣ zensical build --clean

  • 先清除建置快取再重建
  • 升級 Zensical 或輸出結果異常時建議使用

佈署到 GitHub Pages

Zensical 沒有 gh-deploy 指令。建議用 GitHub Actions 建置後上傳 site/，細節見 佈署。

參考資料