跳轉至

Markdown 語法與元件示範

Material for MkDocs 提供了豐富的排版元件與擴充功能。撰寫筆記時可隨時參考本頁面提供的語法範例。

1. 提示區塊 (Admonitions)

使用 !!! <類型> "標題" 建立不同風格的提示框：

筆記 (Note)

這是一個一般的提示方塊，用來補充一般背景資訊。

小技巧 (Tip)

使用快捷鍵 Ctrl+Alt+T 或 Cmd+Option+T 可以快速在 IDE 中調出終端機。

警告 (Warning)

在覆蓋設定檔前，請務必先將原有檔案進行備份。

危險 (Danger)

執行 rm -rf 指令時請特別小心當前目錄路徑！

可摺疊區塊 (Collapsible)

將 !!! 改為 ??? 或 ???+（預設展開），即可建立可收合的內容面板。

展開後可以看到更多詳細的補充說明。

2. 程式碼區塊 (Code Blocks)

分頁顯示多語言 / 指令

1
2
3
4
5
def greet(name: str) -> str:
    """返回個人化問候語"""
    return f"Hello, {name}!"

print(greet("Windcold"))

1
2
3
4
5
6
7
8
interface User {
  id: string;
  name: string;
}

const greet = (user: User): string => {
  return `Hello, ${user.name}!`;
};

curl -fsSL https://get.example.com | sh

程式碼行號標記與註解 (Annotations)

site_name: Windcold 知識庫
theme:
  name: material # (1)!
  language: zh-Hant
  1. 👨‍💻 採用官方極致美觀的 Material 主題。

3. 圖表視覺化 (Mermaid)

直接在 Markdown 中以 Mermaid 繪製流程圖、序列圖或狀態圖：

sequenceDiagram
    autonumber
    actor User as 使用者
    participant Git as 本地 Git
    participant GH as GitHub 倉庫
    participant GHA as GitHub Actions
    participant Pages as GitHub Pages

    User->>Git: 撰寫 Markdown 並 commit
    User->>GH: git push origin main
    GH->>GHA: 觸發 CI/CD 工作流
    GHA->>GHA: 執行 mkdocs build 產生靜態檔案
    GHA->>Pages: 部署至 GitHub Pages CDN
    Pages-->>User: 線上即刻閱讀最新知識庫
Hold "Alt" / "Option" to enable pan & zoom

4. 內容分欄卡片 (Grid Cards)

  • 結構化筆記

    將筆記按主題、架構或年份妥善分門別類。

  • 全文極速檢索

    即使累積上百篇文章，本地與線上搜尋引擎皆能秒級定位。

5. 待辦事項清單 (Checklist)

  • 安裝 Material for MkDocs
  • 設定自動化 GitHub Actions 流程
  • 安裝 11 項實用 MkDocs 外掛
  • 撰寫第一篇核心架構筆記

你可以使用 高亮標記、刪除線，或是 Ctrl+K 鍵盤樣式。

6. 自動化外掛示範

A. 文章別名引用 (alias) 與內部連結

在文章 front-matter 定義別名後，可以在任何頁面使用雙中括弧快速引用：

B. 文章標籤 (Tags)

在文章 front-matter 中加入 tags: 屬性，標籤會自動渲染於標題上方，並彙整於 標籤索引頁：

---
tags:
  - Markdown
  - 語法元件
---

C. AI 摘要外掛 (ai-summary)

在需要 AI 自動摘要的文章頂部加入：

---
include:
  - ai-summary
---

建置時將自動呼叫 LLM 產生精簡前言摘要。

D. LLMs.txt 規範支援 (llmstxt)

網站建置時會自動於根目錄產出標準規範的 /llms.txt 與 /llms-full.txt，供 AI 智慧助理檢索知識庫全站內容。

E. Git Committers 與版本修訂日期

頁面底端將自動載入本頁面的貢獻者頭像清單與最後修訂時間（如「3 小時前」、「2 天前」）。