產品簡介與核心價值
EpoCanvas Docs 是專門為 EpoCanvas 開源生態打造的官方技術文件網站系統。它基於現代靜態網站框架 Astro 5 與 Starlight 建置，旨在為開發者提供一個排版專業、開啟速度快、搜尋順手、易於維護的文件平台。
無論是撰寫產品的使用手冊、API 介面規範，還是記錄系統架構設計，EpoCanvas Docs 都能讓撰寫者專注於寫好 Markdown 內容，同時為閱讀者提供舒適自然的瀏覽體驗。
解決的實際問題
在日常開發與技術寫作中，許多團隊在維護文件時常遇到以下困擾：
- 頁面開啟慢、記憶體佔用高：許多文件工具產生的頁面帶有大量 JavaScript 執行環境，在手機或弱網路環境下開啟慢，捲動長文章時容易卡頓。
- 長文章導覽費力：常見文件站通常只有左側選單，閱讀數千字的長篇技術說明時，難以快速掌握目前文章內部的小標題層級。
- 搜尋依賴外部服務：常見的 Algolia 等雲端搜尋服務需要額外申請帳號、設定爬蟲金鑰，在無法存取外部服務的內網環境中完全失效。
- 多語言只有半套：不少文件站宣稱支援多語言，實際上只有導覽按鈕翻了譯，點進文章內文還是原文；也有的譯文缺失時直接 404，讀者只能自己改 URL 找內容。
EpoCanvas Docs 正是為了解決這些實際痛點而設計的。
核心功能一覽
圖：產品簡介頁的實際渲染效果。左側為文件分類目錄，中央為內文，右側為自動產生的「本頁目錄」大綱，隨捲動高亮目前小節。
1. 清晰的三欄式閱讀介面
- 左側導覽欄：按模組組織所有文件分類，帶有層級摺疊，換頁不跳動。
- 中央內文區：內文最大寬度 60rem，行距 1.68，程式碼區塊自適應寬度，長時間閱讀不易疲勞。
- 右側大綱欄：自動擷取文章內的
h2與h3標題產生「本頁目錄」，隨捲動高亮目前閱讀位置，點擊任意小標題平滑跳轉。
2. 雙模式搜尋：頁內尋找 + 全站搜尋
- 目前頁尋找：直接在頂部搜尋框輸入關鍵字，頁面內所有符合的文字立即高亮，並顯示
3/9這樣的進度計數，按 Enter 逐個跳轉。 - 全站搜尋彈窗：按下
Ctrl + K（Mac 為Cmd + K）開啟全域搜尋彈窗，基於 Pagefind 靜態索引列出所有命中的文件與段落預覽。 - 全部搜尋能力都在瀏覽器本機完成，不依賴任何後端服務，託管在內網也能用。
3. 10 種語言的完整譯文
- 支援簡體中文、繁體中文、英語、日語、韓語、西班牙語、法語、德語、俄語、葡萄牙語共 10 種語言，每種語言的導覽、側邊欄與全部文件內文都是完整翻譯。
- 點擊右上角語言按鈕即可跳轉到同一篇文章的目標語言版本，URL 帶語言前綴（如
/en/canvas/），可直接加入書籤或分享給使用其他語言的同事。 - 個別頁面暫缺某語言譯文時，該頁自動回退顯示預設中文內容，不會出現 404 錯誤。
4. 專業的 Markdown 與程式碼排版
- 基於 Expressive Code 的程式碼高亮，支援為程式碼區塊標註檔名標題、高亮指定行、展示 diff 對比。
- 原生支援 4 種彩色提示框（Note、Tip、Caution、Danger），並支援自訂標題。
- 支援 GFM 表格、任務清單、刪除線等常用 Markdown 擴充語法，完整規則見渲染規則詳解。
5. 建置快、託管免費
- 基於 Astro 5 靜態編譯，建置產物為純 HTML、CSS 與少量視需要載入的 JS，全站 10 種語言約 180 個頁面完整建置約 25 秒。
- 預先內建 Cloudflare Pages 部署指令，一行指令即可將文件發布到線上，並自動取得 HTTPS 憑證。
專案整體架構
為了讓文件保持輕巧好維護，系統按職責劃分為四個部分：
圖：系統架構。撰寫者只需維護 Markdown 內容源，其餘環節全部自動完成。
- 底座與樣式：基於 Astro 5 靜態核心，透過
src/styles/custom.css定義設計變數，淺色與深色模式共用同一套變數名。 - 內容源管理：所有文件儲存在
src/content/docs/目錄下，使用純 Markdown（.md）或可嵌入元件的 MDX（.mdx）撰寫。 - 介面元件：透過覆蓋 Starlight 原生元件，客製化了頂欄、側邊欄、本頁目錄與搜尋彈窗。
- 分發與存取：編譯產物儲存在
dist/目錄，託管在 Cloudflare Pages，由全球 CDN 節點就近回應。
適合誰用
EpoCanvas Docs 適合以下場景：
- 開源專案的官方文件站：產品手冊、API 參考、架構說明，一個儲存庫全部搞定；
- 團隊內部知識庫：純靜態、無外部服務依賴，放在內網也能完整使用搜尋；
- 個人技術部落格式文件：只寫 Markdown，不用操心前端工程，一條指令發布。
它不適合需要登入驗證、留言互動、即時資料展示的場景——純靜態網站沒有後端，這類需求需要另行搭配服務。
常用文件工具比較
| 功能特性 | EpoCanvas Docs | Docusaurus | VitePress | GitBook 商業版 |
|---|---|---|---|---|
| 底層技術 | Astro 5 + Starlight | React 18 | Vue 3 + Vite | 閉源 SaaS 平台 |
| 搜尋機制 | Pagefind 本機靜態索引 | 依賴 Algolia 雲端服務 | Minisearch 記憶體搜尋 | 自帶後端搜尋 |
| 佈局設計 | 三欄（左選單 + 中內文 + 右目錄） | 需要設定外掛改造 | 預設雙欄/三欄 | 固定兩欄 |
| 部署方式 | Cloudflare Pages 直傳 | S3 / Vercel / GitHub | GitHub Pages | 平台私有託管 |
| 自主可控度 | 100% 開源，原始碼完全在手 | 100% 開源 | 100% 開源 | 閉源，付費功能多 |
技術棧與版本
目前版本實際使用的技術棧（以建置產物為準）：
| 元件 | 版本 | 作用 |
|---|---|---|
| Astro | v5.18.2 | 靜態網站核心，負責建置與路由 |
| Starlight | v0.32.6 | 文件站框架，提供版面骨架與內容處理 |
| Expressive Code | 隨 Starlight 整合 | 程式碼區塊高亮、標題欄、行高亮 |
| Pagefind | 經 @pagefind/default-ui 1.5.2 整合 | 建置期產生靜態搜尋索引 |
| Wrangler | v4.131.0 | Cloudflare 官方 CLI，執行部署 |
| 執行環境 | Node.js 18.20.8 / 20.3+ / 22+，pnpm 10 | 本機開發與建置環境；執行 pnpm run deploy 時 wrangler 要求 Node.js 22 以上 |
升級相依套件時，請同步閱讀 介面元件與二次開發 中的回歸測試注意事項。
專案目錄結構
本專案的程式碼組織如下，各目錄分工明確：
epocanvas-docs/├── public/ # 靜態資源目錄（圖片、向量圖示直接放這裡）│ └── images/canvas/ # 介面截圖與系統架構向量圖├── src/│ ├── components/starlight/ # 客製化的頁面元件（頂欄、側邊欄、本頁目錄、搜尋彈窗等）│ ├── config/navigation.ts # 頂部導覽欄設定（增刪選單項目改這裡）│ ├── content/docs/ # 文件內文 Markdown 檔案存放位置│ │ ├── index.mdx # 文件站首頁落地頁│ │ ├── canvas/ # 各章節文件（簡體中文，預設語言）│ │ └── en/ ja/ ... # 其他 9 種語言的完整譯文目錄│ ├── styles/custom.css # 全域樣式與主題顏色變數│ ├── utils/i18n.ts # 介面詞條字典與語言清單│ └── pages/404.astro # 自訂 404 頁（依瀏覽器語言輸出提示文字）├── scripts/ # 建置前快取失效、i18n／圖片／錨點覆核與截圖腳本├── astro.config.mjs # 站點主設定檔（標題、語言清單、側邊欄目錄在這裡設定）└── package.json # 專案相依套件與執行指令設定下一步
- 想在本機把專案跑起來？請閱讀 快速上手 (3 分鐘執行)。
- 想了解介面的具體佈局與使用方式？請閱讀 頁面佈局與閱讀體驗。
- 想開始撰寫新文件？請閱讀 Markdown 撰寫與排版指南 與 渲染規則詳解。