資訊提示框 (Admonitions)

在 Zensical 中，Admonitions 是用來顯示提示框（註解、警告、資訊等）的元件。這些提示框可以用來強調內容，讓讀者更容易理解重點。寫法與 Material for MkDocs 相同。

`zensical.toml` 設定

[project.markdown_extensions]
admonition = {}
pymdownx.details = {}
pymdownx.superfences = {}

基本使用

你可以使用 !!! 來創建 Admonition，格式如下：

!!! type
    這是提示框的內容

其中，type 可以是以下類型：

note（筆記）
abstract（摘要）
info（資訊）
tip（提示）
success（成功）
question（問題）
warning（警告）
failure（失敗）
danger（危險）
bug（錯誤）
example（範例）
quote（引言）

📌 範例

!!! note
    這是一個 **筆記** 提示框。

!!! warning
    **警告！** 這段內容可能會影響系統安全性。

!!! success
    恭喜！你已經完成這個章節的學習。

Note

這是一個筆記提示框。

Warning

警告！ 這段內容可能會影響系統安全性。

Success

恭喜！你已經完成這個章節的學習。

自訂標題

你可以在 !!! 後面加上標題：

!!! tip "小技巧"
    這是一個自訂標題的提示框。

小技巧

這是一個自訂標題的提示框。

內部使用 Markdown

你可以在 Admonition 內使用 Markdown 語法：

!!! info "格式範例"
    - 這是一個列表項目
    - **這是粗體**
    - *這是斜體*

格式範例

這是一個列表項目
這是粗體
這是斜體

可摺疊的 Admonitions

如果你想讓 Admonition 預設為摺疊（點擊展開），可以加上 ?：

??? example "點擊展開範例"
    這是一個可以摺疊的提示框。

點擊展開範例

這是一個可以摺疊的提示框。

自訂樣式

你可以透過 CSS 自訂樣式，例如：

.md-typeset .admonition.custom {
    background-color: #ffebcd;
    border-left: 4px solid #ff4500;
}

然後在 Markdown 內使用：

!!! custom "自訂顏色"
    這是一個自訂顏色的 Admonition。

自訂顏色

這是一個自訂顏色的 Admonition。

移除標題

在類型後面加上空字串 ""，就會連圖示與標題都不顯示（不適用於可摺疊的提示框）：

!!! note ""
    這個提示框沒有標題。

這個提示框沒有標題。

巢狀提示框

提示框裡面還可以放提示框，只要內層再多縮排四個空格：

!!! question "外層"
    這是外層提示框。

    !!! success "內層"
        這是內層提示框。

外層

這是外層提示框。

內層

這是內層提示框。

行內提示框（側邊欄）

加上 inline（放左邊）或 inline end（放右邊），提示框就會變成內文旁邊的側邊欄：

!!! info inline end "側邊小提醒"
    這個提示框會靠右，和後面的文字並排。

這一段文字會顯示在提示框的左邊。行內提示框**必須寫在**想並排的內容**之前**。

側邊小提醒

這個提示框會靠右，和後面的文字並排。

這一段文字會顯示在提示框的左邊。行內提示框必須寫在想並排的內容之前。空間不夠時（例如手機），提示框會拉滿整個寬度。

inline end 在由右到左（rtl）的語言中會靠左，inline 則相反。

更換提示框圖示

每種類型都有專屬的圖示，可以在 zensical.toml 換成任何內建圖示，甚至自訂圖示：

[project.theme.icon.admonition]
note = "octicons/tag-16"
abstract = "octicons/checklist-16"
info = "octicons/info-16"
tip = "octicons/squirrel-16"
success = "octicons/check-16"
question = "octicons/question-16"
warning = "octicons/alert-16"
failure = "octicons/x-circle-16"
danger = "octicons/zap-16"
bug = "octicons/bug-16"
example = "octicons/beaker-16"
quote = "octicons/quote-16"

想用 FontAwesome 圖示的話，把值換成 fontawesome/solid/...，例如 note = "fontawesome/solid/note-sticky"、tip = "fontawesome/solid/bullhorn"。

GitHub Callouts

除了 !!! 語法之外，也可以使用 GitHub 的 callouts（又稱 alerts）。它們是帶有特殊標記的引用區塊，好處是在 GitHub、GitLab 與其他支援的工具裡也能正常顯示。

設定：啟用 Python Markdown Extensions 內建的 Quotes 擴充，並開啟 callouts：

[project.markdown_extensions.pymdownx.quotes]
callouts = true

用法：引用符號 > 後面接 [!類型]，內容每行都要加 >：

> [!NOTE]
> 這是 GitHub 風格的 callout。

Note

這是 GitHub 風格的 callout。

GitHub 支援五種類型：[!NOTE]、[!TIP]、[!WARNING]、[!IMPORTANT]、[!CAUTION]。前三種直接對應到內建的 note、tip、warning；important 與 caution 不是內建的 admonition 類型，會使用預設樣式，除非你自己加 CSS。

注意

標記必須是全大寫，小寫（例如 [!note]）在 GitHub 上不會被辨識。另外，callouts 不屬於 GitHub Flavored Markdown 規格，並非所有 GFM 解析器都支援。

啟用 Quotes 擴充後，也可以使用 Zensical 支援的任何 admonition 類型，不限於這五種。

沿用 mkdocs-callouts 外掛

如果你的 MkDocs 專案用的是 mkdocs-callouts 外掛（Obsidian 風格的 callouts），Zensical 自 0.0.62 起直接支援：外掛條目會自動啟用 pymdownx.quotes 的 callouts: true，但外掛的 aliases、breakless_lists、title_from_first_bold 三個設定會被忽略。

總結

!!! type 用來創建提示框
!!! type "標題" 來自訂標題
??? type "標題" 讓提示框可摺疊
可使用 Markdown 內容
透過 CSS 自訂樣式
!!! type "" 移除標題；inline / inline end 做成側邊欄
用 theme.icon.admonition 更換圖示
用 pymdownx.quotes 的 callouts = true 支援 GitHub 的 > [!NOTE] 語法

這樣就能靈活運用 Admonitions 讓你的 Zensical 文件更具可讀性！

參考資料

Admonitions - Zensical