Skip to content

網站客製化

你可以透過 TOML 設定、CSS、自訂 HTML、JavaScript 等方式來 客製化 Zensical，讓網站符合你的需求。

Note

顏色、字型、圖示、Logo 另有專章，這裡著重在整體客製化流程。

修改 zensical.toml（基本客製化）

在 zensical.toml 進行基本客製化設定：

[project.theme]
variant = "classic"
features = [
  "navigation.tabs",
  "navigation.sections",
  "content.code.copy",
]

[project.theme.palette]
scheme = "slate"
primary = "indigo"
accent = "pink"

[project.theme]
font.text = "Roboto"
font.code = "Fira Code"

📌 這可以客製化：

  • 主題變體（classic 接近 Material for MkDocs，modern 為新外觀）
  • 顏色主題（palette）
  • 字體設定（font）
  • 導覽選項（navigation.tabs、navigation.sections）
  • 代碼顯示功能（content.code.copy）

客製化 CSS

你可以使用 自訂 CSS 來調整樣式。

步驟 1：建立 extra.css

在 docs/css/extra.css 加入：

/* 修改標題顏色 */
.md-typeset h1 {
    color: #ff4081;
}

/* 修改表格內文字垂直置中 */
.md-typeset table td {
    vertical-align: middle;
}

/* 修改側邊欄背景 */
.md-sidebar {
    background-color: #333;
}

步驟 2：在 zensical.toml 啟用

[project]
extra_css = [
  "css/extra.css",
]

自訂 Logo、Icons

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

設定社交媒體 Icons

[[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"

自訂 HTML 頁面

你可以建立 overrides/ 目錄來覆蓋預設的 HTML。Zensical 使用 MiniJinja 模板（與 Jinja 大部分相容）。

步驟 1：建立 overrides/ 目錄

.
├── overrides/
│   ├── main.html
│   └── partials/
│       └── footer.html
└── zensical.toml

步驟 2：啟用 overrides/

[project.theme]
custom_dir = "overrides"

常見可覆寫區塊包含 extrahead、content、footer、header、analytics 等。

加入 JavaScript

如果你需要額外的 互動效果，可以加入 JavaScript。

步驟 1：建立 extra.js

在 docs/js/extra.js 加入：

document.addEventListener("DOMContentLoaded", function() {
    console.log("Hello from extra.js!");
});

步驟 2：在 zensical.toml 載入

[project]
extra_javascript = [
  "js/extra.js",
]

總結

客製化項目 設定方式
修改主題顏色 palette.primary / palette.accent
修改字體 font.text / font.code
自訂 CSS extra_css = ["css/extra.css"]
自訂 Logo & Icons theme.logo、[[project.extra.social]]
自訂 HTML 結構 建立 overrides/，啟用 custom_dir
加入 JavaScript extra_javascript = ["js/extra.js"]

📌 這些設定能夠讓你的 Zensical 網站變得更獨特！

參考資料