文章格式完全示範

忘記語法怎麼寫，回來翻這篇就好

這篇是寫給自己的參考文章：把這個站支援的 Markdown 語法全部用過一輪，附上原始碼與實際效果。寫新文章時忘記某個語法怎麼寫，回來翻這篇就好。

建議的閱讀方式是開著原始碼對照看——右側目錄可以直接跳到你要找的段落。

• 開頭：frontmatter
• 文字與行內元素
• 標題層級
  • 這是第三層標題
• 清單
• 引用與提示框
• 表格
• 程式碼
  • 行號與標記行
  • 行內標記
  • 多種寫法並列
• 圖片
• 步驟輪播
• 在文章裡放元件
• 寫完之後
• 附錄：目前不支援的語法

開頭：frontmatter

每篇文章最上方的 frontmatter 決定了它在站上的所有 metadata。在編輯器輸入 post 按 Tab 可以展開骨架：

---
title: "文章標題（含冒號時要加引號）"
description: "給搜尋引擎與列表頁的摘要，約 80–120 字"
date: 2026-07-20        # 發布日期
updated: 2026-07-20     # 更新日期：標題上方小字、列表排序都用它
tags: ["標籤A", "標籤B"]
image: ../../images/posts/<分類>/<slug>/cover.png   # 選填，社群分享縮圖
day: 1                  # 逐日連載選填，顯示 Day 並控制分類排序
order: 1                # 其他文章選填，與 day 擇一
---

兩個容易忘記的地方

title 或 description 裡有冒號時一定要加引號，否則 YAML 解析會失敗、build 直接中斷。另外改完文章記得更新 updated——這是讀者判斷內容新舊的唯一依據。

分類不寫在 frontmatter 裡，由檔案放在哪個資料夾決定。這篇放在 posts/ai-tools/，所以它的分類就是「AI 工具運用」，網址是 /ai-tools/markdown-format-showcase。day 只在逐日連載文章使用，會顯示 Day 標記並控制分類首頁與側欄順序；一般文章不需要填。

文字與行內元素

段落就是普通的文字，中間空一行就是新段落。行內可以用粗體、斜體、刪除線、行內程式碼，以及鍵盤按鍵如 ⌘ + K（開啟搜尋）。

連結分兩種寫法：站內文章用相對於根目錄的路徑，例如另一篇範例文章；站外連結直接寫網址，例如 VitePress 官方文件。

需要標註來源或補充說明時可以用註腳^[1]，數字會自動編號，點下去跳到文末^[2]。

也可以放表情符號 🎉 🚀 💡，用 :名稱: 的寫法。

---

上面那條分隔線是三個減號 ---。

標題層級

文章的主標題（#）由 frontmatter 的 title 產生，內文請從 ## 開始寫。

這是第三層標題

右側目錄只收 ## 與 ### 兩層，所以第三層以下不會出現在目錄裡，適合放不需要被索引的細節。

這是第四層標題

第四層以後就純粹是視覺分隔了。

清單

無序清單用減號：

• 第一項
• 第二項
  • 巢狀項目要縮排兩格
  • 再一項
• 第三項

有序清單用數字（後面的數字寫什麼都會自動重新編號）：

1. 先做這件事
2. 再做這件事
3. 最後做這件事

教學文最實用的是任務清單，讀者可以邊做邊勾：

• 安裝好 Node.js 20 以上版本
• 用 pnpm install 用 `pnpm install` 裝好套件
• 申請 API 金鑰
• 完成第一次部署

引用與提示框

一般引用用 >：

好的教學不是把知識講完，而是讓讀者能自己走完下一步。

需要強調時用提示框。這個站支援 GitHub 風格的五種提示：

NOTE

補充說明，讀者知道更好、不知道也不影響操作。

TIP

小技巧，通常是「其實有更快的做法」。

IMPORTANT

一定要看的關鍵資訊，跳過會卡住。

WARNING

有風險的操作，做之前先想清楚。

CAUTION

可能造成資料遺失或不可逆後果的動作。

也可以用容器語法，好處是可以自訂標題：

這是自訂標題

容器語法寫成 ::: tip 標題，結尾用 :::。標題不寫的話會顯示預設的「TIP」。

資訊

info 是中性的補充說明，顏色最不搶戲。

危險

danger 用在真的會出事的地方，例如刪除資料、覆寫設定。

內容很長、又不是每個讀者都需要看的話，用可折疊的 details：

點我展開：為什麼文章圖片不放進 git？

圖片放進 git 會讓 repo 越來越肥，而且每次修圖都會產生一份完整的新檔案，clone 一次要拉整個歷史。這個站的做法是圖片只存在本機並上傳 Cloudflare R2，git 裡只留一份記錄檔案雜湊的 manifest 用來去重。

詳細的運作方式寫在另一篇文章裡。

表格

表格用管線符號分隔，第二行的冒號決定對齊方式：

指令	用途	執行頻率
pnpm dev	本機開發，改檔案即時更新	每天
pnpm build	建置靜態檔案到 .vitepress/dist	部署前
pnpm upload:images <範圍>	上傳圖片到 R2，內容沒變會自動跳過	每篇文章
pnpm release	建置並部署到 Cloudflare	每次上線

為什麼不是 pnpm deploy？

因為 deploy 是 pnpm 的內建指令，會被攔截而不會執行 package.json 裡的 script，所以這個站的部署指令叫 release。

程式碼

行內程式碼用單反引號，像 const answer = 42 這樣。

單獨的程式碼區塊用三個反引號加上語言名稱：

interface Post {
  title: string
  updated: string
  tags: string[]
}

function isRecent(post: Post): boolean {
  const days = (Date.now() - +new Date(post.updated)) / 86_400_000
  return days < 30
}

行號與標記行

在語言後面加 :line-numbers 開行號，用 {行號} 標記重點行：

const config = {
  title: '卡斯伯線上開發書',
  // 這兩行會被標記起來
  cleanUrls: true,
  lastUpdated: true,
}

行內標記

也可以直接在程式碼的註解裡標記，這樣行號變動時不用回頭改：

const a = 1
const b = 2
const c = 3

focus 會把其他行淡出，適合強調某一行：

function setup() {
  const app = createApp()
  app.mount('#root') 
  return app
}

++ 與 -- 做成 diff 的效果，教「改哪一行」時很好用：

export default {
  appearance: true,
  appearance: 'dark',
}

error 與 warning 用來標出有問題的寫法：

const data = JSON.parse(raw) 
const value = someObject.maybeMissing 

多種寫法並列

同一件事有多種做法時用 code-group，讀者可以切換分頁：

pnpm

pnpm add -D vitepress

npm

npm i -D vitepress

yarn

yarn add -D vitepress

圖片

在編輯器裡直接貼上截圖，會自動存到 images/posts/<分類>/<文章檔名>/ 並插入相對路徑，開發時直接就能預覽：

圖片路徑只能用貼上流程產生的形式

路徑一定要是 ../../images/... 開頭。只有這種形式會在建置時被改寫成圖床網址；把圖片放在文章旁邊或用 <img> 標籤引用，會讓建置失敗或繞過整個圖片管線。

步驟輪播

多張操作截圖不要一張張往下堆，用輪播包起來。輸入 carousel 按 Tab 展開，然後把圖片貼進去（圖片之間要留空行）：

steps

一張圖就是一個步驟，圖片的 alt 文字會顯示在下方當作步驟說明。三張圖的比例刻意做得不一樣，可以看到切換時高度會平順地跟著變化；手機上可以直接左右滑動。

在文章裡放元件

Markdown 檔案裡可以直接寫 Vue 元件，全站註冊過的元件都能用。例如列出某個標籤的所有文章：

文章格式完全示範：這個站能用的所有 Markdown 寫法

一篇把本站可用格式全部用過一輪的參考文章：frontmatter 欄位、標題、清單、表格、五種提示框、程式碼區塊的六種標記、步驟輪播、註腳與 Vue 元件，寫文章時忘記語法就回來翻。

AI 工具運用更新於 2026-09-13#寫作流程#Markdown#VitePress#範例

範例文章：文章格式與步驟輪播示範

這篇範例文章示範本站的文章慣例：frontmatter 欄位、圖片貼上流程，以及用 carousel 容器標籤呈現多步驟截圖的輪播效果。

AI 工具運用更新於 2026-07-20#範例#寫作流程

範例文章：本站圖片為什麼放在 R2

這篇範例文章示範一般文章的格式，同時說明本站的圖片管線：本機預覽、build 時改寫網址、上傳 R2 與去重的運作方式。

雲端服務知識更新於 2026-07-20#範例#Cloudflare#R2

上面那塊是 <PostList tag="範例" /> 產生的，它也支援 category 與 limit 兩個屬性。

寫完之後

最後照這個順序收尾：

1. 檢查 frontmatter 的 updated 是不是今天
2. pnpm upload:images posts/ai-tools/markdown-format-showcase 上傳這篇的圖片
3. pnpm dev 看一遍實際效果，特別是輪播與圖片
4. pnpm release 建置並部署

上傳圖片不用擔心重複

上傳腳本會比對每個檔案的內容雜湊，已經上傳過而且沒有修改過的圖片會自動跳過，所以指令重複執行很多次也沒關係。

附錄：目前不支援的語法

以下這些寫在文章裡不會有效果，需要時再另外加套件：

語法	狀態
數學公式 $E = mc^2$	未啟用，需要加 markdown.math 設定與套件
定義列表	未啟用
==螢光標記==	未啟用
Mermaid 流程圖	未啟用，需要額外套件

---

1. 註腳的內容寫在文章任何地方都可以，最後都會統一收到文章底部。 ↩︎

2. 註腳右邊的 ↩︎ 可以跳回原本閱讀的位置。 ↩︎