跳轉至

部落格（Blog）

Zensical 0.0.64 開始內建原生的 blog 外掛。你可以把部落格放在文件旁邊，也可以讓整個網站就是一個部落格。它會自動產生最新文章列表、封存頁、分類頁、作者頁與分頁。

需要 Zensical 0.0.64 以上

blog 是 2026-09-22 釋出的 0.0.64 才加入的功能。用 pip show zensical 或 uv pip show zensical 確認版本，需要時依 基本操作指令裡的「升級 Zensical」升級。

直接移植自 Material for MkDocs

Zensical 目前的部落格是 Material for MkDocs blog 外掛的原生移植，設定、文章中繼資料、網址、封存、分類、作者、分頁的行為都維持原樣，所以所有設定選項與文章欄位，都以 Material for MkDocs 的 blog 文件為準。官方表示之後會推出更適合 Zensical 的彈性部落格功能。

運作方式

Zensical 會掃描文章資料夾裡的 Markdown 檔案，產生分頁的「檢視頁」。預設的目錄結構如下：

.
├─ docs/
│  └─ blog/
│     ├─ posts/
│     └─ index.md
└─ zensical.toml
  • blog/index.md 是部落格的入口，會變成依時間倒序（新到舊）列出文章的分頁頁面。
  • 另外會自動產生封存頁、分類頁，以及（開啟時）作者頁。
  • 文章可以放在巢狀資料夾，因為網址是由標題、日期與設定的網址格式產生，跟檔案放哪裡無關。
  • 日期會依網站語言（theme.language）顯示。
  • 文章可以使用和其他頁面一樣的 Markdown 語法（提示框、程式區塊、頁簽、圖表……）。

啟用部落格

[project.plugins.blog]

（在 mkdocs.yml 則是 plugins: 底下加上 - blog。）

已經在用 Material for MkDocs 的 blog 外掛的話，Zensical 同時認得 blog 與 material/blog 兩種寫法、預設的 blog/ 資料夾、.authors.yml 與既有的文章中繼資料，不必另外安裝任何套件。

導覽

  • 自動產生導覽：什麼都不用設定，封存與分類頁會自動出現在導覽底下。
  • 明確定義 nav：只加入部落格的入口頁，不要列出個別文章：
[project]
nav = [
  "index.md",
  { "Blog" = ["blog/index.md"] },
]

導覽項目的名稱可以任意取，例如「最新消息」或「技術文章」，但路徑必須和 blog_dir 一致。搭配 navigation.indexes（見 導覽設定）可以讓部落格區段直接使用 blog/index.md 當概覽頁。

寫第一篇文章

在 blog/posts/ 底下建立 Markdown 檔（可放在子資料夾）。每篇文章都必須有建立日期（沒有日期會讓建置失敗），其他中繼資料一樣寫在 Front matter：

docs/blog/posts/hello-world.md
---
date: 2026-09-22
categories:
  - Hello
  - World
---

# Hello world!

歡迎來到我們的新部落格。
  • 草稿：加上 draft: true，文章在預覽（zensical serve）時會顯示，一般建置則預設不包含。準備發佈時，拿掉這行即可。
  • 更新日期：日期可以同時記錄建立與更新：
date:
  created: 2026-09-22
  updated: 2026-09-24

啟動 zensical serve，就能在部落格、封存與分類頁看到這篇文章。

摘要（Excerpt）

部落格的列表頁可以只顯示摘要。在前幾段介紹文字之後加入分隔標記 <!-- more -->：

# Hello world!

這段介紹會顯示在部落格列表頁。

<!-- more -->

完整內容從這裡開始。

標記之前的內容就是摘要；沒有標記的話，列表頁會顯示整篇文章（除非設定 post_excerpt: required，此時沒有標記會直接報錯）。

作者

在部落格資料夾建立 .authors.yml，用一個固定的識別字定義每位作者：

docs/blog/.authors.yml
authors:
  jane:
    name: Jane Doe
    description: 技術作家
    avatar: https://example.com/jane.png

每位作者可以設定 name、description、avatar、slug（作者頁網址）、url（個人網站）。文章裡用識別字引用，可以有多位作者；找不到對應作者時，建置會失敗：

---
date: 2026-09-22
authors:
  - jane
---

分類

在文章加上一個或多個分類，就會出現在自動產生的分類頁：

---
date: 2026-09-22
categories:
  - Releases
  - Engineering
---

分類名稱可以包含空白與中文（實測中文分類會產生 blog/category/教學/ 這樣的網址）。用 categories_allowed 限定可用分類，可以在建置時抓出打錯字：

[project.plugins.blog]
categories_allowed = ["Releases", "Engineering"]

文章使用了不在清單內的分類，建置會直接停止。

相關連結

links 會在文章側邊欄顯示相關連結，語法和 nav 相同，支援區段、外部網址與錨點：

---
date: 2026-09-22
links:
  - 開始使用: zensical_basics.md
  - 延伸閱讀:
      - 官方網站: https://zensical.org
      - 導覽設定: zensical_navigation.md
---

連結到文章與圖片

用文章的 Markdown 原始檔路徑連結，Zensical 會自動換成正確網址：

[Hello world!](blog/posts/hello-world.md)

放在文章旁邊或底下的圖片等資源，會被搬到產生的部落格資源目錄，文章與摘要中的連結也會自動改寫。

文章的中繼資料

欄位 說明
date 必填。文章日期；也可以用 created、updated 與自訂日期
draft true 時視為草稿
authors 作者識別字清單（定義在 .authors.yml）
categories 分類清單
pin true 時置頂在列表最前面（多篇置頂時依日期新到舊排序）
links 側邊欄的相關連結
readtime 手動指定閱讀時間（分鐘）
slug 自訂網址中的 slug

中日韓文章的閱讀時間不準

自動計算的閱讀時間目前不會處理中日韓文字的斷詞，中文文章的估計會不準確。建議用 readtime 欄位手動指定。

常用的外掛設定

所有設定都放在 [project.plugins.blog]。下面是常用的選項與預設值：

[project.plugins.blog]
blog_dir = "blog"                    # 部落格所在資料夾（"." 表示整站就是部落格）
post_dir = "{blog}/posts"            # 文章資料夾
post_date_format = "long"            # 文章日期格式：full / long / medium / short，或 babel 格式
post_url_format = "{date}/{slug}"    # 文章網址格式
post_url_date_format = "yyyy/MM/dd"  # 網址中的日期格式
post_excerpt = "optional"            # 摘要：optional / required
post_readtime = true                 # 自動計算閱讀時間
archive = true                       # 產生封存頁
categories = true                    # 產生分類頁
authors = true                       # 讀取 .authors.yml 並顯示作者
authors_profiles = false             # 產生作者個人頁
pagination_per_page = 10             # 每頁文章數
draft = false                        # 建置時是否包含草稿
draft_on_serve = true                # 預覽時是否包含草稿
draft_if_future_date = false         # 未來日期的文章視為草稿
想做的事 設定
整站就是部落格 blog_dir = "."
網址不含日期 post_url_format = "{slug}"
網址只含年份 post_url_date_format = "yyyy"
網址含分類 post_url_format = "{categories}/{slug}"，搭配 post_url_max_categories
每頁顯示的文章數 pagination_per_page = 5
分類頁／封存頁／作者頁的名稱與網址 categories_name、categories_url_format、archive_name、archive_url_format、authors_profiles_name、authors_profiles_url_format
限制摘要中顯示的作者／分類數 post_excerpt_max_authors、post_excerpt_max_categories
依文章數排序分類 categories_sort_by、categories_sort_reverse
列表頁用目錄顯示文章標題 blog_toc = true（也可個別設定 archive_toc、categories_toc、authors_profiles_toc）
未來日期的文章先不發佈 draft_if_future_date = true，日期到了就自動發佈

更多選項

分頁格式（pagination_format）、分頁網址（pagination_url_format）、slug 的分隔字元（post_slugify_separator）等進階選項，請查 Material for MkDocs 的 blog 文件。

不支援的部分

自訂的 Python 函式（例如自己寫的 post_slugify、categories_sort_by）不被支援，只能使用內建的策略。從 Material for MkDocs 遷移時，如果用到自訂函式，請先檢查。

實測驗證

本頁的行為是在 Zensical 0.0.64 上實際建置驗證過的：

  • 日期式文章網址（blog/2026/09/01/hello-world/）、封存頁、分類頁（含中文分類）、作者頁與分頁都會產生。
  • draft: true 與未來日期（搭配 draft_if_future_date）的文章不會出現在一般建置。
  • pin: true 的文章會排在最前面。
  • 使用不在 categories_allowed 的分類，或文章缺少 date，建置都會失敗並指出檔案。
  • blog 與 material/blog 兩種寫法都可以使用。

總結

步驟 做法
啟用 [project.plugins.blog]（需 Zensical 0.0.64+）
入口頁 docs/blog/index.md
寫文章 docs/blog/posts/*.md，front matter 必須有 date
摘要 <!-- more -->
作者 docs/blog/.authors.yml + authors:
分類 categories:，可用 categories_allowed 限制
草稿 draft: true
導覽 只加入 blog/index.md，不要列出文章

參考資料