單元 6 · GitHub Flavored Markdown

GitHub 的 Markdown 擴充 — GFM

← 單元教學

GitHub Flavored Markdown（GFM） 是 GitHub 在標準 Markdown 上擴充的版本， 也是你寫 README、Issue、Pull Request 時實際使用的語法。它的規格以 CommonMark 為基礎， 並加上下面這些實用擴充。

任務清單 · Task Lists

在清單項目後方寫 [ ]（未完成）或 [x]（已完成），GitHub 會渲染成可勾選的 checkbox。

原始碼 · SOURCE
- [x] 寫完 README
- [x] 推上 GitHub
- [ ] 等待 review
渲染結果 · RENDERED
  • ☑ 寫完 README
  • ☑ 推上 GitHub
  • ☐ 等待 review
實戰用法：Issue 內建「Task list」會顯示進度條；在 PR 描述列清單，還有 「將 Issue 標記為完成」的自動關聯功能。

刪除線 · Strikethrough

用兩個波浪號 ~~ 包起來。

原始碼 · SOURCE
~~這個方案已過時~~，請改用新版。
渲染結果 · RENDERED

這個方案已過時，請改用新版。

自動連結 · Autolinks

在 GitHub 上，網址會自動變成連結，不用尖括號。更棒的是「跨資源自動連結」：

自動連結規則 · AUTOLINKS
https://github.com            # 網址自動成連結
@shumingyang-opencode        # @mention 通知某人
#42                          # 指到本 repo 的 Issue/PR 42
shumingyang-opencode/repo#1  # 指到其他 repo 的 issue
`gh-42` 等內嵌 code 也會連結    # issue/PR 自動連結
注意：#42 只在你 repo 的上下文（README、Issue、PR）才有意義， 一般 markdown 檔案裡它只是普通文字。

註腳 · Footnotes

用 [^1] 標記、文末 [^1]: 內容 定義，適合補參考資料而不打斷正文。

原始碼 · SOURCE
GFM 規格見[官方文件][^1]。

[^1]: https://github.github.com/gfm/
渲染結果 · RENDERED

GFM 規格見官方文件1。

1 https://github.github.com/gfm/

Emoji

用 :名稱: 語法插入表情符號（自動轉成 emoji）。

原始碼 · SOURCE
:rocket: 發布成功！ :tada:
渲染結果 · RENDERED

🚀 發布成功！ 🎉

完整清單可查 Emoji Cheat Sheet。

其他 GFM 特色

看完這頁你應該能說出：
  • 任務清單的寫法與它在 Issue/PR 的實戰用途。
  • 刪除線 ~~ 與 emoji :名稱:。
  • 自動連結的三種形式：網址、@mention、#issue。
  • 註腳的標記與定義兩段式寫法。
  • GFM 在 GitHub 協作裡的角色。

延伸閱讀

← 上一篇
單元 5 · 表格與進階區塊
下一篇 →
單元 7 · Markdown 生態系