Aither (繁體中文)

Astro-Theme-Aither 使用指南

Sat, 14 Mar 2026 08:00:00 GMT

本指南涵蓋從零開始到完成部署多語言部落格的完整流程。你可以從頭讀到尾，也可以直接跳到需要的章節。 ## 前置條件 - [Node.js](https://nodejs.org/) 22 LTS 或更新版本 - [pnpm](https://pnpm.io/) 10 或更新版本 - 一個 GitHub 帳號 - 一個 [Cloudflare](https://cloudflare.com/) 帳號（用於部署） ## 安裝 ```bash git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git cd YOUR_REPO corepack enable pnpm install pnpm validate pnpm dev ``` 接著在瀏覽器中打開 `http://localhost:4321`。 ## 專案結構 ```text src/ ├── components/ # Astro 與 React 元件 ├── config/site.ts # 站點名稱、導覽、頁尾、社群連結 ├── content/posts/ # 依語系組織的文章內容 ├── i18n/ # UI 文字翻譯 ├── layouts/ # 版面元件 ├── lib/ # 工具函式 ├── pages/ # 路由頁面 └── styles/global.css # Tailwind v4 主題 token ``` ## 設定 ### 站點設定 `src/config/site.ts` 是整個站點的單一設定來源： ```typescript export const siteConfig = { name: '你的部落格名稱', title: '你的標語', description: '你的站點 SEO 描述', author: { name: '你的名字', avatar: '', }, }; ``` ### 環境變數 ```bash cp .env.example .env ``` 如果某個變數留空，對應服務就會自動停用。 ### 站點 URL 在 `astro.config.mjs` 中設定正式網址： ```javascript import { defineConfig } from 'astro/config'; import aither from '@aither/astro'; export default defineConfig({ site: 'https://your-domain.pages.dev', integrations: [aither()], }); ``` ## 撰寫文章在 `src/content/posts/en/` 下建立新的 `.mdx` 檔案： ```markdown --- title: 我的第一篇文章 date: "2026-03-14T16:00:00+08:00" category: General description: 用於 SEO 與社群預覽的簡短摘要。 tags: [Topic, Another] pinned: false --- 正文從這裡開始。 ``` ### Frontmatter 參考 | 欄位 | 型別 | 必填 | 說明 | |------|------|------|------| | `title` | string | 是 | 文章標題 | | `date` | date | 是 | 發布時間（例如 `2026-03-14T16:00:00+08:00`） | | `category` | string | 否 | 分類 | | `description` | string | 否 | SEO 描述 | | `tags` | string[] | 否 | 標籤列表 | | `pinned` | boolean | 否 | 是否置頂 | | `image` | string | 否 | 封面圖片 | ### MDX 元件你可以在內容中直接匯入互動元件： ```mdx import MyChart from '@/components/MyChart' ``` ## 國際化主題預設支援 11 種語言。要新增翻譯文章，只要在目標語系資料夾建立同名檔案： ```text src/content/posts/en/my-post.mdx src/content/posts/zh-hant/my-post.mdx src/content/posts/fr/my-post.mdx ``` UI 文字位於 `src/i18n/messages/`。 ## 自訂內容分區你可以透過 `src/content.config.ts` 與 `src/config/site.ts` 增加翻譯、筆記、教學等自訂集合。之後列表頁、詳情頁與導覽入口都會自動生成。 ## 主題樣式系統分成兩層： - 顏色模式：`light`、`dark`、`system` - 風格樣式：`default` 或內建樣式如 `evolution` ```typescript ui: { defaultMode: 'system', defaultStyle: 'default', showMoreThemesMenu: true, }, ``` 顏色 token 位於 `src/styles/global.css`。預設字型為系統 sans-serif，程式碼區塊則使用 monospace。 ## SEO 與 AI 每個頁面都已內建以下輸出： - `/sitemap-index.xml` - `/rss.xml` - `/robots.txt` - `/llms.txt` - `/llms-full.txt` - `/posts/slug.md` - JSON-LD 與 Open Graph ## 部署 ### Cloudflare Pages 最佳實踐：先建立 Pages 專案。工作流程預設使用倉庫名稱；如果需要覆蓋，請設定 `CLOUDFLARE_PAGES_PROJECT_NAME`。請在 GitHub Secrets 中設定： - `CLOUDFLARE_API_TOKEN` - `CLOUDFLARE_ACCOUNT_ID` 然後執行 `pnpm validate`，再推送到 `main`。 ## 常用指令 | 指令 | 說明 | |------|------| | `pnpm dev` | 啟動本地開發伺服器 | | `pnpm validate` | 執行完整的推送前驗證 | | `pnpm build` | 建立正式環境 build | | `pnpm preview` | 在本機預覽 production build | ## 版本方案公開 release tag 使用 CalVer 風格命名，例如 `v2026.04.08`。

AI 智能體在真實專案中的最佳實踐（範例）

Sat, 10 Jan 2026 08:00:00 GMT

AI 智能體真正有價值的時候，往往不是它看起來像「魔法」，而是它開始表現得像一套穩定的生產力工具。效果最好的團隊，不會讓智能體「把一切都做完」，而是會明確任務、提供足夠上下文，並讓結果容易驗證。這聽起來很基本，但差異非常大。任務描述清楚時，智能體可以推進得很快，產出也常常相當扎實。任務邊界模糊時，它則容易浪費上下文、繞很多彎路，最後交回一份看起來很有把握、但沒有真正解決問題的結果。 ## 從小而明確的任務開始最適合交給智能體的任務，通常都具體、明確，而且邊界清楚。不要只說「優化一下這個應用」，而要說「修復部落格頁在行動端的導覽重疊問題」，或是「替 RSS 訂閱源新增一個冒煙測試」。任務越聚焦，智能體的目標就越穩定，也越不容易順手改動無關部分。這同樣能降低審查成本。任務夠小時，改了什麼、應該怎麼測、結果是否正確，都會更容易判斷。 ## 把上下文寫清楚對智能體來說，重要上下文最好寫出來，而不是預設它能自行推斷。一份高品質的任務說明通常包括： - 明確的目標 - 相關檔案或目錄 - 不能更動的限制條件 - 預期輸出或完成標準 - 最後需要執行的驗證命令人類通常能從零散資訊裡補出很多東西，智能體往往更「照字面理解」。如果某個細節重要，就應該明確寫出來。 ## 盡量讓智能體用工具，而不是靠猜智能體在動手之前，應該先查看目前系統，而不是直接套用泛化經驗。這代表先閱讀相關檔案、檢查建置方式、理解現有慣例，而不是只憑模型記憶來判斷。對外部系統也是一樣。如果問題依賴最新文件、部署設定或線上實際行為，就應該優先用工具確認真實狀態，而不是「憑印象回答」。這也是為什麼機器可讀介面如此重要。清楚的目錄結構、明確的驗證腳本、型別定義和顯式設定，都會讓智能體更可靠，因為環境本身就在提供說明。 ## 讓輸出天然可驗證一個好的智能體工作流，不應該停在「這是答案」，而應該停在「這是可核驗的結果」。要求智能體說明它改了什麼、測了什麼、哪些地方還無法驗證。理想的輸出通常具備這些特徵： - diff 足夠小 - 驗證命令能順利通過 - 能給出可重現的截圖或預覽 - 會明確說明風險與假設驗證環節，決定了智能體的產出只是「看起來合理」，還是「真的可以依賴」。 ## 讓回復與修正成本足夠低再強的智能體也會走錯路。正確做法不是避開智能體，而是讓修正代價足夠低。盡量把任務拆小，腳本保持穩定，流程保留檢查點。能做到冪等的操作就盡量冪等。避免那種「一步走錯，後面就會留下很大爛攤子」的工作流。如果一個任務可以拆成讀取、規劃、實作、驗證四步，那就這樣拆。智能體在那些易於檢查、易於測試、易於繼續推進的系統裡，表現通常最好。 ## 人工複核仍然不可取代智能體非常擅長速度、覆蓋率和重複勞動，但判斷力仍然屬於人。產品取捨、安全邊界、語氣風格、品牌表達，以及長期可維護性，仍然應該由理解全局的人來把關。目標不是把人移出流程，而是讓人少花時間在機械勞動上，把精力放到真正需要判斷與責任的地方。 ## 一個實用的心智模型可以把 AI 智能體看成一位執行力很強、速度很快，而且非常照字面理解的協作者。給它清楚的任務，給它合適的工具，讓它展示過程，然後像審查任何重要更動一樣去複核結果。真正的槓桿，就在這裡。

AI 智慧體與工具使用（範例）

Fri, 09 Jan 2026 08:00:00 GMT

AI 智慧體是一個能夠執行操作的語言模型——不僅僅是生成文字。它能搜尋網頁、執行程式碼、呼叫 API、讀取檔案，並決定下一步做什麼。 ## 從對話到行動聊天機器人回答問題，智慧體解決問題。區別在於自主性：智慧體決定使用哪些工具、以什麼順序、如何處理錯誤。這種轉變意義深遠。傳統的聊天機器人是被動的——使用者問一個問題，它給出一個回答，對話結束。智慧體則是主動的——你給它一個目標，它會自行規劃步驟、收集資訊、執行操作，直到目標達成。舉一個具體的例子：你告訴智慧體「幫我修復這個 CI 失敗的問題」。它不是簡單地建議你怎麼做，而是：讀取 CI 日誌，分析錯誤原因，查看相關的程式碼檔案，編寫修復程式碼，執行測試確認修復有效，最後建立一個 Pull Request。整個過程中，它在每一步都做出判斷和決策。 ## 工具使用工具使用讓 AI 模型呼叫外部函式。模型判斷何時需要工具，生成正確的參數，並將結果整合到回答中。這把文字生成器變成了強大的助手。 ### 工具的類型常見的智慧體工具包括： - **資訊檢索工具**：網頁搜尋、資料庫查詢、檔案讀取 - **程式碼執行工具**：在沙箱環境中執行 Python、JavaScript 等程式碼 - **API 呼叫工具**：與外部服務互動，如發送電子郵件、建立工單、部署應用 - **檔案操作工具**：建立、編輯、刪除檔案和目錄 - **瀏覽器操作工具**：打開網頁、點擊按鈕、填寫表單 ### 工具定義在技術實作上，工具通常以結構化的格式定義，包含名稱、描述和參數的 JSON Schema。模型根據工具描述來判斷何時以及如何使用每個工具。好的工具描述對智慧體的表現至關重要——模糊的描述會導致模型在錯誤的時機呼叫錯誤的工具。 ```json { "name": "search_documents", "description": "在知識庫中搜尋與查詢相關的文件片段", "parameters": { "query": { "type": "string", "description": "搜尋關鍵字或自然語言查詢" }, "limit": { "type": "integer", "description": "回傳結果的最大數量", "default": 5 } } } ``` ## 智慧體循環最強大的模式是智慧體循環：模型規劃一個步驟，執行它，觀察結果，然後決定下一步。這個循環持續到任務完成或模型判斷無法繼續。 ### 循環的結構一個典型的智慧體循環包含四個階段： 1. **觀察**：接收當前的環境狀態和最新的工具執行結果 2. **思考**：分析當前狀態，判斷是否已完成目標，決定下一步行動 3. **行動**：選擇並呼叫適當的工具 4. **更新**：將工具的執行結果加入對話歷史，回到觀察階段這個循環的關鍵在於模型的**規劃能力**。優秀的智慧體不會盲目地一步步嘗試，而是在行動前先形成一個大致的計畫，然後在執行過程中根據實際結果動態調整。 ### 錯誤處理在真實世界中，工具呼叫經常失敗——API 可能返回錯誤、檔案可能不存在、網路可能超時。好的智慧體需要優雅地處理這些失敗：嘗試替代方案、向使用者請求澄清，或者承認當前任務無法完成。 ## 實際應用智慧體技術已經在多個領域展現出巨大價值： - **軟體開發**：自動化程式碼審查、bug 修復、功能實作和測試撰寫 - **資料分析**：自動查詢資料庫、生成報表和視覺化圖表 - **客戶服務**：不僅回答問題，還能直接在後臺系統中執行操作，如退款、修改訂單 - **IT 運維**：監控系統狀態、自動排查問題、執行修復操作 ## 風險能執行操作的智慧體也能執行錯誤的操作。沙箱隔離、確認步驟和人工審查是任何生產級智慧體系統的必要安全措施。 ### 安全設計原則在設計智慧體系統時，應遵循以下原則： - **最小權限**：只授予智慧體完成任務所需的最低權限，不要給予不必要的存取權 - **破壞性操作需確認**：刪除資料、發送通知等不可逆操作應要求使用者明確確認 - **沙箱執行**：程式碼執行應在隔離的沙箱環境中進行，防止對宿主系統造成損害 - **行為日誌**：記錄智慧體的每一個決策和操作，便於事後審計和問題排查 - **速率限制**：限制智慧體在單位時間內能執行的操作次數，防止失控的循環智慧體技術仍在快速發展中。隨著模型推理能力和工具使用能力的提升，智慧體能夠承擔的任務複雜度也在持續增加。

✨ 為什麼選擇 Astro-Theme-Aither（範例）

Sat, 03 Jan 2026 08:00:00 GMT

一個相信文字本身就很美的 AI 原生 Astro 主題。 ## 設計理念極簡設計，不極簡工程。當頁面上沒有花俏的視覺元素來掩蓋問題時，任何瑕疵都會被放大。極簡設計對工程品質的要求更高，而不是更低。排版參數遵循 Apple 人機介面指南：17px / 1.47 / -0.022em。全站統一無襯線系統字型棧。字型本身就是視覺標識。 ## AI 原生為 AI 智能體時代而生。每個頁面都天然可被機器閱讀： - **llms.txt** — AI 智能體內容索引，`/llms.txt` - **llms-full.txt** — 全文輸出，`/llms-full.txt` - **Markdown 端點** — 任何文章 URL 後加 `.md` 取得源檔案 - **JSON-LD** — 每篇文章的 Article 結構化資料 - **robots.txt** — 明確歡迎 GPTBot、ClaudeBot、PerplexityBot 你的內容不只是發布了——它是 AI 可發現的。 ## 基於 Astro Astro 的島嶼架構意味著只有互動元件載入 JavaScript。其他一切都是靜態 HTML 和 CSS，瞬間載入。互動式島嶼：主題切換器（View Transitions API 圓形展開動畫）、語言切換器、瀏覽器語言偵測、行動端導覽。 ## 功能 - **Tailwind CSS v4** — `@theme` 設計令牌，完整明暗主題自訂 - **i18n** — 多語言支援，自動瀏覽器語言偵測 - **文章置頂** — 將重要文章固定在列表頂部 - **深色模式** — 淺色 / 深色 / 系統，View Transitions API 動畫 - **Content Collections** — 建構時型別安全 Markdown 驗證 - **SEO** — Open Graph、規範 URL、Twitter Cards - **RSS + 網站地圖** — 自動產生，零設定 - **Google Analytics / Crisp Chat / Giscus** — 可選，透過 `.env` 設定 - **Vitest + Playwright** — 單元 + E2E 測試，整合 CI - **部署** — GitHub Pages（預設）+ Cloudflare Pages（可選） ## 適合誰如果你相信好的文字自己會說話： - **部落客** — 想讓文字成為絕對主角 - **技術寫作者** — 需要清晰的程式碼區塊和內容結構 - **多語系作者** — 需要內建 i18n 和語言偵測 - **開發者** — 欣賞工程品質過硬、可放心擴展的程式碼庫寫任何話題——排版會讓它看起來很好。

📝 Markdown 樣式指南

Fri, 02 Jan 2026 08:00:00 GMT

這篇文章演示了 Astro-Theme-Aither 支援的每一個 Markdown 功能。寫作時可以將它作為參考。 ## 標題使用 `##` 作為章節標題，`###` 作為子章節，`####` 作為三級子章節。避免在正文中使用 `#`——文章標題已經作為頂級標題呈現。 ### 三級標題 #### 四級標題 ### 標題的最佳實踐一篇結構良好的文章通常只需要兩到三個層級的標題。過多的層級嵌套會讓讀者迷失方向。建議遵循以下原則： - **`##` 用於主要章節**：每個主要章節代表文章的一個核心論點或主題 - **`###` 用於子章節**：在需要進一步細分時使用 - **`####` 謹慎使用**：只在確實需要第三層級時才使用，通常表示你的內容結構可能需要重新組織 ## 段落與換行普通段落文字自然流動。在段落之間留一個空行來分隔它們。這是第二個段落。保持每個段落圍繞一個想法，以獲得最佳閱讀體驗。寫作時，建議每個段落控制在三到五句話之間。過長的段落會形成視覺上的「文字牆」，讓讀者望而卻步。適當地將長段落拆分成幾個短段落，可以顯著提升閱讀體驗。如果你發現一個段落超過了六七行，考慮將其拆分。 ## 強調 - **粗體文字** 使用 `**雙星號**` - *斜體文字* 使用 `*單星號*` - ***粗斜體*** 使用 `***三星號***` - ~~刪除線~~ 使用 `~~雙波浪號~~` 強調標記應謹慎使用。如果一段文字中到處都是粗體，那粗體就失去了強調的效果。一般來說，每個段落中最多使用一到兩處粗體來突出關鍵概念即可。斜體在中文排版中不太常用，因為中文字型的斜體渲染效果通常不如西文字型理想。 ## 連結 [行內連結](https://astro.build) 使用 `[文字](url)` 語法。連結文字應該具有描述性，讓讀者不需要點擊就能知道連結指向的內容。避免使用「點擊這裡」或「連結」這樣的空洞文字。例如： - 不佳：更多資訊請[點擊這裡](https://astro.build) - 推薦：查看 [Astro 官方文件](https://astro.build) 了解更多 ## 列表無序列表： - 第一項 - 第二項 - 巢狀項 - 另一個巢狀項 - 第三項有序列表： 1. 第一步 2. 第二步 1. 子步驟一 2. 子步驟二 3. 第三步任務列表： - [x] 搭建專案 - [x] 寫第一篇文章 - [ ] 部署到生產環境 ### 列表使用建議列表是組織資訊的利器，但需要注意以下幾點： - 當項目之間有明確的順序關係時，使用有序列表 - 當項目之間是並列關係時，使用無序列表 - 每個列表項盡量保持簡潔，通常一到兩行即可 - 如果列表項需要大量解釋，可能更適合使用子標題加段落的形式 ## 引用 > 抽象的目的不是為了模糊，而是為了創造一個新的語意層級，在其中可以做到絕對精確。 > > — Edsger W. Dijkstra 巢狀引用： > 第一層 > > > 第二層 > > > > > 第三層引用區塊適合用於展示名人語錄、重要聲明或需要特別突出的文字段落。在技術文章中，也可以用來標記重要的警告或提示資訊。 ## 程式碼使用反引號包裹行內 `程式碼`。帶語法高亮的程式碼區塊： ```typescript interface Post { title: string; date: Date; description?: string; tags?: string[]; draft?: boolean; } function getPublishedPosts(posts: Post[]): Post[] { return posts .filter((post) => !post.draft) .sort((a, b) => b.date.getTime() - a.date.getTime()); } ``` ```css @theme { --font-sans: 'system-ui', sans-serif; --font-serif: 'ui-serif', 'Georgia', serif; } ``` 程式碼區塊現在預設會顯示行號，寫教學、做程式碼審閱，或引用較長範例時都更順手。 ### 程式碼區塊的技巧撰寫包含程式碼的技術文章時，以下技巧能讓你的文章更具可讀性： - **標註語言**：在開啟的三個反引號後指定語言（如 `typescript`、`css`、`python`），啟用語法高亮 - **精簡範例**：只展示與當前討論相關的程式碼，去掉無關的匯入和設定 - **加入註解**：在關鍵行加上註解，幫助讀者理解程式碼意圖 - **前後文說明**：在程式碼區塊之前說明這段程式碼要做什麼，之後解釋關鍵細節 ```python # 使用列表推導式過濾並轉換資料 active_users = [ user.name.upper() # 將名字轉為大寫 for user in all_users # 遍歷所有使用者 if user.is_active # 只保留活躍使用者 ] ``` ## 數學公式行內公式可以直接寫在句子裡，例如 `$E = mc^2$`；較大的公式則適合使用區塊形式： $$ \int_0^1 x^2 \, dx = \frac{1}{3} $$ 這些公式會在建置階段透過 KaTeX 轉成靜態輸出，因此頁面不需要額外載入瀏覽器端數學引擎。 ## Mermaid 圖表如果你要展示流程、順序或結構關係，可以使用 `mermaid` 程式碼區塊： ```mermaid flowchart TD Draft["Markdown 草稿"] --> Build["Astro 建置"] Build --> Html["面向讀者的 HTML 頁面"] Build --> Protocol["面向智慧體的 Markdown 與 JSON"] Html --> Reader["人類讀者"] Protocol --> Agent["AI 智慧體"] ``` 這類圖表會在 Astro 建置時直接轉成 SVG，不需要等到前端再執行 Mermaid。 ## 心智圖如果你想從 Markdown 層級直接生成真正的心智圖，可以使用 `markmap` 程式碼區塊： ```markmap # Aither 寫作 ## Markdown 基礎 ### 標題 ### 表格 ## 豐富內容 ### KaTeX 數學公式 ### Mermaid 圖表 ### Markmap 心智圖 ## 發布介面 ### 面向讀者的頁面 ### 面向智慧體的端點 ``` 它和一般圖表不同：Markmap 會保留內容層級，並提供輕量互動，適合整理綱要、課程內容或複雜主題。 ## 表格 | 功能 | 狀態 | 備註 | |---|---|---| | 深色模式 | 支援 | 淺色 / 深色 / 跟隨系統 | | RSS 訂閱 | 內建 | `/rss.xml` | | 網站地圖 | 自動產生 | 透過 `@astrojs/sitemap` | | SEO | 內建 | Open Graph + 規範連結 | 靠右對齊和置中欄位： | 靠左 | 置中 | 靠右 | |:---|:---:|---:| | 文字 | 文字 | 文字 | | 較長文字 | 較長文字 | 較長文字 | 表格適合展示結構化的比較資訊。但需要注意，Markdown 表格在行動裝置上的展示可能不理想，因此建議表格的欄位數控制在四欄以內，並保持每個儲存格的內容簡短。 ## 分隔線使用 `---` 建立分隔線： --- 分隔線後的內容。分隔線適合用於在文章中標記主題的重大轉換。但不要過度使用——大多數時候，一個新的 `##` 標題就足以表示章節的轉換。 ## 圖片圖片使用標準 Markdown 語法： ```markdown ![替代文字](./image.jpg) ``` 本主題以排版為核心，但在需要時圖片同樣可以正常使用。 ### 圖片使用建議 - **始終提供替代文字**：替代文字不僅有助於無障礙訪問，也是 SEO 的重要因素 - **最佳化圖片大小**：在上傳前壓縮圖片，推薦使用 WebP 格式以獲得更好的壓縮率 - **有意義的圖片名稱**：使用描述性的檔案名如 `astro-project-structure.png`，而非 `screenshot-001.png` ## 寫作風格總結好的 Markdown 寫作不僅是正確使用語法，更是善用這些工具來組織和表達你的想法。記住以下原則： 1. **結構清晰**：使用標題建立明確的層次結構 2. **段落精煉**：每個段落聚焦一個概念 3. **善用列表**：將並列資訊轉化為列表 4. **程式碼配文字**：程式碼區塊前後都要有文字說明 5. **留白呼吸**：適當的空白讓內容更易閱讀

👋 你好，世界（範例）

Thu, 01 Jan 2026 08:00:00 GMT

歡迎來到 Astro-Theme-Aither。這是一個基於一個信念構建的 AI 原生部落格主題：文字本身就很美。統一的無襯線系統字型棧、Apple HIG 排版參數，以及不喧賓奪主的版面。這裡的一切都服務於一個目標——讓你的文字看起來優美、讀起來舒適。 ## 為什麼再造一個部落格主題網路上有無數部落格主題，那為什麼還要再做一個？答案在於優先順序。大多數主題為視覺衝擊力而最佳化——大圖、複雜版面、華麗動畫。這些在展示中很好看，但當讀者真正坐下來閱讀一篇兩千字的文章時，它們只會礙事。 Astro-Theme-Aither 從不同的前提出發：內容就是產品。主題的職責是以它應得的認真態度呈現內容：Apple HIG 正文參數（17px / 1.47 / -0.022em）、充足的留白、讓長文閱讀變得舒適而不是疲憊的垂直節奏。技術決策也延續了這一理念。主題使用 Astro 的島嶼架構——只有互動元件（主題切換、語言切換、語言偵測、行動端導覽）載入 JavaScript。其他一切都是靜態 HTML 和 CSS。沒有版面偏移，沒有載入動畫。頁面載入完畢，你開始閱讀。 ## 開始使用搭建只需幾步： 1. **複製倉庫** — 使用 GitHub 範本按鈕或直接 `git clone` 2. **安裝依賴** — 執行 `pnpm install` 3. **設定網站** — 編輯 `src/config/site.ts` 設定標題、描述和導覽 4. **設定服務** — 複製 `.env.example` 為 `.env`，填入 API 金鑰（GA、Crisp、Giscus） 5. **替換內容** — 用你自己的文章替換 `src/content/posts/` 中的範例 6. **本地開發** — 執行 `pnpm dev` 啟動熱更新開發伺服器 7. **部署** — 推送到 GitHub，CI 工作流程自動部署到 Cloudflare Pages ### 專案結構 ``` src/ ├── components/ # Astro 和 React 元件 ├── config/ # 網站設定（site.ts） ├── content/ # Markdown 文章（按語言組織） ├── i18n/ # 翻譯和語言工具 ├── layouts/ # 頁面版面（Layout.astro） ├── lib/ # 共用工具（posts, formatter, markdown-endpoint） ├── pages/ # 路由頁面（按語言） └── styles/ # 全域 CSS + Tailwind v4 @theme 令牌 ``` ### 寫第一篇文章在 `src/content/posts/zh-hant/` 下建立 `.md` 檔案： ```markdown --- title: 我的第一篇文章 date: "2026-01-15T16:00:00+08:00" category: General description: SEO 和社群預覽的簡短摘要 tags: [話題, 標籤] pinned: false --- 正文從這裡開始。 ``` `title`、`date`、`category` 是必填項。`description` 強烈建議填寫。設定 `pinned: false` 可將文章置頂。多語系內容只需在對應語言目錄（`en/`、`ko/`、`fr/` 等）建立同名檔案。 ## 開箱即用 ### 內容功能 - **RSS 訂閱** — 自動產生 `/rss.xml` - **網站地圖** — 透過 `@astrojs/sitemap` 自動產生 - **SEO 標籤** — 每頁自動產生 Open Graph、Twitter Cards、規範 URL - **JSON-LD** — Article 結構化資料，服務 AI 和搜尋引擎 - **深色模式** — 淺色 / 深色 / 系統切換，View Transitions API 圓形展開動畫 - **i18n** — 多語言支援，自動瀏覽器語言偵測 - **文章置頂** — 將重要文章固定在列表頂部 - **分頁** — 基於檔案的 SSG 分頁，帶頁碼導覽 ### AI 原生功能 - **llms.txt** — AI 智能體內容索引，`/llms.txt` - **llms-full.txt** — AI 全文消費，`/llms-full.txt` - **Markdown 端點** — 任何文章 URL 後加 `.md` 取得純 Markdown - **robots.txt** — 明確歡迎 AI 爬蟲（GPTBot、ClaudeBot、PerplexityBot） ### 開發者功能 - **TypeScript** — 嚴格模式，全型別化 - **Content Collections** — 建構時 frontmatter 型別驗證 - **Tailwind CSS v4** — `@theme` 設計令牌 - **Vitest + Playwright** — 單元測試 + E2E 測試 - **部署** — GitHub Pages（預設）+ Cloudflare Pages（可選） - **Google Analytics** — 可選，環境變數設定 - **Crisp Chat** — 可選線上客服，環境變數設定 - **Giscus 評論** — 可選 GitHub Discussions 評論 ### 效能靜態 HTML + 最小 JavaScript 島嶼 = Lighthouse 四項滿分。 ## 自訂 - **顏色** — 編輯 `src/styles/global.css` 中的 CSS 變數 - **字型** — 修改 Tailwind 主題設定中的字型族 - **導覽** — 更新 `src/config/site.ts` 中的導覽陣列 - **服務** — 在 `.env` 中設定 GA、Crisp、Giscus 環境變數 - **語言** — 在 `src/i18n/` 新增語言，建立對應路由 ## 設計理念主題的視覺簡潔是刻意的，但這不等於工程簡單。底層處理了大量關注點：Apple HIG 排版參數、明暗兩種模式的無障礙色彩對比、View Transitions API 動畫、自動瀏覽器語言偵測、語意化 HTML 結構、AI 友好的內容端點，以及從手機到超寬螢幕的閱讀體驗最佳化。好的設計是隱形的。當你在這個主題上閱讀一篇文章，只是單純享受文字而完全沒注意到主題的存在——這就是設計在按預期工作。祝寫作愉快。