Skip to content

Zensical 簡介

🔹 Zensical 是什麼？

Zensical 是由 Material for MkDocs 原班人馬打造的 新一代靜態網站產生器，專門用來建立技術文件網站。內容用 Markdown 撰寫，再轉換成 HTML 靜態網站。

📌 特點：

  • 用 Markdown 撰寫（簡單、直觀）
  • 速度快（產生靜態 HTML，沒有伺服器負擔）
  • 適合技術文件（API 文件、教學、知識庫）
  • 可部署在 GitHub Pages、Netlify、Vercel
  • 內建搜尋、提示框、頁簽、程式碼高亮、Mermaid 圖表
  • 可用 classic 主題變體，外觀接近 Material for MkDocs

設定檔建議使用 zensical.toml。為了方便從 Material for MkDocs 遷移，Zensical 也能讀取 mkdocs.yml。

🔹 跟 MkDocs、Material for MkDocs 的關係

MkDocs 是較早的靜態網站產生器；Material for MkDocs 是它最常用的佈景主題。Zensical 則是同一團隊推出的後繼專案，目標是在保留熟悉寫作體驗的同時，改善架構與擴充能力。

📌 你可以這樣理解：

  • MkDocs：把 Markdown 轉成網站的工具
  • Material for MkDocs：讓 MkDocs 網站更好看、更好用的主題
  • Zensical：同一套設計理念的新工具，建議用 zensical.toml 設定，指令改為 zensical serve / zensical build

📌 Zensical vs Material for MkDocs 有什麼差別？

比較項目 Material for MkDocs Zensical
用途 MkDocs 的佈景主題 獨立的靜態網站產生器
設定檔 mkdocs.yml 建議 zensical.toml（仍可讀 mkdocs.yml）
指令 mkdocs serve / mkdocs build zensical serve / zensical build
外觀 Material Design classic 接近原主題；另有 modern
圖示 / Emoji material.extensions.emoji zensical.extensions.emoji
佈署指令 有 mkdocs gh-deploy 沒有 gh-deploy，改用 GitHub Actions 或自行上傳 site/

簡單來說：

  • 寫作語法大多相同（Admonition、Tabs、程式區塊、Mermaid 等）。
  • 設定語法從 YAML 改成 TOML。
  • 部分 MkDocs 插件（部落格、RSS、Social Cards、Jupyter、Markmap）目前還沒有 Zensical 原生對應。

📌 Zensical vs 其他常見工具

Warning

底下的比較表跟優缺點分析可以當作入門參考，實際選擇仍要看自己的需求。

比較項目 Zensical Blogger Google Sites WordPress
主要用途 技術文件、知識庫 部落格、文章 公司內部網頁、簡單網站 部落格、企業網站
內容格式 Markdown WYSIWYG / HTML WYSIWYG WYSIWYG / HTML
SEO 友善 ✅ 需要手動設定 ✅ 內建 ❌ 不適合 SEO ✅ 內建強大 SEO
外觀客製化 ✅ 可自訂 CSS / JS ❌ 內建主題有限 ❌ 幾乎無法客製化 ✅ 支援多種佈景主題
是否支援程式碼高亮 ✅ 內建 ❌ 需額外設定 ❌ 不支援 ⚠️ 需要外掛
適合技術文件 ✅ 非常適合 ❌ 不適合 ❌ 不適合 ⚠️ 可用，但不是最佳選擇
部署方式 GitHub Pages / Netlify / Vercel Google 託管 Google 託管 自行選擇伺服器
維護成本 低 最低 最低 中等（需管理伺服器）

📌 優缺點分析

⭕ Zensical 優點

  1. 適合技術文件：特別適合 API 文件、教學、知識庫。
  2. Markdown 撰寫：比 Blogger / WordPress 更簡單直觀。
  3. 靜態網站，載入超快：不需要後端，部署在 GitHub Pages 或 Netlify 完全免費。
  4. 支援全文搜尋：內建搜尋功能，方便讀者查找內容。
  5. 高度可客製化：可以修改 CSS、JS，甚至覆寫模板。
  6. 從 Material for MkDocs 遷移成本低：多數 Markdown 寫法可以直接沿用。

❌ Zensical 缺點

  1. 需要 Git / Markdown 基礎：不像 Blogger/WordPress 可以直接編輯，需要學習 Git + Markdown。
  2. 不適合動態內容：不支援留言、用戶登入、後台管理等功能。
  3. 部分插件尚未到位：部落格、RSS、社交卡片、Jupyter Notebook、心智圖等需等官方支援或自行實作。

📌 什麼情況應該選 Zensical？

⭕ 適合使用 Zensical 的情境

  • 你需要 技術文件網站、API 文件、知識庫（如：程式教學、學習指南）
  • 你習慣使用 Markdown
  • 你已經在用 Material for MkDocs，想遷移到新工具
  • 你希望 部署在 GitHub Pages / Netlify（免費）

❌ 不適合 Zensical 的情境

  • 你希望 不寫程式就能管理網站 → 選 Google Sites
  • 你需要 支援使用者留言、會員功能 → 選 WordPress
  • 你主要想寫 內建部落格 / RSS → 目前先選 Material for MkDocs 或等 Zensical 支援

📝 結論

你需要 最佳選擇
技術文件 / API 文件 / 知識庫 Zensical
已有 Material for MkDocs 專案要遷移 Zensical（classic 變體）
一般部落格 Blogger / WordPress
簡單企業網站 / 內部網站 Google Sites
自訂網站 + 商業用途 WordPress / 自架網站

📌 如果你的需求是技術文件，Zensical 是目前很值得學的選擇！
📌 如果你只是寫部落格，Blogger 或 WordPress 會更適合！