標籤（Tags）

文件愈來愈多時，可以替頁面加上標籤分類，讀者就能透過搜尋找到相關的頁面。Zensical 原生實作了 tags 外掛，設定方式沿用 Material for MkDocs。

啟用標籤

不需要另外安裝任何套件，在 zensical.toml 加上：

[project.plugins.tags]

（在 mkdocs.yml 則是 plugins: 底下加一行 - tags。）

用 front matter 的 tags 屬性：

---
tags:
  - HTML5
  - JavaScript
  - CSS
---

# 頁面標題

頁面底部會顯示這些標籤，讀者也可以在搜尋中用標籤篩選，不需要額外設定。

---
hide:
  - tags
---

每個標籤可以搭配一個圖示。做法是兩步：

步驟 1：替標籤指定「識別字」（只能包含英數字、連字號、底線）：

[project.extra.tags]
HTML5 = "html"
JavaScript = "js"
CSS = "css"

同一個識別字可以給多個標籤共用，就等於把一群標籤指定成同一個圖示。沒有指定識別字的標籤，會使用預設圖示。

步驟 2：替識別字指定圖示：

[project.theme.icon.tag]
default = "lucide/hash"
html = "fontawesome/brands/html5"
js = "fontawesome/brands/js"
css = "fontawesome/brands/css3"

官方表示，標籤外掛支援 Material for MkDocs 既有的設定，包括標籤清單與進階設定，用法請參考原外掛文件。若要建立標籤索引頁，把  放在該頁內容中。

已被忽略的舊設定

從 Material for MkDocs 遷移時，下列舊設定會被悄悄忽略，需要改名或改寫：

舊設定	請改用
`tags_compare`	`tags_sort_by`
`tags_compare_reverse`	`tags_sort_reverse`
`tags_pages_compare`	`listings_sort_by`
`tags_pages_compare_reverse`	`listings_sort_reverse`
`tags_file`、`tags_extra_files`	在索引頁加上 `<!-- material/tags -->`
`export`、`export_file`、`export_only`	沒有替代方案（原生標籤不匯出 JSON）

此外，自訂的 Python 函式（tags_slugify、tags_sort_by、listings_sort_by、listings_tags_sort_by）不被支援，請改用 Material for MkDocs 文件所列的內建函式。

步驟	設定
啟用	`[project.plugins.tags]`
加標籤	front matter `tags`
標籤圖示	`[project.extra.tags]` + `[project.theme.icon.tag]`
隱藏標籤	front matter `hide: [tags]`