網站客製化

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

修改 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

設定網站 Logo

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

以模組、非同步或延遲方式載入 JavaScript

extra_javascript 的項目除了字串，也可以寫成帶有屬性的表：

[project]
extra_javascript = [
  { path = "js/extra.js", type = "module" },
  { path = "js/analytics.js", async = true },
  { path = "js/other.js", defer = true },
]

• 檔案副檔名是 .mjs 時，Zensical 會自動當成 JavaScript 模組（type="module"）。這個自動偵測只適用於純字串的項目。
• 因此，如果想以模組載入又要用 async，就必須明確寫出 type = "module"。

自訂 404 錯誤頁面

在 overrides/ 資料夾放一個 404.html，就可以自訂找不到頁面時的畫面。這個檔案可以在網頁伺服器設定為後備頁面：

.
├── overrides/
│   └── 404.html
└── zensical.toml

Zensical 本來就有預設的 404.html，所以只有想改內容時才需要建立。

覆寫模板區塊（建議做法）

覆寫模板有兩種方式：覆寫整個模板／partial，或覆寫模板中的區塊（block），官方建議使用區塊。

Zensical 的 main.html 繼承自 base.html。最穩當的方式是覆寫 main.html，而不是 base.html，因為 base.html 在未來版本更可能改變。

例如覆寫網站標題：

{% extends "base.html" %}

{% block htmltitle %}
  <title>唯客學院 Zensical 教學</title>
{% endblock %}

如果是追加而不是取代內容，在區塊裡使用 {{ super() }} 保留原本的內容，這在加入第三方 script 時特別好用：

{% extends "base.html" %}

{% block scripts %}
  <!-- 需要先執行的 script -->
  {{ super() }}
  <!-- 需要後執行的 script -->
{% endblock %}

主題提供的區塊：

覆寫 partial

也可以用同樣的檔名與位置取代整個 partial。例如要換掉頁尾，就建立 overrides/partials/footer.html，Zensical 就會改用你的版本（見 設定頁尾）。

自訂單頁模板

有些頁面需要不同的結構，例如首頁或參考頁。在 overrides/ 新增模板（檔名不可以和 Zensical 內建的 main.html、base.html 等重複），再用 front matter 指定給特定頁面：

---
template: "my_template.html"
---

MiniJinja 相容性

Zensical 使用 MiniJinja，不能呼叫任意的 Python 函式。如果覆寫中呼叫了無法用 MiniJinja 過濾器或測試取代的 Python 函式，就必須改由 Zensical 模組或其他支援的客製化機制提供。以 Material for MkDocs 9.6.18 或更新版本為基礎的覆寫，通常不需修改，見 從 MkDocs 遷移。

把主題打包成 Python 套件

想和別人分享你的主題擴充，可以把它打包成 Python 套件，讓使用者用 pip 安裝，並在設定裡用名稱引用。做法與 MkDocs 相同，透過 mkdocs.themes 進入點（entry point），所以既有的 Material for MkDocs 主題衍生品只要少量修改就能在 Zensical 執行。

建議的結構：

.
├─ pyproject.toml
└─ my_theme/
   ├─ __init__.py          # 必要，可以是空的
   ├─ main.html
   └─ mkdocs_theme.yml     # 選填

pyproject.toml 的重點是宣告進入點：

[project]
name = "my-theme"
version = "0.1.0"
dependencies = ["zensical>=0.0.37"]

[project.entry-points."mkdocs.themes"]
my_theme = "my_theme"

左邊的 my_theme 是使用者在設定檔中使用的名稱，右邊是套件內放主題檔案的資料夾。mkdocs_theme.yml 可以設定主題的預設值並宣告延伸自哪個主題（預設主題目前為了相容，名稱仍然是 material）：

extends: material
font:
  text: Roboto
  code: Roboto

使用者安裝後這樣引用：

[project.theme]
name = "my_theme"

總結

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

參考資料

• Customization - Zensical