一篇文章的完整功能展示 / YOUR NAME

這是一篇用來展示文章功能的完整範例。它本身不是產品文件，而是一個可以直接閱讀、點擊與操作的測試頁面。

文章的內容檔案位於自己的 content bundle 裡，index.md 旁邊可以放圖片、圖表或其他只屬於這篇文章的檔案。

從 frontmatter 開始

每篇文章都需要幾個基本欄位，這些資料會出現在文章頁的標題區、文章清單與標籤頁：

title：文章標題。
summary：文章摘要。
createTime：建立時間，列表會依照它排序。
slug：由文章資料夾最後一段決定，文章不需要在 frontmatter 重複填寫。
tags：一個或多個標籤，可以從標籤索引頁回到這篇文章。

這篇文章位於 site-guide 資料夾，因此會自動加入由 site-guide/index.md 管理的 Site Guide 系列；updatedTime 則只屬於這篇文章。

圖片與點擊放大

圖片可以直接放在這個 index.md 的旁邊，使用相對路徑引用。下面這張圖就是同一個 content bundle 裡的檔案。

文章功能地圖

點擊圖片可以開啟放大預覽，也可以先用 Tab 聚焦圖片，再按下 Enter 或 Space。預覽視窗可以用 Escape、關閉按鈕或背景關閉，關閉後焦點會回到原本的圖片。

圖片的替代文字不是裝飾，它會在圖片載入失敗、使用螢幕閱讀器，或讀者只使用鍵盤時提供必要的上下文。

緊貼多張圖片的照片牆

兩張以上圖片若在 Markdown 中緊貼排列，中間沒有空白行或其他內容，會自動成為同一面照片牆。開啟其中一張後，可用左右按鈕或方向鍵在這一組圖片內切換：

空白行會結束這個圖片群組，所以下方這張圖仍維持單張呈現：

單張圖片不會變成照片牆

圖片檔案的位置

這篇文章的檔案結構如下：

src/content/blog/site-guide/2026-08-15-article-feature-tour/
├── index.md
├── feature-map.svg
├── gallery-layout.svg
├── gallery-notes.svg
└── gallery-preview.svg

系列本身的 metadata 位於上一層：

src/content/blog/site-guide/
├── index.md
└── 2026-08-15-article-feature-tour/
    ├── index.md
    ├── feature-map.svg
    ├── gallery-layout.svg
    ├── gallery-notes.svg
    └── gallery-preview.svg

ToC 與 hash 連結

這些標題會自動出現在右側的文章 ToC。ToC 會在捲動時高亮目前所在的章節，每個標題也都有穩定的 hash，可以直接分享給別人：

跳到程式碼區塊
跳到完整閱讀流程

標題可以被直接連結

例如這個子標題的 hash 是 #標題可以被直接連結。瀏覽器會在載入頁面時直接跳到這個位置，文章側欄的 ToC 也會同步更新目前章節。

程式碼與技術內容

文章支援 inline code，例如使用 pnpm build 檢查靜態路由，或用 pnpm new:post 建立下一篇文章。

type ArticleFeature = {
	name: string
	available: boolean
}

const features: ArticleFeature[] = [
	{ name: 'table of contents', available: true },
	{ name: 'image zoom', available: true },
	{ name: 'tag pages', available: true },
]

console.log(features.filter(feature => feature.available))

程式碼區塊會保留語言標記，讓閱讀者知道這段內容原本是以什麼語言撰寫。其他 inline code 則適合放入指令、檔名或短小的 API 名稱。

連結與文章導覽

文章可以連到站內頁面，例如所有文章、所有系列與所有標籤，也可以連到外部網站，例如 Astro。

文章頁的側欄會顯示建立時間、更新時間、系列與 tags；頁面底部則會提供上一篇、下一篇與文章清單導覽。

完整閱讀流程

一篇文章從建立到發佈，可以依照這個流程：

執行 pnpm new:post -- "文章標題"，並輸入不含日期的可讀 slug。
指令建立新的 index.md，並用 ${EDITOR:-vim} 開啟它。
如果文章屬於系列，使用 pnpm new:post -- "文章標題" --series=site-guide，讓文章放在對應系列資料夾。
在 frontmatter 填好 tags、摘要與必要欄位。
把圖片或其他附件放到同一個文章目錄；緊貼的多張 Markdown 圖片會自動成為照片牆。
用 Markdown 寫入標題、段落、列表、引用、連結與程式碼。
執行 pnpm check 與 pnpm build，確認內容 schema、文章路由與圖片最佳化都能通過。

這篇文章同時也是一個小型的回歸測試。當任何文章功能被修改時，可以回到這裡確認所有內容類型仍然能正常呈現。