插入圖片（Figure）並加上註解（Caption） - puyotw/core-site GitHub Wiki

正如很多學術文章一樣，圖片通常有特殊的格式。一般來說，圖片會置中在頁面，且圖下有註解。註解前面更會標明圖片是頁面中的第幾張，以便內文引用。

HTML 本身是支持 figure 和 figcaption 標籤的，但 Markdown 標準語法並沒有將圖片轉成 figure 的語法。雖然，驅動 Jekyll 的 Markdown 引擎 kramdown 有特殊語法支持，但說到底還是不支持數自動計算圖片編號的功能。有見及此，團隊為方便作者插入圖片和註解，特意製作了 Jekyll 的插件 Figure。本文將介紹 Figure 的使用方法。

figure 環境

Figure 插件新增了 figure 環境。基本的語法如下：

{% figure %}
  圖片、表格、模擬器等的 Markdown 或 Liquid 語法
{% endfigure %}

這將生成類似如下的 HTML：

<figure>
   圖片、表格、模擬器等的 HTML
   <figcaption><i>圖 1</i></figcaption>
</figure>

caption 區域

在 figure 環境中，可將註解內容放至 caption 區域，如下：

{% figure %}
  圖片、表格、模擬器等的 Markdown 或 Liquid 語法
{% caption %}
  註解內容的 Markdown 或 Liquid 語法
{% endfigure %}

這將生成類似如下的 HTML：

<figure>
   圖片、表格、模擬器等的 HTML
   <figcaption><i>圖 1</i>. 註解內容的 HTML</figcaption>
</figure>

其中圖 1的1是會隨圖片編號而改變。

ref 與 reft 標籤

ref 與 reft 標籤用作引用頁面上的 figure。首先要給 figure 起一個名字，然後將名字傳入 ref 或 reft中。ref 則會生成能跳到該 figure 的超連結，而 reft 也會生成一樣的東西，但只有文字，沒有超連結。

label 屬性

label 屬性是放在 figure 環境中，是該 figure 的名字。label 在同一頁面中必須唯一，否則是未定義行為。

例如：

{% figure label: my_fig %}
   ...
{% endfigure %}

則該 figure 的 HTML 為：

<figure id="my_fig"> ... </figure>

在內文任意地方（該 figure 之前、裡面、之後皆可）輸入 {% ref my_fig %}，則生成如下 HTML：

<a href="#my_fig">圖 1</a>

另外，{% reft my_fig %} 則會生成純文字的 圖 1，沒有超連結。

reffmt 屬性

這是 reference format 的簡寫，是寫在 figure 標籤的屬性，可改變圖片編號的表示方法。除了在該 figure 裡面的編號表示方式改變外，引到該 figure 的 ref 或 reft 表示方式也會改變。此屬性的可用的變數為 num。預設值是 "圖 {{ num }}"。

{% figure label: my_fig reffmt: "{{ num }} 號圖片" %}
   ...
{% endfigure %}

將促使 figure 內及 ref 和 reft 的編號表示方式變為1 號圖片。

其他屬性

txtfmt 屬性

這是 text format 的簡寫，是寫在 caption 標籤的屬性，可改變註解內容的格式。此屬性的可用變數為 captext。預設值是 ". {{ captext }}"。值得注意的是，當 figure 環境內沒有 caption 區域，則這個格式內所有內容均不顯示。例如：

{% figure %}
   ...
{% endfigure %}

這段代碼生成的註解為 圖 1，但如果寫成：

{% figure %}
   ...
{% caption %}
{% endfigure %}

則會生成註解 圖 1. 。另外，如果寫成：

{% figure %}
   ...
{% caption txtfmt: "「{{ captext }}」" %}
   註解文字
{% endfigure %}

則會生成註解 圖 1「註解文字」。

fmt 屬性

這是 format 的簡寫，是寫在 caption 標籤的屬性，可改變註解的整體格式。此屬性的可用變數為 ref 和 caption。預設值是 "*{{ ref }}*{{ caption }}"。這將是寫在 figure 之下整體格式，包含了編號及註解內容。例如：

{% figure %}
   ...
{% caption fmt: "{{ caption }} <=> {{ ref }}" %}
   註解文字
{% endfigure %}

則會生成註解內容 . 註解文字 <=> 圖 1。

⚠️ **GitHub.com Fallback** ⚠️