MDX 寫作範例：完整展示部落格可用的所有元件與語法

這篇是給內容團隊參考的 MDX 寫作範例，完整列出目前部落格支援的所有語法、元件、檔案規範與發佈流程。撰寫新文章時可以直接複製本檔做為起始模板，再依需要刪改各區段。

本檔同時是 QA 樣本：所有區段在 dev 預覽時若有任一處呈現異常，就代表渲染流程出問題，應優先修復後再寫新文章。

一、Frontmatter 欄位

每篇 MDX 在最頂端的 --- 區塊必須包含以下欄位。所有欄位由 src/content/config.ts 的 zod schema 嚴格驗證，缺欄或格式錯誤會在 pnpm dev 與 pnpm build 階段就拋錯：

欄位	必填	型別	說明
`title`	✅	string	主標題（純文字，不要用 markdown）
`subtitle`	⬜	string	副標題；UI 會以「title：subtitle」呈現於 og:title 與卡片
`description`	✅	string	SEO meta description 與卡片摘要，建議 80~140 字
`publishDate`	✅	date	發文日期，格式 `YYYY-MM-DD`（會被 zod 轉成 Date）
`updatedDate`	⬜	date	更新日期，格式同上；用於 schema.org `dateModified`
`author`	⬜	string	作者姓名字串，預設「希望債務救星團隊」
`tags`	⬜	string[]	tag 字串陣列，預設 `[]`；列表頁會以此做相關文章配對
`coverImage`	⬜	image	封面圖；置於 `src/assets/blog/` 並用相對路徑引用
`coverImageAlt`	⚠️	string	`coverImage` 存在時必填
`draft`	⬜	boolean	`true` 時 production build 自動排除；dev 仍可預覽

1.1 完整 Frontmatter 範例

最簡可發佈版本（無封面、無副標）：

---
title: "債務協商懶人包"
description: "一次看懂前置協商流程、所需文件、常見問題與費用估算。"
publishDate: 2026-05-15
tags: ["債務協商", "懶人包"]
---

完整欄位版本（含封面、副標、更新日期）：

---
title: "債務協商完整指南"
subtitle: "從評估到簽約一次看懂"
description: "前置協商從盤點負債、計算 DBR、與銀行公會送件、到簽約執行的完整流程，附常見拒絕原因與補件清單。"
publishDate: 2026-05-15
updatedDate: 2026-05-20
author: "王律師"
tags:
  - "債務協商"
  - "前置協商"
  - "完整指南"
coverImage: "../../assets/blog/debt-negotiation/cover.webp"
coverImageAlt: "桌面上散落多份信用卡帳單，旁邊放著計算機與筆記本"
draft: false
---

沒有封面也沒關係。系統會自動以 from-primary → to-accent 漸層 + title / subtitle 視覺繪製預設大圖（同時套用到列表卡片）。

二、文字段落與強調語法

一般段落直接寫即可。以下是可用的強調語法總覽：

語法	寫法	呈現
粗體	`重點`	重點
斜體	`補述`	補述
粗斜體	`*最高強調*`	最高強調
刪除線	`~~已廢止~~`	~~已廢止~~
行內程式碼	`import.meta.env`	`import.meta.env`

可以混用，例如：「DBR 必須低於 22 倍」是 銀行公會 的審核基準。

2.1 段落與斷行

可以連續多個段落，每段之間留一個空行即可。中文不需手動換行，瀏覽器會依容器寬度自然斷行。

如果真的需要強制換行（例如詩詞、地址、條列項目內），可以在行尾加兩個空格再 Enter，
這樣會產生 <br />，但在內文段落中不建議這麼做。

2.2 連結

外部連結會由 SmartLink 元件自動加上 target="_blank" 與 rel="noopener noreferrer"：金管會官方網站。

站內相對連結則保持單頁切換（同視窗）：聯絡我們、服務介紹、FAQ。

判斷規則：以 http:// 或 https:// 開頭 → 外部；其餘 → 站內。

2.3 跳脫字元

要顯示 markdown 保留字本身，用反斜線跳脫：\* 顯示星號、\_ 顯示底線、\# 顯示井號。

三、多層級標題

部落格支援 H2 ~ H4 三層，由 prose 樣式自動套用視覺層級。H1 由文章標題自動產生，內文不要再使用 #，否則會破壞 SEO heading hierarchy。

這是 H3 標題（含左側裝飾線）

H3 用於 H2 的子節，左側會自動顯示 3px 主色裝飾線，方便視覺辨識章節層級。

這是 H4 標題

H4 用於 H3 的子節，裝飾線略細，適合更深一階的細節說明。建議文章層級不要超過 H4，避免結構過深、TOC 縮排過嚴重。

3.1 標題會被左側目錄自動收錄

側欄 TOC 會自動列出所有 H2 ~ H4，並以縮排呈現層級。目前正在閱讀的段落會自動高亮：當文章捲動到某個 heading 通過視窗頂部觸發線（位於 sticky header 下方約 120px）時，TOC 對應條目會切換為 primary 色與粗體，並在條目左側畫出裝飾線。點擊 TOC 連結則平滑跳轉到對應段落。

3.2 標題建議寫法

用編號開頭（如「3.1 xxx」）方便讀者引用
標題本身不要用粗體 / 斜體 / 程式碼樣式，會干擾 prose 既有設計
同層級標題之間至少留一個段落，不要連續兩個 heading

四、清單

4.1 無序清單

第一點：這是一條一般項目
第二點：可以包含粗體、斜體、程式碼、與連結
第三點：項目可以多行，第二行只要保持縮排即可延續說明：縮排兩格表示這是同一個項目的延伸內容
第四點：可以巢狀
- 巢狀子項目 1
- 巢狀子項目 2
  - 第三層（不建議再深）

4.2 有序清單

第一步：盤點目前所有負債（含本金、利率、月付金）
第二步：計算 DBR（負債總額 ÷ 月收入）
第三步：諮詢專業顧問，評估適用方案
第四步：準備文件並送件
第五步：等待銀行回覆與簽約

有序清單的數字不需要連續，markdown 會自動編號：

第一步
第二步（寫 1 也會渲染為 2）
第三步

4.3 任務清單（GFM checklist）

已完成：建立 content/blog/ 資料夾
已完成：撰寫 frontmatter
進行中：完成內文
尚未開始：reviewer 審稿
尚未開始：production build 驗證

4.4 定義式清單（用粗體模擬）

由於 prose 預設不支援 <dl>，建議用以下寫法：

DBR：負債收入比，月應還款金額 ÷ 月收入
前置協商：依銀行公會機制，由單一窗口（最大債權銀行）統籌與所有銀行協商
更生程序：由法院介入，以裁定方式重整債務還款計畫

五、圖片

5.1 圖片放置位置

用途	位置	引用方式
內文展示圖	`public/images/blog/<slug>/`	`![alt](/images/blog/<slug>/foo.webp)`
封面（會被 Astro 處理）	`src/assets/blog/<slug>/`	frontmatter `coverImage: "../../assets/..."`
共用插畫	`public/images/shared/`	`![alt](/images/shared/foo.svg)`

5.2 內文圖片寫法

所有圖片必須提供 alt 文字，否則 BlogImage 元件會在 build 階段拋錯：

連續多張圖也沒問題：

5.3 alt 文字撰寫原則

✅ 描述「圖中內容」，例如「桌面上散落多份信用卡帳單」
✅ 描述「圖中傳達的資訊」，例如「DBR 計算公式：負債 ÷ 收入 × 100%」
❌ 不要寫「這是一張圖」「圖片」「示意圖」這類無資訊內容
❌ 不要重複文章周邊段落已有的描述，避免螢幕閱讀器重複朗讀

5.4 圖片載入優化

BlogImage 已自動套用：

loading="lazy"：滾動到附近才載入
decoding="async"：解碼不阻塞主執行緒
圓角 + 輕陰影樣式
支援 caption prop（透過 MDX shortcode 寫法），會以 <figcaption> 渲染

六、引用區塊

6.1 一般引用

一般引用區塊：用於補充提醒或重點摘要。可以連續多行；段落之間照樣留空行。

6.2 含格式的引用

重要： 引用內也支援粗體、斜體、程式碼 與連結。

適合放法規依據、官方公告摘錄、或特別需要強調的提示。

6.3 多段引用

第一段：依據《消費者債務清理條例》第 151 條，債務人於前置協商不成立後始得聲請更生或清算。

第二段：協商過程中銀行不得催收、不得向第三人請求，違者將由金管會依《銀行法》裁罰。

6.4 巢狀引用

外層引用：來自 A 報告。

內層引用：A 報告中再引用 B 公告的段落。

內層第二段。

外層延續。

七、表格（GFM）

7.1 基本表格

服務類型	適用情境	主要效益
前置協商	卡費 / 信貸還款壓力大	降低利率、延長期數
債務整合	多筆負債分散	統一單筆、簡化管理
司法更生	財務狀況極度緊繃	法院介入重整還款
清算程序	已無償還能力	法定免責程序

7.2 含對齊與格式的表格

對齊符號寫在分隔列：:--- 左對齊、:---: 置中、---: 右對齊。

方案	DBR 適用範圍	月省金額	備註
前置協商	22 倍以上	5,000~15,000	留紀錄 6 個月
債務整合	8~22 倍	3,000~10,000	視信用條件
司法更生	收入無法清償	視裁定	須由律師代理
清算程序	已無資產	—	法定免責

表格 cell 內可使用粗體、code、連結，但不要放圖片或多行段落，避免破壞排版。

八、程式碼區塊

行內 code 適合短語，例如 import.meta.env.PUBLIC_FRONT_EDGE_URL。

多行程式碼用三個反引號包圍，可以指定語言（目前未啟用 syntax highlight，純樣式呈現；未來啟用後語言標記就會生效）。

8.1 TypeScript

import { getCollection, type CollectionEntry } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog', ({ data }) => !data.draft);
  return posts.map((post) => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

type Props = { post: CollectionEntry<'blog'> };

8.2 TSX

import { useState } from 'react';
import { Button } from '@xingrong-frontend/ui';

export function CounterDemo() {
  const [count, setCount] = useState(0);
  return (
    <Button onClick={() => setCount(count + 1)}>
      已點擊 {count} 次
    </Button>
  );
}

8.3 JSON

{
  "title": "MDX 寫作範例",
  "tags": ["撰寫指南", "MDX 範例"],
  "draft": false
}

8.4 Bash

# 啟動 dev server
pnpm dev

# 預覽某篇文章
open http://localhost:4321/blog/example-mdx-showcase

# 通過 production build 驗證
pnpm build

8.5 SQL（CRM 後台舉例）

SELECT id, name, phone, debt_amount, monthly_income
FROM "simple-crm".leads
WHERE created_at >= NOW() - INTERVAL '7 days'
ORDER BY created_at DESC;

九、嵌入元件

部落格 MDX 可直接 import React 元件並使用 JSX 語法。本檔案頂端已 import：

import { EmbedLink, YouTubeEmbed } from '@xingrong-frontend/blog-kit/react';

9.1 EmbedLink — 外部連結卡片

<EmbedLink> 用於精選外部連結，比一般文字連結更醒目。建議用於官方資料、研究報告、深度文章。

最小參數版本：

中華民國銀行公會

中華民國銀行公會 - 消費金融案件無擔保債務協商機制

銀行公會關於消費金融案件無擔保債務協商機制（含前置協商）的官方公告與說明。

完整參數版本（含縮圖）：

金管會

金融監督管理委員會

主管全國金融服務業之金融市場監理，包括銀行業、證券期貨業、保險業之監理。

可用 props：

prop	必填	說明
`url`	✅	目標連結網址
`title`	✅	卡片主標題
`description`	⬜	描述文字（最多兩行）
`source`	⬜	來源網站名稱；未填則自動取 hostname
`image`	⬜	縮圖網址
`imageAlt`	⬜	縮圖替代文字；未填則用 `title`

9.2 YouTubeEmbed — YouTube 影片嵌入

<YouTubeEmbed> 嵌入 YouTube 影片，自動採 16:9 比例，使用 youtube-nocookie.com 提升隱私並符合 GDPR：

可用 props：

prop	必填	說明
`id`	✅	YouTube 影片 ID（網址 `?v=` 後 11 字元）
`title`	✅	無障礙標題，請寫清楚影片內容；會渲染為 `<iframe title>`

重要：id 不是完整網址。例如 https://youtu.be/dQw4w9WgXcQ 中的 dQw4w9WgXcQ 才是 ID。

不要使用 https://www.youtube.com/watch?v=... 整段網址，會渲染失敗。

十、實用 MDX 撰寫小技巧

10.1 換行的處理

段落內不要手動斷行（中文會自然斷行）
想強制換行：行尾加兩個空格 + Enter
段落之間：留一個空行
想刻意留兩個段落距離：在中間加 <br /> 或新增空段落

10.2 草稿不發佈

frontmatter 加 draft: true，production build 會自動排除這篇。dev 模式仍可預覽，方便撰寫中審稿與分享預覽連結。

---
title: "撰寫中..."
publishDate: 2026-05-15
description: "..."
draft: true
---

10.3 沒有封面圖也沒關係

如果還沒準備好封面，可以整段省略 coverImage 與 coverImageAlt：

---
title: "暫無封面的文章"
description: "..."
publishDate: 2026-04-29
tags: ["新知"]
---

系統會自動以 from-primary → to-accent 漸層 + title / subtitle 視覺繪製預設大圖（同時套用到列表卡片）。

10.4 SEO description 撰寫建議

description 同時用於：

<meta name="description">（搜尋引擎摘要）
Open Graph og:description（社群分享卡）
部落格列表卡片摘要

撰寫原則：

80~140 字最佳；超過 160 字 Google 會截斷
把核心關鍵字放前 60 字
直接回答讀者搜尋意圖（不要寫成標題的延伸）
避免和 title 重複

10.5 標題連結（heading anchor）

每個 H2 ~ H4 會自動產生 anchor，slug 由 github-slugger 演算法決定（中文會直接保留）。例如：

「## 第一節概述」 → slug 第一節-概述 → URL #第一節-概述
「### 4.1 無序清單」 → slug 41-無序清單

要從外部分享文章特定段落時，把 slug 接在文章 URL 後即可：

https://hope-debt-savior.com/blog/example-mdx-showcase#第一節-概述

10.6 文章內 cross-reference

用站內連結 + anchor：

跳到本文 § 七、表格
跳到另一篇文章特定段落：債務協商指南 § 文件準備

十一、發佈流程

新增文章流程：

建檔：在 src/content/blog/ 新增 <slug>.mdx
- slug 用小寫英文 + 連字號，例如 debt-negotiation-2026
- 不要用中文 slug，避免 URL encoding 顯示混亂
準備圖片：放到 public/images/blog/<slug>/ 或共用 public/images/shared/
- 封面圖另放 src/assets/blog/<slug>/cover.webp
- 圖片優先使用 WebP / AVIF；SVG 適用於圖示與示意圖
填寫 frontmatter：對照 § 1 表格逐欄確認
撰寫內文：依本檔範例
本地預覽：
- 在 monorepo 根跑 pnpm dev 並選 hope-debt-savior → 開啟 http://localhost:4321/blog/<slug>
- 檢查 TOC、圖片、連結、嵌入元件全部正常
本地驗證：pnpm typecheck 與 pnpm build，確認 production 也通過
commit：依 Laziimit 格式，例如 v0.x.y 新增 <slug> 文章
送審：reviewer 確認後 push；CI 自動部署

結語

以上即為部落格目前支援的所有 MDX 寫法與發佈流程。

需要新功能（例如程式碼語法高亮、社群分享按鈕、RSS feed、評論系統、目錄展開折疊）請開 issue 與工程團隊討論，並附上預期 UX 與優先級。