基本操作指令

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

安裝

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

uv（建議）pip

如果專案已經有 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

選項	簡寫	說明
`--config-file`	`-f`	指定要使用的設定檔
`--open`	`-o`	用預設瀏覽器開啟預覽
`--dev-addr <IP:PORT>`	`-a`	指定 IP 與埠號（預設 `localhost:8000`）
`--help`		顯示說明並離開

只用於預覽

Zensical 內建的網頁伺服器只適合預覽，不要拿來當正式環境。正式上線請使用 nginx、Apache 這類專用的網頁伺服器，或靜態網站託管服務。

建立網站

指令:

zensical build

zensical build --clean

說明:

1️⃣ zensical build

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

2️⃣ zensical build --clean

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

zensical build 的所有選項：

選項	簡寫	說明
`--config-file`	`-f`	指定要使用的設定檔
`--clean`	`-c`	清除快取
`--strict`	`-s`	啟用嚴格模式：有警告就中止建置，見連結驗證
`--help`		顯示說明並離開

輸出異常時

如果建置結果不如預期（特別是升級 Zensical 之後），先跑一次 zensical build --clean。官方說明 Zensical 的架構仍在演進，正在修正會留下過期建置狀態的行為，之後應該不再需要清除。如果乾淨建置之後問題還在，請到官方 issue 回報。

佈署到 GitHub Pages

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

升級 Zensical

升級前，先查看官方的 changelog 確認要升級到的版本。Zensical 遵循語意化版本（semantic versioning），目前是 0.0.x（alpha／開發階段）；接近 beta 時會改成 0.x，等到穩定的 1.0 之後，語意化版本的規則才會更嚴格。

pipuv

先啟用要升級的虛擬環境，然後：

pip install --upgrade --force-reinstall zensical

查看目前安裝的版本：

pip show zensical

已經有鎖定檔（uv.lock）時，uv 會一直使用舊版本，直到你明確升級。把 <version> 換成想升級到的版本：

uv lock --upgrade-package zensical==<version>

查看目前安裝的版本：

uv pip show zensical

瀏覽器支援

Zensical 盡可能支援最大範圍的瀏覽器，同時使用 CSS 自訂屬性（custom properties）、遮罩圖片（mask images）等現代 CSS 功能。官方確認完整支援的瀏覽器：

瀏覽器	版本
Chrome	49+
Safari	10+
Edge	79+
Firefox	53+
Opera	36+