`icons` 及 `logo` 設定

在 Zensical 中，你可以透過 zensical.toml 來設定 網站圖示（icons）、標誌（logo），以及其他視覺元素。安裝後即可使用超過 10,000 個內建圖示。

設定網站 Logo（標誌）

可以用圖片檔（放在 docs/ 底下）：

[project.theme]
logo = "images/logo.png"

也可以改用內建圖示：

[project.theme.icon]
logo = "fontawesome/solid/landmark"

📌 說明：

圖片需放在 docs/ 目錄下，可使用 .png、.svg 等格式。
內建圖示路徑例如 lucide/smile、fontawesome/solid/landmark。
Logo 預設會連到首頁（等同 site_url）。若要改連到其他網址：

[project.extra]
homepage = "https://www.vcdemy.com"

設定網站 Favicon（網站標籤小圖示）

[project.theme]
favicon = "images/favicon.png"

📌 Favicon 是瀏覽器標籤上的小圖示（常見為 16x16 或 32x32）。

設定 Header / Footer 圖示（Icons）

Zensical 內建 Material Icons、FontAwesome、Lucide 等圖示集，你可以這樣設定頁尾社交連結：

[[project.extra.social]]
icon = "fontawesome/brands/github"
link = "https://github.com/your-repo"

[[project.extra.social]]
icon = "fontawesome/brands/linkedin"
link = "https://linkedin.com/in/your-profile"

[[project.extra.social]]
icon = "material/email"
link = "mailto:your@email.com"

📌 圖示來源：

material/* → Material Design Icons
fontawesome/brands/* → FontAwesome 品牌圖示
lucide/* → Lucide 圖示

📌 常見 Icons

圖示名稱	範例
`material/github`
`material/email`
`material/twitter`
`fontawesome/brands/facebook`
`fontawesome/brands/instagram`

設定導航欄 Icons

要在側邊導覽標題旁出現圖示，只需在 .md 檔最前面加入 front matter：

---
icon: material/library
---

📌 這樣你的導覽項目旁邊就會有 library 圖示了！

正文裡也可以用 shortcode 插入圖示，例如 :material-rocket-launch: →

自訂圖示

若要加入額外圖示，在 overrides/.icons/ 放入 *.svg，並設定：

[project.theme]
custom_dir = "overrides"

[project.markdown_extensions.pymdownx.emoji]
emoji_generator = "zensical.extensions.emoji.to_svg"
emoji_index = "zensical.extensions.emoji.twemoji"
options.custom_icons = [
  "overrides/.icons",
]

假設檔案是 overrides/.icons/bootstrap/envelope-paper.svg：

設定檔寫：bootstrap/envelope-paper
Markdown 寫：:bootstrap-envelope-paper:

內建的圖示集

Zensical 內建超過 10,000 個圖示，來自五個圖示集：

圖示集	路徑前綴	Markdown 範例
Lucide	`lucide/`	`:lucide-check:`
Material Design	`material/`	`:material-rocket-launch:`
FontAwesome	`fontawesome/`（`brands`、`solid`、`regular`）	`:fontawesome-brands-github:`
Octicons	`octicons/`	`:octicons-heart-fill-24:`
Simple Icons	`simple/`	`:simple-python:`

設定檔用路徑（material/pencil），Markdown 裡用簡碼：把 / 換成 -，前後加冒號。

幫圖示加上顏色與動畫

需要啟用 attr_list。先在 extra.css 定義 CSS class：

.youtube {
  color: #EE0F0F;
}

@keyframes heart {
  0%, 40%, 80%, 100% { transform: scale(1); }
  20%, 60%           { transform: scale(1.15); }
}

.heart {
  animation: heart 1000ms infinite;
}

再把 class 加到圖示上：

:fontawesome-brands-youtube:{ .youtube }
:octicons-heart-fill-24:{ .heart }

可更換的網站圖示

網站上大部分的圖示都可以在 [project.theme.icon] 更換，例如頁尾的上一頁／下一頁箭頭：

[project.theme.icon]
previous = "fontawesome/solid/angle-left"
next = "fontawesome/solid/angle-right"

完整清單：

名稱	用途
`logo`	網站 Logo
`menu`	開啟側邊欄（手機）
`alternate`	切換語言（見語言）
`search`	搜尋圖示
`share`	分享搜尋
`close`	重設搜尋、關閉公告
`top`	回到頂端按鈕
`edit`	編輯此頁
`view`	檢視原始碼
`repo`	程式庫圖示（見程式庫連結）
`admonition`	提示框圖示（見提示框）
`tag`	標籤圖示（見標籤）
`previous`	頁尾上一頁、手機上收起搜尋
`next`	頁尾下一頁

總結

設定項目	設定方式
Logo（圖片）	`theme.logo = "images/logo.png"`
Logo（圖示）	`theme.icon.logo = "lucide/smile"`
Favicon	`theme.favicon = "images/favicon.png"`
社交 Icons	`[[project.extra.social]]`
導航欄 Icons	在 front matter 中設定 `icon`
自訂 Icons	`overrides/.icons` + `custom_icons`
更換網站圖示	`[project.theme.icon]`（`previous`、`next`、`repo`、`edit` 等）
圖示顏色／動畫	`:圖示:{ .class }` + CSS

這樣你就能輕鬆自訂 Zensical 的圖示、Logo、Favicon！

參考資料

Logo and icons - Zensical

icons 及 logo 設定