導覽設定

清楚的導覽結構是好文件的關鍵。Zensical 預設會依照資料夾結構產生側邊導覽，你也可以明確定義，並用一系列功能旗標（feature flags）調整外觀與行為。

明確定義導覽（`nav`）

最簡單的寫法是列出檔案路徑（相對於 docs_dir），標題由 Zensical 從內容取得：

[project]
nav = [
  "index.md",
  "about.md",
]

要指定標題，就用「標題 = 路徑」的形式：

[project]
nav = [
  { "首頁" = "index.md" },
  { "關於" = "about.md" },
]

導覽區段（Sections）

把陣列放在標題後面，就形成階層：

[project]
nav = [
  { "首頁" = "index.md" },
  { "關於" = [
    "about/index.md",
    "about/vision.md",
    "about/team.md",
  ] },
]

外部連結

任何無法對應到 Markdown 頁面的字串，都會被當成網址：

[project]
nav = [
  { "GitHub" = "https://github.com/zensical/docs" },
]

導覽功能旗標

所有旗標都加在 [project.theme] 的 features 陣列：

[project.theme]
features = [
  "navigation.instant",
  "navigation.tabs",
  "navigation.sections",
  "navigation.expand",
  "navigation.path",
  "navigation.indexes",
  "navigation.top",
  "toc.follow",
]

旗標	效果
`navigation.instant`	即時導覽：攔截站內連結，以 XHR 載入，不整頁重新載入，行為像單頁應用程式，搜尋索引也會保留。需要 `site_url`
`navigation.instant.prefetch`	滑鼠移到連結上就開始預先載入頁面（實驗性功能）
`navigation.instant.progress`	慢速連線時，頁面頂端顯示進度條（超過 400 毫秒才會出現）
`navigation.tracking`	網址列的錨點（`#xxx`）會隨著目錄中目前的段落自動更新
`navigation.tabs`	第一層區段變成頁首下方的頁籤（視窗寬度超過 1220px 時）
`navigation.tabs.sticky`	頁籤固定在頁首下方，捲動時不消失（需搭配 `navigation.tabs`）
`navigation.sections`	第一層區段在側邊欄以群組呈現。與 `navigation.tabs` 併用時，改成第二層區段
`navigation.expand`	預設展開所有可摺疊的子區段
`navigation.path`	每頁標題上方顯示麵包屑導覽
`navigation.prune`	只輸出目前可見的導覽項目，可讓網站體積減少 33% 以上，適合上千頁的網站
`navigation.indexes`	區段可以直接掛一份文件（`index.md`），當作該區段的概覽頁
`navigation.top`	往上捲動時，頁面底部中央出現「回到頂端」按鈕
`toc.follow`	右側目錄會自動捲動，讓目前的段落一直在視野中
`toc.integrate`	目錄併入左側導覽，不再另外顯示在右側

有些旗標不能同時使用

navigation.prune 與 navigation.expand 不相容：展開需要完整的導覽結構。
navigation.indexes 與 toc.integrate 不相容：區段沒有空間放目錄。
navigation.instant 與 navigation.instant.prefetch/progress 都需要設定 site_url。

區段索引頁（`navigation.indexes`）

啟用後，在資料夾建立 index.md，並把它放在該區段的第一項：

[project]
nav = [
  { "教學" = [
    "tutorial/index.md",
    { "第一章" = "tutorial/chapter-1.md" },
    { "第二章" = "tutorial/chapter-2.md" },
  ] },
]

README.md 也會被視為索引頁。本教學網站就啟用了這個旗標。

即時預覽（Instant previews）

即時預覽可以讓讀者不離開目前頁面，就看到另一頁某個段落的內容。在指向其他頁標題的內部連結加上 data-preview 屬性即可（需要 attr_list）：

[Attribute Lists](customization.md#extra-css){ data-preview }

限制

這仍是實驗性功能，目前只支援指向標題（header）的連結，不支援其他帶有 id 的元素。需要設定 site_url。

自動預覽

不想每個連結都手寫 data-preview 的話，可以用內建的擴充，依頁面或資料夾整批啟用：

[[project.markdown_extensions.zensical.extensions.preview.configurations]]
targets.include = [
  "customization.md",
  "compatibility/markdown/*",
]

targets：被連到的頁面，指向這些頁面的連結會啟用預覽（官方建議做法）。
sources：連結所在的頁面。省略時，所有頁面都啟用。
include / exclude 支援萬用字元；同時符合時，排除優先。
可以定義多組 configurations，精確控制哪裡要顯示預覽。

單頁隱藏側邊欄

在頁面的 front matter 用 hide 隱藏導覽、目錄或麵包屑：

---
hide:
  - navigation
  - toc
  - path
---

完整的 hide 選項見 Front matter。

調整內容區寬度

內容區預設寬度會讓每行約 80～100 個字元，方便閱讀。想加寬，用一小段 CSS：

docs/css/extra.css

.md-grid {
  max-width: 1440px;
}

想讓內容永遠填滿整個螢幕：

.md-grid {
  max-width: initial;
}

別忘了在 extra_css 載入這個檔案，見網站客製化。

總結

想做的事	怎麼做
自訂導覽結構	`nav = [...]`
不整頁重新載入	`navigation.instant`（記得設 `site_url`）
頂端頁籤	`navigation.tabs`（可加 `.sticky`）
每個區段有概覽頁	`navigation.indexes`
麵包屑	`navigation.path`
回到頂端按鈕	`navigation.top`
預覽其他頁的段落	連結加上 `{ data-preview }`
單頁隱藏側邊欄	front matter 的 `hide`

參考資料

Navigation - Zensical