專案基本設定

Zensical 的專案設定都寫在 zensical.toml 裡。用 zensical new 建立專案時，會自動產生一份附有註解的範例設定檔。

`[project]` 範圍

zensical.toml 的開頭必須先宣告一個範圍（scope）：

[project]

目前所有設定都放在這個範圍底下。官方表示之後會新增其他範圍，並提供自動重構，不需要手動搬移。

也可以繼續用 mkdocs.yml

Zensical 讀得懂 mkdocs.yml。本頁每個設定都同時有 TOML 與 YAML 兩種寫法，YAML 版本就是把 [project] 底下的鍵放到最上層。

常用設定一覽

設定	用途	範例
`site_name`	必填。網站名稱，會出現在 HTML head 與頁首	`"Zensical教學"`
`site_url`	網站的正式網址。使用 instant navigation、instant previews 時必須設定（它們依賴 `sitemap.xml`）；只有離線使用才可省略	`"https://example.com"`
`site_description`	頁面沒有自己的 `description` 時，用它作為 HTML head 的描述，搜尋引擎會用來摘要頁面	`"Zensical 中文教學"`
`site_author`	網站作者，寫入 HTML head	`"Victor Gau"`
`copyright`	頁尾的版權宣告，可放 HTML	`"© 2026 唯客學院"`
`docs_dir`	Markdown 來源目錄，相對於設定檔的路徑	`"docs"`
`site_dir`	輸出目錄，相對於設定檔的路徑	`"site"`
`use_directory_urls`	是否使用目錄式網址，預設 `true`	`false`
`dev_addr`	`zensical serve` 綁定的位址，預設 `localhost:8000`	`"localhost:3000"`
`watch`	預覽時額外監看的檔案或資料夾	`["data.csv", "fragments"]`
`extra`	自由的鍵值，給覆寫的模板取用	`[project.extra]`
`strict`	建置時遇到警告就中止，見連結驗證	`true`

zensical.toml

[project]
site_name = "我的 Zensical 網站"
site_url = "https://example.com"
site_description = "這是一個使用 Zensical 建立的網站"
site_author = "Victor Gau"
copyright = "&copy; 2026 唯客學院"
docs_dir = "docs"
site_dir = "site"
dev_addr = "localhost:3000"
watch = [
  "data.csv",
  "fragments",
]

docs_dir 目前不能設成 .

這是官方標註的暫時限制。如果想把 Markdown 放在專案根目錄，請改成放進子資料夾（例如 docs），再讓 docs_dir 指向它。

`use_directory_urls` 的差別

這個設定會改變頁面網址的樣子：

true（預設）false

來源檔案	產生的檔案	網址
`index.md`	`index.html`	`/`
`usage.md`	`usage.html`	`/usage/`
`about/license.md`	`about/license.html`	`/about/license/`

來源檔案	產生的檔案	網址
`index.md`	`index.html`	`/index.html`
`usage.md`	`usage.html`	`/usage.html`
`about/license.md`	`about/license.html`	`/about/license.html`

建置給離線使用時，Zensical 會自動改成 false，這樣網站才能直接用檔案系統開啟。

`watch` 會自動監看哪些東西？

不需要設定的部分：docs_dir 內所有檔案、主題檔案、Snippets 的 base_path 與 auto_append 檔案、Macros 相關的檔案，以及符號連結（僅限目標位於已監看資料夾內）。其他不在這些位置的資料（例如放在專案根目錄的 CSV）才需要加進 watch。修改被監看的檔案時，會觸發完整重建。

頁面之間的連結

連到其他頁面時，請一律使用指向 Markdown 檔案的相對連結，不要連到最後產生的 HTML：

請參考 [佈署](zensical_deployment.md) 這一頁。

Zensical 會依照 use_directory_urls 自動換成正確的網址。這樣做有兩個好處：

網站搬到新的 site_url 時，內容完全不用改。
未來 Zensical 支援 HTML 以外的輸出格式時，連到 Markdown 的連結仍然有效。

README.md 與 index.md

README.md 會像 MkDocs 一樣被轉成 index.html。如果同一個資料夾同時有 README.md 與 index.md，行為未定義，請避免。

頁面標題怎麼決定？

每一頁的標題依下列優先順序決定：

nav 設定裡指定的標題
頁面 front matter 的 title（見 Front matter）
頁面內容的第一個一級標題（# 標題）
Markdown 檔名

與 MkDocs 目前的一個差異

如果設定了 nav，但 Markdown 檔案裡沒有寫 # 標題，MkDocs 會用導覽標題當作頁面的 h1，Zensical 目前則是用檔名。官方正在重新設計導覽，之後會處理。建議每一頁都寫上 # 標題。

總結

想做的事	設定
網站名稱、網址	`site_name`、`site_url`
SEO 描述、作者	`site_description`、`site_author`
改來源／輸出目錄	`docs_dir`、`site_dir`
改預覽埠號	`dev_addr`
監看額外檔案	`watch`
改網址格式	`use_directory_urls`

專案基本設定

[project] 範圍