Markdown 圖標完整教程 - 如何在 Markdown 中添加圖標（Font Awesome、Emoji、SVG）
Markdown 圖標是什麼？
Markdown 本身沒有內置的圖標（icon）語法——標準 CommonMark 規範裡找不到一個專門用來插入圖標的標記。但這不意味著在 Markdown 裡沒法用圖標。實際上有幾種常見的方法，只是每種都有各自的適用範圍和限制。
簡單來說，Markdown 圖標就是通過 HTML 標籤、圖片引用、Emoji 或者 Markdown 擴展插件等方式，在文檔中插入的小型視覺元素。它們常用來做導航標記、狀態指示、分類標籤，或者單純讓文檔更好看。
五種添加 Markdown 圖標的方法
根據你的使用場景，主要有這幾種方式：
| 方法 | 兼容性 | 複雜度 | 適合場景 |
|---|---|---|---|
| Emoji 表情 | 幾乎所有平台 | 低 | 快速點綴、狀態標記 |
| Unicode 符號 | 幾乎所有平台 | 低 | 箭頭、數學符號、特殊字符 |
| Font Awesome（HTML 標籤） | 需要加載 CSS 的平台 | 中 | 自有網站、部落格 |
| SVG 圖片引用 | 支援 img 標籤的平台 | 中 | GitHub README、跨平台文檔 |
| Markdown 擴展插件 | 特定工具鏈 | 高 | Hugo/MkDocs/Jekyll 等靜態站點 |
下面逐個展開。
用 Emoji 添加圖標
這是最簡單也最通用的方法。幾乎所有 Markdown 渲染器都支援 Emoji，包括 GitHub、GitLab、VS Code 預覽、Typora。
直接在文本中插入 Emoji 字符：
構建狀態：✅ 通過 | ❌ 失敗 | ⏳ 進行中
功能列表：
- 🔍 搜索功能
- 📊 數據分析
- 🔔 通知推送
- 🛡️ 安全防護GitHub、GitLab 還支援用冒號包裹的 Emoji 短代碼：
:tada: 發佈成功！
:rocket: 版本更新
:warning: 注意事項說實話，如果你只是想在文檔裡加點視覺元素，Emoji 是首選——不需要額外配置，複製粘貼就能用。
不過 Emoji 也有局限：樣式取決於用戶的操作系統和字體，不同設備上顯示效果可能不一樣。比如 Windows 和 macOS 上同一個 Emoji 看起來差別就挺大的。如果你需要精確控制圖標的大小和顏色，Emoji 就不太合適了。
用 Unicode 符號作為圖標
Unicode 裡藏著大量可以直接當圖標用的符號字符。它們跟 Emoji 一樣不需要額外依賴，而且在所有平台上的渲染基本一致（因為走的是字體渲染）。
一些常用的 Unicode 圖標符號：
**箭頭類：**
→ ← ↑ ↓ ⇒ ⇐ ⇑ ⇓ ➜ ➤ ▶ ◀
**形狀類：**
● ○ ■ □ ▲ △ ◆ ◇ ★ ☆ ✓ ✗
**數學/邏輯：**
≈ ≠ ≤ ≥ ± × ÷ ∞ √ ∑ ∏
**其他常用：**
☎ ✉ ⌛ ⚡ ♻ ⚠ ☘ ✈ ☕在 Markdown 裡直接粘貼這些字符就行：
### ✅ 已完成功能
- 用戶登錄 → 密碼驗證 ⇒ Token 生成
- 數據導出：CSV √ | JSON √ | XML ✗
### ⚠️ 注意事項
- CPU 使用率 ≥ 80% 時觸發告警
- 請求超時時間 ≈ 30s我的經驗是，Unicode 符號特別適合用在表格裡做狀態標記或者技術文檔中表示邏輯關係。它比 Emoji 更"正經"，不會因為渲染差異太離譜。
用 Font Awesome 圖標
Font Awesome 是最流行的圖標庫之一，提供了數千個矢量圖標。在 Markdown 中使用 Font Awesome 主要有兩種方式。
方式一：HTML 標籤（需要加載 CSS）
如果你的 Markdown 渲染在網頁上（比如自己的部落格或文檔站），可以在頁面模板的 <head> 中加載 Font Awesome CSS：
<link rel="stylesheet"
href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">然後在 Markdown 文件裡直接寫 HTML：
項目功能列表：
- <i class="fa-solid fa-user"></i> 用戶管理
- <i class="fa-solid fa-gear"></i> 系統設置
- <i class="fa-solid fa-chart-line"></i> 數據分析
- <i class="fa-solid fa-shield-halved"></i> 安全中心
按鈕樣式： <i class="fa-solid fa-download"></i> 下載 |
<i class="fa-solid fa-trash"></i> 刪除Font Awesome 還支援控制圖標大小和樣式：
<i class="fa-solid fa-house"></i> 默認大小
<i class="fa-solid fa-house fa-lg"></i> 大號
<i class="fa-solid fa-house fa-2x"></i> 兩倍大
<i class="fa-solid fa-house fa-3x"></i> 三倍大
<i class="fa-solid fa-spinner fa-spin"></i> 旋轉動畫這個方法的關鍵前提是頁面上必須加載了 Font Awesome 的 CSS 文件。如果是自己的網站，這很好辦。但如果是 GitHub README，就行不通了——GitHub 出於安全考慮會剝離自定義 CSS 和 JavaScript，<i class="fa-solid fa-user"> 這種寫法在 GitHub 上不會渲染出圖標。
我之前有一次給項目寫 README，興沖沖地用了一堆 Font Awesome 圖標，推上去一看全是空白——就是踩了這個坑。後來才搞清楚 GitHub 的 HTML 白名單策略只允許少量標籤（<img>、<a>、<br> 等），<i> 標籤會被保留但不會應用自定義 class 樣式。
方式二：Markdown 擴展插件
如果你用 MkDocs、Hugo、Jekyll 等靜態站點生成器，可以通過插件用短代碼（shortcode）來插入圖標。
MkDocs + fontawesome-markdown：
先安裝擴展：
pip install fontawesome-markdown在 mkdocs.yml 中啟用：
markdown_extensions:
- fontawesome_markdown然後在 Markdown 中使用：
我 :fa-coffee: 你
導航 :fa-home: 首頁 | :fa-cog: 設置Hugo 短代碼：
Hugo 有內置的圖標短代碼語法，配合圖標庫使用：
{{</* icon "github" */>}}
{{</* icon "heart" */>}}不過要注意，fontawesome-markdown 這個 Python 包最後更新在 2018 年，只支援到 Font Awesome v5.2。如果你需要 v6 的圖標，可以考慮其他方案或者自己寫個簡單的擴展。
用 SVG 圖片添加圖標
這個方法在 GitHub README 中特別實用。因為 GitHub 雖然不支援 Font Awesome CSS，但支援 <img> 標籤——我們可以直接引用 Font Awesome 的 SVG 文件。
引用遠程 SVG
Font Awesome 的 SVG 文件託管在 GitHub 倉庫中，可以直接用 URL 引用：
<img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/solid/crown.svg" width="20" height="20"> 付費功能
<img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/solid/rocket.svg" width="20" height="20"> 快速開始
<img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/solid/star.svg" width="20" height="20"> 推薦功能通過調整 width 和 height 屬性控制大小。顏色呢？SVG 文件默認是黑色的。如果需要改顏色，可以用 CSS 的 filter 屬性（前提是你的平台支援），或者下載 SVG 文件後修改裡面的 fill 顏色值。
用 shields.io 徽章
shields.io 提供了一種更靈活的「圖標+文字」方案，在開源項目 README 中特別常見：
這嚴格來說是「徽章」不是「圖標」，但在實際使用中經常起到圖標的作用——快速傳達項目狀態信息。shields.io 支援自定義顏色、文字、logo，靈活度很高。
各平台 Markdown 圖標兼容性對比
不同平台對圖標的支援差異很大。我整理了一個對比表，幫你快速判斷用哪種方法。
| 平台 | Emoji | Unicode 符號 | Font Awesome (HTML) | SVG 圖片引用 | 擴展插件 |
|---|---|---|---|---|---|
| GitHub | ✅ | ✅ | ❌ CSS 被剝離 | ✅ | ❌ |
| GitLab | ✅ | ✅ | ✅ 支援 HTML | ✅ | 部分 |
| VS Code 預覽 | ✅ | ✅ | ✅ | ✅ | 取決於插件 |
| Typora | ✅ | ✅ | ✅ | ✅ | 部分主題 |
| MkDocs | ✅ | ✅ | ✅ | ✅ | ✅ |
| Hugo | ✅ | ✅ | ✅ | ✅ | ✅ 短代碼 |
| Jekyll | ✅ | ✅ | ✅ | ✅ | ✅ |
關鍵結論：Emoji 和 Unicode 符號是唯一在所有平台都通用的方案。 如果你的文檔需要跨平台使用，優先選這兩種。Font Awesome HTML 標籤方法只在你能控制頁面 CSS 的環境中才好用。
暗色主題下的圖標問題
這是一個容易被忽略的細節。如果你用 SVG 圖片引用方式（比如 GitHub README），默認的 SVG 是黑色的。在亮色主題下沒問題，但如果用戶開了暗色主題（GitHub Dark），黑色圖標在深色背景上基本看不見。
解決思路：
- 使用帶透明背景的彩色 SVG — 修改 SVG 文件中的
fill值為特定顏色 - 用 shields.io 替代 — shields.io 的徽章自帶主題適配
- Emoji 替代 — Emoji 在暗色/亮色主題下都能正常顯示
<!-- 暗色主題可能看不清 -->
<img src="https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/solid/star.svg" width="16">
<!-- 更好的方案：用 Emoji 或 shields.io -->
⭐ Star us on GitHub
不同場景的圖標方案推薦
根據你實際的寫作場景，我的建議是這樣的：
寫 GitHub README：用 Emoji 做簡單標記，用 shields.io 做狀態徽章，盡量避免 Font Awesome HTML 標籤（因為不渲染）。如果一定要用 Font Awesome 風格的圖標，走 SVG 圖片引用的路線。
寫技術部落格 / 文檔站：如果站點模板已經加載了 Font Awesome，直接用 <i> 標籤是最方便的。對於 Hugo/MkDocs 等有插件生態的方案，用短代碼更優雅。
跨平台發佈：如果同一份 Markdown 要在多個平台使用，Emoji 和 Unicode 符號是最安全的選擇。Font Awesome 和 SVG 方法可能需要在某些平台上調整。
內部文檔 / Wiki：GitLab Wiki、Confluence 這些平台一般都支援 HTML，Font Awesome 方案可行。但也建議先用 Emoji 試試，夠用就沒必要搞複雜了。
常見問題
GitHub README 中 Font Awesome 圖標不顯示怎麼辦？
這是最常見的問題。GitHub 出於安全考慮，不允許外部 CSS 和 JavaScript 運行，所以 <i class="fa-solid fa-user"> 標籤雖然不會被移除，但對應的圖標樣式不會加載。解決方法是用 SVG 圖片引用或者直接用 Emoji 替代。
為什麼同一個 Markdown 文件在不同平台圖標顯示不一樣？
Markdown 的圖標渲染取決於各平台的 HTML 白名單策略和 CSS 加載權限。比如 GitHub 會剝離大部分 HTML 屬性，而 GitLab 和自己的網站則寬鬆得多。這就是為什麼跨平台文檔推薦用 Emoji 的原因——它不依賴任何外部資源。
Markdown 圖標可以自定義顏色和大小嗎？
Emoji 和 Unicode 符號的顏色和大小通常跟隨文本樣式，無法單獨控制。Font Awesome 圖標可以通過 CSS 類（如 fa-lg、fa-2x）和顏色樣式來調整，但這只在支援自定義 CSS 的平台上有效。SVG 圖片可以通過 width/height 屬性調整大小。
參考來源
- Font Awesome Official Documentation — Font Awesome 圖標庫官方文檔，提供完整的圖標列表和使用方法
- GitHub Flavored Markdown Spec — GitHub 官方 Markdown 文檔，包含 HTML 白名單策略說明
- Python-Markdown Extensions — Python Markdown 擴展官方文檔
- Font Awesome Markdown Extension — fontawesome-markdown 擴展項目文檔
- shields.io — 開源徽章生成服務，廣泛用於 GitHub 項目狀態展示