{
  "url": "https://unifast.dev/zh-TW/docs/introduction/key-concepts/",
  "locale": "zh-TW",
  "title": "核心概念",
  "description": "了解 unifast 的多階段編譯管線、內建處理階段，以及 MdAst 與 HAst 轉換的運作方式。",
  "section": "introduction",
  "body": "unifast 透過多階段管線來編譯 Markdown。理解這些階段有助於您設定編譯器並挑選合適的外掛。\n\n### 編譯管線\n\n```\nInput text\n  → Parse (Markdown or MDX)\n  → IR0: MdAst (Markdown structure)\n  → Normalize + Built-in MdAst passes\n  → Lower to IR1: HAst (HTML structure)\n  → HAst passes (sanitize, highlight, etc.)\n  → Emit (HTML string)\n```\n\n每一個階段都會透過中介表示法（IR）對文件進行轉換。\n\n### 中介表示法\n\n| IR | 名稱 | 用途 |\n|----|------|---------|\n| **IR0** | MdAst | Markdown 結構──標題、段落、清單、程式碼區塊 |\n| **IR1** | HAst | HTML 結構──元素、屬性、文字節點 |\n| **IR2** | JsAst | 僅限 MDX──ESM import 與 JSX 運算式 |\n\n解析器會產生 **MdAst**，接著下降為 **HAst** 以輸出 HTML。MDX 輸入另外還會產生 **JsAst** 節點，用來輸出 JavaScript。\n\n### 處理階段（Passes）\n\n處理階段是在特定階段套用於 AST 的轉換。unifast 針對常見任務提供以下內建處理階段：\n\n**MdAst 處理階段**（下降為 HTML 之前）：\n\n- **Normalize** - 為後續處理階段建立一致的結構\n- **Slug** - 從文字內容產生標題 ID\n- **TOC** - 從標題擷取目錄\n- **Definition Resolution** - 解析連結與圖片的參照定義\n\n**HAst 處理階段**（下降為 HTML 之後）：\n\n- **Sanitize** - 移除不允許的 HTML 元素與屬性\n- **Highlight** - 為程式碼區塊套用語法高亮\n- **Cleanup** - 移除不必要的節點與空白\n\n處理階段會依據階段排序，您無需擔心執行順序。\n\n### 外掛\n\n外掛是用來設定內建處理階段的 TypeScript 套件。它們並不會在編譯過程中執行任意 JavaScript，而是設定選項以控制 Rust 核心處理文件的方式。\n\n```ts\nimport { compile, gfm, sanitize } from \"@unifast/node\";\n\nconst result = compile(source, {\n  plugins: [gfm(), sanitize()],\n});\n```\n\n每個外掛會傳回一個設定物件，該物件會在 Rust 核心執行之前合併至 compile 選項。如此一來，熱路徑便能完全留在原生程式碼中。\n\n### 輸出格式\n\n編譯器透過 `outputKind` 選項支援多種輸出格式：\n\n| 格式 | 說明 |\n|--------|-------------|\n| `\"html\"` | HTML 字串（預設） |\n| `\"hast\"` | HAst JSON──用於自訂渲染的 HTML AST |\n| `\"mdast\"` | MdAst JSON──用於分析的 Markdown AST |\n| `\"mdx-js\"` | JavaScript 模組字串（僅限 MDX） |\n\n### 診斷訊息\n\n編譯器會透過結果中的 `diagnostics` 陣列回報問題。每筆診斷訊息都包含嚴重度層級、訊息內容，以及選用的來源範圍，可用於精確定位錯誤位置。\n\n```ts\nconst result = compile(source);\n\nfor (const d of result.diagnostics) {\n  console.warn(`[${d.level}] ${d.message}`);\n}\n```",
  "alternates": [
    {
      "locale": "en",
      "url": "https://unifast.dev/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/docs/introduction/key-concepts.json"
    },
    {
      "locale": "ja",
      "url": "https://unifast.dev/ja/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/ja/docs/introduction/key-concepts.json"
    },
    {
      "locale": "zh-CN",
      "url": "https://unifast.dev/zh-CN/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/zh-CN/docs/introduction/key-concepts.json"
    },
    {
      "locale": "zh-TW",
      "url": "https://unifast.dev/zh-TW/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/zh-TW/docs/introduction/key-concepts.json"
    },
    {
      "locale": "ko",
      "url": "https://unifast.dev/ko/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/ko/docs/introduction/key-concepts.json"
    },
    {
      "locale": "fr",
      "url": "https://unifast.dev/fr/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/fr/docs/introduction/key-concepts.json"
    },
    {
      "locale": "it",
      "url": "https://unifast.dev/it/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/it/docs/introduction/key-concepts.json"
    },
    {
      "locale": "es",
      "url": "https://unifast.dev/es/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/es/docs/introduction/key-concepts.json"
    },
    {
      "locale": "pt-BR",
      "url": "https://unifast.dev/pt-BR/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/pt-BR/docs/introduction/key-concepts.json"
    },
    {
      "locale": "de",
      "url": "https://unifast.dev/de/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/de/docs/introduction/key-concepts.json"
    },
    {
      "locale": "ru",
      "url": "https://unifast.dev/ru/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/ru/docs/introduction/key-concepts.json"
    },
    {
      "locale": "hi",
      "url": "https://unifast.dev/hi/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/hi/docs/introduction/key-concepts.json"
    },
    {
      "locale": "id",
      "url": "https://unifast.dev/id/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/id/docs/introduction/key-concepts.json"
    },
    {
      "locale": "tr",
      "url": "https://unifast.dev/tr/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/tr/docs/introduction/key-concepts.json"
    },
    {
      "locale": "vi",
      "url": "https://unifast.dev/vi/docs/introduction/key-concepts/",
      "api": "https://unifast.dev//api/vi/docs/introduction/key-concepts.json"
    }
  ]
}