這篇指南把教學元件、圖片與影片的效果和寫法放在一起。先操作每一節的範例，再複製對應的 Markdown。開始與結束標籤各佔一行，素材放在本篇同層的 assets/，不必設定單篇樣式或程式。
想先看完整操作？到部落格的教學元件與媒體互動範例。也可以直接開啟這篇頁籤裡的補充說明，體驗目錄與段落連結自動展開內容。
提示與警告
{% hint style="info" %}
先閱讀這段背景說明，再繼續操作。
{% endhint %}
style 必填。將 info 改成 success、warning 或 danger，可以顯示不同的狀態：
自動編號的操作步驟
-
閱讀範例
先看這個步驟的標題與說明。步驟可以包含一般 Markdown，也能放提示區塊。
-
複製寫法
複製下方範例，換成自己的標題與內容。步驟編號由網站產生。
{% stepper %}
{% step %}
### 閱讀範例
先看這個步驟的標題與說明。
{% hint style="info" %}
這是步驟裡的補充提示。
{% figure src="assets/cool.svg" alt="放在操作步驟提示中的冷色抽象海報" %}
這張圖位於**步驟中的提示**裡，仍可點擊放大。
{% endfigure %}
{% endhint %}
{% endstep %}
{% step %}
### 複製寫法
換成自己的標題與內容。
{% endstep %}
{% endstepper %}
讓讀者選擇平台
Windows
Windows 範例內容
第一個頁籤預設顯示。點擊 macOS，看看另一份正文。
macOS
這是另一個平台的獨立內容。
{% tabs %}
{% tab title="Windows" %}
這是第一個平台的內容。
{% hint style="info" %}
頁籤內也可以放提示。
{% endhint %}
{% endtab %}
{% tab title="macOS" %}
這是另一個平台的內容。
{% endtab %}
{% endtabs %}
每個 tab 都需要非空白的 title。同頁可放多組 tabs，各組獨立切換；不支援頁籤內再放頁籤。
收合補充說明
{% expandable title="點開查看補充說明" %}
這裡放需要時再讀的資訊。
- 第一個檢查項目。
- 第二個檢查項目。
{% endexpandable %}
expandable 是本網站自訂的寫法，標題使用純文字。用 Tab 移到收合標題，再按 Enter 或空白鍵，就能開合。
一般圖片會自動提供放大入口
點擊圖片，或用 Tab 選到圖片後按 Enter。放大視窗可按 Esc 關閉；停用 JavaScript 時，同一個入口會開啟原圖。
alt 替代文字要描述畫面。它供無法看見圖片的讀者使用，不會自動顯示成圖說。句子裡的小圖保留原本排版；已有連結的圖片，也會保留作者指定的目的地。
有說明時，使用 figure
行內程式碼。{% figure src="assets/warm.svg" alt="暖色海報以陶土橘背景搭配半圓拱門與圓形" %}
這是**可見圖說**，可以補充色彩選擇。
{% endfigure %}
src、alt 必填。圖說限一段基本行內 Markdown，開始與結束標籤各自獨立成行。
用 gallery 比較圖片
先打開一張，再用左右方向鍵切換。每組圖片各自獨立，不會混入正文其他圖片。畫面較窄時，圖片會換行，保留完整內容。
{% gallery %}
{% figure src="assets/warm.svg" alt="陶土橘與奶油白的暖色海報" %}
暖色版本。
{% endfigure %}
{% endgallery %}
獨立圖片之間留空行。圖片組只能放獨立 Markdown 圖片或 figure，不能插入其他正文。
影片、封面與字幕一起放在 assets
按播放，再試試暫停與字幕選單。這段短片沒有旁白；示範字幕是另外撰寫的操作提示。
{% video src="assets/flower.mp4" poster="assets/flower-poster.png" title="花園短片" captions="assets/captions.zh-Hant.vtt" %}
影片說明放在這裡。
{% endvideo %}
src 與 title 必填；poster、captions 選填。本機影片支援 MP4、WebM，也可在 src 填合法的 HTTPS 影片網址。影片不會自動播放。字幕限本機 .vtt 檔案，語言預設沿用文章語言。
字幕檔案的開頭與時間格式如下：
WEBVTT
00:00:00.000 --> 00:00:02.000
這是播放器示範字幕。
點擊後才載入 YouTube
{% embed url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="YouTube 官方播放器範例" %}
外部影片的說明。
{% endembed %}
目前支援 YouTube 的 watch?v=...、youtu.be/...、shorts/... 與 embed/... HTTPS 網址。其他平台請使用一般 Markdown 連結。停用 JavaScript 時，入口會直接前往 YouTube。
媒體也能放進教學元件
切到「圖片」頁籤，再點開裡面的圖。頁籤裡的圖片同樣可以放大。
文字
這個頁籤先顯示文字。另一個頁籤裡有圖片，停用 JavaScript 時兩邊的內容都能閱讀。
圖片
媒體可以放進 hint、tab、step 或 expandable 的正文。程式碼區塊裡的標籤會保留原文，不會產生另一個播放器或圖片組。
撰寫時檢查這幾件事
| 檢查項目 | 正確寫法 |
|---|---|
| 標籤位置 | 每個標籤各佔一行，不放進清單或引用 |
| 屬性 | style、title 的值用成對引號包住 |
| 步驟與頁籤 | step 放在 stepper 裡，tab 放在 tabs 裡 |
| 結尾 | 每個元件都有對應的 end... 標籤 |
| 展示語法 | 放進帶有語言名稱的程式碼區塊，保留原文 |
這篇的程式碼範例只顯示寫法。文章正文只辨識受支援的元件標籤，不執行任意 HTML、版型指令或 JavaScript。
素材來源
排版圖由本站製作。花朵影片來自 MDN 的 CC0 影片素材，依其 CC0 授權使用。封面取自該影片畫面，示範字幕由本站撰寫。