知識庫範例 · 這份指南說明此網站的內容維護方式，供你之後直接擴充。
1. 複製一個內容資料夾
寫部落格時，一般文章複製 src/blog/2026/ai-action-launch/，自由版型文章複製 src/blog/2026/custom-article/。寫知識庫時，複製 src/kb/examples/publishing-guide/。先把複製出來的每份來源都設為 draft: true，移除範例的 aliases，編輯期間就不會進入正式產物。
修改每份檔案開頭的 pageId、translationKey、title、description 與 permalink。每個 pageId 和網址都要唯一；同篇文章的不同語言版本使用相同的 translationKey。
部落格依「發文年份／slug」收納，知識庫依「主題代碼／slug」收納。slug 是固定的文章名稱，例如 create-library。公開網址由 permalink 獨立指定，不把年份或主題資料夾加入網址，也不隨標題改字而自動改名。
2. 各自撰寫繁中與英文
此範例的英文在 index.md，繁中在 index.zh-Hant.md。其他語言也加上自己的語言代碼。兩份 Markdown 各自撰寫；沒有翻譯時，只保留實際寫好的語言。自由版型部落格則繼續使用 .njk HTML，英文為 index.njk，繁中為 index.zh-Hant.njk。
知識庫使用固定模板：標題、內文、側邊分類、右側目錄與上下篇導覽都由共用版型提供，不加入自訂 CSS 或 JavaScript。需要自由編排時，請寫成部落格的自由版型文章。
正文從 ## 開始，主標題由版型提供。## 與 ### 會自動加入目錄；需要保留固定段落連結時，在標題結尾填入 {#copy} 這類代碼。知識庫用數字 order 決定順序。分類名稱可翻譯，categoryKey 則讓同一分類的中英版本互相對應。
圖片放在同層 assets/，正文寫成 。連到其他文章時，可以直接填相對 .md 或 .njk 來源路徑，建置會轉成正式網址。程式碼使用反引號；Markdown 正文不執行 HTML 或網站版型指令。
3. 設定搜尋資訊、分享圖與封面
官網頁面、部落格與知識庫都用檔案開頭的 title、description 產生搜尋與分享資訊。不需要不同文案時，保留這兩個欄位即可。需要分別設定時，再加入選填的 meta：
meta:
title: "搜尋使用的標題"
description: "搜尋使用的摘要。"
share:
title: "分享連結使用的標題"
description: "分享連結使用的摘要。"
image:
src: assets/og-image.png
alt: "這張分享圖片的內容說明"
meta.title、meta.description 覆寫 HTML 的搜尋標記；meta.share 覆寫分享標記。兩組各自沿用未覆寫的原始 title、description，不互相套用，也不改動文章主標題、站內搜尋或 RSS。
先把圖片放進這一頁自己的 assets/，再填相對路徑。例如介紹頁使用 src/pages/about/assets/og-image.png，部落格使用該篇文章資料夾的 assets/og-image.png。知識庫也用同樣寫法。圖片支援 PNG、JPEG、WebP、GIF，alt 填圖片說明；不使用外站圖片網址或 ../ 跨資料夾取圖。建置會檢查檔案，並把路徑轉成分享需要的完整網址。
部落格還可以設定封面。先將圖片放在文章的 assets/cover.webp，再加入：
cover:
src: assets/cover.webp
alt: "文章封面的內容說明"
預設版型會在文章顯示封面，列表顯示縮圖。自由版型自行安排正文中的封面位置，列表仍使用 cover。官網頁面與知識庫只設定 meta.share.image，不使用部落格專用的 cover。
分享圖片依序使用本頁的 meta.share.image、部落格的 cover、全站預設圖。所以只設定封面時，同一張圖就會成為 og:image；需要不同分享圖時，再另外指定。全站預設圖是 public/assets/share-default.png，不必在每篇重複填寫。
主要網址、分享圖、RSS 與網站地圖的完整網址，統一使用 cloudflare-deploy.json 裡的 siteUrl 作為預設網域。更換網域時修改這個欄位，不用逐篇改文章。一般建置也可用 SITE_URL 環境變數覆寫；BASE_PATH 用於部署子目錄，目前 Cloudflare 部署在網域根目錄，保持空白。
4. 檢查完成後發布
內容準備好後，將對應檔案設為 draft: false，執行：
npm run test:quick
npm run preview
在預覽中確認標題、目錄與正文圖片。設定部落格封面時，也檢查文章和列表的圖片。檢視頁面原始碼，確認 <title>、描述與 og:image 使用預期內容。
確認預覽後，執行以下指令。它會建置並檢查內容、連結和發布產物，通過後發布到 cloudflare-deploy.json 的 siteUrl 指定網域：
npm run deploy-cloudflare
只檢查、不上傳可使用 npm run deploy-cloudflare -- --check-only。發布會包含目前分支的未提交修改與未被 Git 忽略的新檔案，請先儲存要發布的內容。指令不會自動 commit、push 或合併 PR；推送 main 也不會自動發布正式網站。
需要保存與審查程式時，另外 commit、push 並建立 PR。列表、分類、語言切換、RSS、網站地圖與搜尋索引都會隨建置更新，不必再維護文章清單。