圖片（Images）

圖片是 Markdown 的核心語法，但實際排版常常不好處理。Zensical 提供了圖片對齊與圖片標題的樣式，讓圖片更好用。

`zensical.toml` 設定

[project.markdown_extensions]
attr_list = {}
md_in_html = {}
pymdownx.blocks.caption = {}

圖片對齊

在圖片後面用 align 屬性指定靠左或靠右（需要 attr_list）：

原始程式

![Zensical](images/landmark-solid.svg){ align=left width=120 }

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.

輸出結果

Zensical

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

align=right 則是靠右。如果旁邊沒有足夠空間放文字（例如手機），圖片會拉滿整個寬度。

為什麼沒有置中對齊？

align 屬性不支援置中，所以 Zensical 也不提供。要置中請改用下面的圖片標題語法（標題是選填的）。另外，align 在 HTML5 已被棄用，但保留它是為了可攜性：Markdown 檔在 Zensical 之外的地方檢視時，仍然能看到一致的樣子。

圖片標題

標準 Markdown 沒有圖片標題的語法。有兩種方式：

方式 1：用 figure 與 figcaption（需要 md_in_html）

<figure markdown="span">
  ![圖片說明](images/landmark-solid.svg){ width="120" }
  <figcaption>圖片標題</figcaption>
</figure>

方式 2：用 Caption 擴充（建議）

在圖片下方加上 /// caption 區塊：

原始程式

![Zensical](images/landmark-solid.svg){ width="120" }
/// caption
Zensical 的標誌
///

輸出結果

延遲載入（Lazy-loading）

加上 loading=lazy，讓瀏覽器等圖片快出現在畫面時才載入，適合很大的圖片：

![圖片說明](images/large.png){ loading=lazy }

淺色與深色模式使用不同圖片

如果網站有深色模式切換，可以在圖片網址後面加上 #only-light 或 #only-dark，讓兩種模式顯示不同的圖：

![圖片說明](images/logo-light.png#only-light)
![圖片說明](images/logo-dark.png#only-dark)

使用自訂色彩配置時

內建的 default 與 slate 已經處理好這兩個片段。如果你用的是自訂色彩配置，還要在 CSS 補上隱藏規則（把 custom-light 與 custom-dark 換成你的配置名稱）：

[data-md-color-scheme="custom-light"] img[src$="#only-dark"],
[data-md-color-scheme="custom-light"] img[src$="#gh-dark-mode-only"] {
  display: none; /* 淺色模式隱藏深色圖片 */
}

[data-md-color-scheme="custom-dark"] img[src$="#only-light"],
[data-md-color-scheme="custom-dark"] img[src$="#gh-light-mode-only"] {
  display: none; /* 深色模式隱藏淺色圖片 */
}

Zensical 已內建 GLightbox 的原生實作（自 0.0.35 起）。啟用後，點擊圖片會以全螢幕覆蓋層開啟，並提供導覽與縮放功能：

[project.plugins.glightbox]

Note

GLightbox 的設定沿用 mkdocs-glightbox 外掛。官方標示 touchNavigation、loop、effect、slide_effect、zoomable、draggable、background、shadow 這幾個選項目前會被忽略。

總結

功能	語法
靠左／靠右	`![說明](圖片){ align=left }`
標題	`/// caption` … `///`，或 `<figure>`
延遲載入	`{ loading=lazy }`
依模式換圖	網址加 `#only-light`／`#only-dark`
燈箱	`[project.plugins.glightbox]`