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/articles/` 並用相對路徑引用
`coverImageAlt`	⚠️	string	`coverImage` 存在時必填
`draft`	⬜	boolean	`true` 時 production build 自動排除；dev 仍可預覽

1.1 完整 Frontmatter 範例

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

---
title: "2026 Q1 營運更新"
description: "本季重點：產品進度、客戶拓展與財務概況。"
publishDate: 2026-03-31
tags: ["季報", "營運"]
---

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

---
title: "柴米科技有限公司 商業計畫書"
subtitle: "柴米科技 — Business Plan v0.1"
description: "柴米科技有限公司 完整商業計畫書，涵蓋公司定位、三品牌產品線、市場機會、商業模式、團隊、里程碑、財務預測與募資需求。"
publishDate: 2026-05-24
updatedDate: 2026-05-24
author: "柴米科技有限公司"
tags:
  - "商業計畫書"
  - "公司概覽"
  - "募資"
coverImage: "../../assets/articles/business-plan/cover.webp"
coverImageAlt: "桌面上的筆電顯示營收圖表，旁邊放著筆記本與咖啡"
---

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

二、文字段落與強調語法

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

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

可以混用，例如：「ARR 必須突破 NT$1,000 萬」是 2027 Q2 的 KPI 基準。

2.1 段落與斷行

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

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

2.2 連結

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

站內相對連結則保持單頁切換（同視窗）：首頁、文章列表。

判斷規則：以 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 有序清單

第一步:盤點目前所有產品線（含 shibamimi / youyan / susumie）
第二步：計算各產品線的 ARR、MRR、Churn
第三步：與顧問討論成長假設與資源分配
第四步：準備財務試算表並送董事會
第五步：依董事會結論執行下一季 OKR

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

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

4.3 任務清單（GFM checklist）

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

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

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

MRR：Monthly Recurring Revenue，月經常性收入
NRR：Net Revenue Retention，淨收入留存率，含 churn 與 upsell
CAC payback：客戶取得成本回收期，目標 ≤ 12 個月

五、圖片

5.1 圖片放置位置

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

5.2 內文圖片寫法

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

連續多張圖也沒問題：

5.3 alt 文字撰寫原則

✅ 描述「圖中內容」，例如「白板上手繪的三品牌矩陣示意」
✅ 描述「圖中傳達的資訊」，例如「LTV/CAC 比率：3.5 倍，超過健康門檻」
❌ 不要寫「這是一張圖」「圖片」「示意圖」這類無資訊內容
❌ 不要重複文章周邊段落已有的描述，避免螢幕閱讀器重複朗讀

5.4 圖片載入優化

BlogImage 已自動套用：

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

六、引用區塊

6.1 一般引用

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

6.2 含格式的引用

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

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

6.3 多段引用

第一段：依據董事會 2026 Q1 決議，公司年度行銷預算上限為 ARR 的 30%。

第二段：超過此上限的支出須經 CEO 簽核，並於下次董事會列為例外項目報告。

6.4 巢狀引用

外層引用：來自 A 報告。

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

內層第二段。

外層延續。

七、表格（GFM）

7.1 基本表格

產品線	適用情境	主要效益
shibamimi	母品牌基礎建設	統一帳號 / 計費 / SSO
youyan	B2B 長文發布	自有網域、AI 校稿、SEO
susumie	B2C 創作者社群	手機優先、付費訂閱
企業版	中大型客戶	白標、SLA、API

7.2 含對齊與格式的表格

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

方案	適用客群	月費（NT$）	備註
Free	個人初試	0	含 3 篇／月
Pro	專業者	590	自有網域、AI 校稿
Team	小團隊	1,990	多人協作、進階分析
Enterprise	大型客戶	聯絡 BD	SLA、API、白標

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

八、程式碼區塊

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

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

8.1 TypeScript

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

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

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

8.2 TSX

import { useState } from 'react';
import { Button } from '@shibamimi-tech/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/articles/example-mdx-showcase

# 通過 production build 驗證
pnpm build

8.5 SQL

SELECT id, title, publish_date
FROM articles
WHERE published_at >= NOW() - INTERVAL '7 days'
ORDER BY publish_date DESC;

九、嵌入元件

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

import { EmbedLink, YouTubeEmbed } from '@shibamimi-tech/content/react';

9.1 EmbedLink — 外部連結卡片

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

最小參數版本：

Astro

Astro Docs

Astro 5 官方文件，含 Content Collections、Image、Islands Architecture 等完整指南。

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

Cloudflare

本站基礎建設供應商，提供 Pages、Workers、R2、Zero Trust Access 等服務。

可用 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://docs.shibamimi.com/articles/example-mdx-showcase#第一節-概述

10.6 文章內 cross-reference

用站內連結 + anchor：

跳到本文 § 七、表格
跳到另一篇文章特定段落：商業計畫書 § 募資需求

十一、content 套件擴充元件

除了 § 九介紹的 EmbedLink 與 YouTubeEmbed，@shibamimi-tech/content 還提供以下進階展示元件。本檔頂端已 import：

import { CalloutBox, Quote, Comparison, Timeline } from '@shibamimi-tech/content/blocks';
import { Mermaid } from '@shibamimi-tech/content/charts/Mermaid';
import { BarChart } from '@shibamimi-tech/content/charts/BarChart';

11.1 CalloutBox 提示框

5 種類型：info（資訊）、tip（提示）、warning（注意）、danger（警告）、success（成功）。

11.2 Quote 引言

兩種變體：default 卡片風（適合長段落）與 pullquote 大字嵌入（適合精選短句）。

本公司年度行銷預算上限為 ARR 的 30%，超過上限的支出須經 CEO 簽核並於下次董事會報告。

— 董事會決議紀錄（2026 Q1）

真正的長期主義不是做最大，而是做最久 — 柴米油鹽、有言、速速咩，一步一步來。

— 柴米科技有限公司

11.3 Comparison 比較表

兩欄並列，響應式自動 stacked。每欄可設 tone="positive" | "negative" | "neutral" 改變視覺。

youyan vs susumie

兩條產品線的核心差異

youyan（有言）

B2B — 給專業者

長文編輯器 + 多人協作
自有網域、SEO 結構化資料
月訂閱制 NT$590 起
目標客群：醫師 / 律師 / B2B 內容團隊

susumie（速速咩）

B2C — 給個人創作者

手機優先、輕量發文
付費訂閱 + Tip Jar
免費起跳，平台抽成
目標客群：個人 Newsletter 主、創作者

11.4 Timeline 時間軸

垂直時間軸，支援 milestone 變體高亮關鍵節點。

種子輪募資時程

2026 Q1
Deck 定稿
完成商業計畫書與財務試算
2026 Q2
初步接洽
與 10 家潛在投資人 1:1 會議
2026 Q2
Term Sheet 簽署
確定 lead investor 與估值
2026 Q3
Due Diligence
法務、財務、技術 DD
2026 Q3
Closing
資金到位，啟動下一階段招募與擴展

11.5 Mermaid 圖表（一打六）

一個元件涵蓋 10+ 種圖表類型。記得加 client:visible 才能載入 mermaid lib（~150KB gzipped），文章內多個圖表共用同一份。

11.5.1 Flowchart（流程圖）

載入圖表中…

11.5.2 Sequence Diagram（時序圖）

載入圖表中…

11.5.3 Gantt（甘特圖）

載入圖表中…

11.5.4 Mindmap（心智圖）

載入圖表中…

11.5.5 ER Diagram（實體關聯圖）

載入圖表中…

11.6 BarChart 統計圖

純 SVG / CSS 渲染，0 KB JS 下載（不需 client:* 指令）。適合簡單金額／比例呈現。

11.6.1 Horizontal（橫條，適合長 label）

2026 各月份新註冊用戶數

顯示 2026 年前半年的成長趨勢

1 月120 人
2 月180 人
3 月240 人
4 月210 人
5 月295 人
6 月320 人

11.6.2 Vertical（直條，適合多筆比較）

付費方案分布

62 %

Free

28 %

Pro

8 %

Team

2 %

Enterprise

十二、元件選型建議

需求	元件	載入成本
提示／注意事項	`<CalloutBox>`	0 KB
引言／重點摘要	`<Quote>`	0 KB
方案／產品比較	`<Comparison>`	0 KB
時程／流程進度	`<Timeline>`	0 KB
流程／時序／甘特／樹狀／心智／ER	`<Mermaid client:visible>`	~150 KB（首次）
簡單統計圖	`<BarChart>`	0 KB
外部連結卡片	`<EmbedLink>`	0 KB
YouTube 影片嵌入	`<YouTubeEmbed>`	iframe lazy load
進階互動圖（hover、動畫、多 series）	待後續加 recharts 等	TBD

十三、發佈流程

新增文章流程：

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

結語

以上即為部落格目前支援的所有 MDX 寫法、content 套件擴充元件與發佈流程。撰寫新文章時可直接複製本檔為起點，再依需要刪改各區段。

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

一、Frontmatter 欄位

1.1 完整 Frontmatter 範例

二、文字段落與強調語法

2.1 段落與斷行

2.2 連結

2.3 跳脫字元

三、多層級標題

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

這是 H4 標題

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

3.2 標題建議寫法

四、清單

4.1 無序清單

4.2 有序清單

4.3 任務清單（GFM checklist）

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

五、圖片

5.1 圖片放置位置

5.2 內文圖片寫法

5.3 alt 文字撰寫原則

5.4 圖片載入優化

六、引用區塊

6.1 一般引用

6.2 含格式的引用

6.3 多段引用

6.4 巢狀引用

七、表格（GFM）

7.1 基本表格

7.2 含對齊與格式的表格

八、程式碼區塊

8.1 TypeScript

8.2 TSX

8.3 JSON

8.4 Bash

8.5 SQL

九、嵌入元件

9.1 EmbedLink — 外部連結卡片

Astro Docs

Cloudflare

9.2 YouTubeEmbed — YouTube 影片嵌入

十、實用 MDX 撰寫小技巧

10.1 換行的處理

10.2 草稿不發佈

10.3 沒有封面圖也沒關係

10.4 SEO description 撰寫建議

10.5 標題連結（heading anchor）

10.6 文章內 cross-reference

十一、content 套件擴充元件

11.1 CalloutBox 提示框

11.2 Quote 引言

11.3 Comparison 比較表

youyan（有言）

susumie（速速咩）

11.4 Timeline 時間軸

種子輪募資時程

Deck 定稿

初步接洽

Term Sheet 簽署

Due Diligence

Closing

11.5 Mermaid 圖表（一打六）

11.5.1 Flowchart（流程圖）

11.5.2 Sequence Diagram（時序圖）

11.5.3 Gantt（甘特圖）

11.5.4 Mindmap（心智圖）

11.5.5 ER Diagram（實體關聯圖）

11.6 BarChart 統計圖

11.6.1 Horizontal（橫條，適合長 label）

2026 各月份新註冊用戶數

11.6.2 Vertical（直條，適合多筆比較）

付費方案分布

十二、元件選型建議

十三、發佈流程

結語