本文整理 GitHub 專案 saicaca/fuwari。Fuwari 是一個以 Astro 建立的靜態部落格模板，目標是讓使用者以 Markdown 管理文章，再部署到 Vercel、Netlify、GitHub Pages 等靜態託管平台。本文以目前可見的 repository README、設定檔、套件清單及主要 source 結構為基礎，版本參考 commit：6d39b0d。

一、專案定位

Fuwari 不是帶後台、資料庫及會員系統的 CMS，而是「內容檔案 + 建置流程 + 靜態輸出」的部落格起始模板。文章放在 src/content/posts/，以 Markdown 或 MDX 撰寫；Astro 在 build 階段把內容轉成 HTML，Pagefind 再建立搜尋索引。這種設計適合個人部落格、技術筆記、文件站及低維護成本的內容網站。

它的主要取捨很清楚：犧牲即時後台編輯、資料庫查詢及動態權限，換取部署簡單、運行成本低、頁面速度快、版本控制自然及容易透過 Git 回溯。

二、技術棧與責任分工

  • Astro 5：負責路由、內容頁面、靜態建置及元件整合；文章在建置時生成，適合內容為主的網站。
  • Svelte：用於互動元件，例如搜尋、深色模式、封存面板及顯示設定；不是整個網站都變成大型客戶端 SPA。
  • Tailwind CSS：提供實用類別、響應式版面及主題樣式，並配合 PostCSS nesting。
  • TypeScript：為設定、內容 schema、工具函式及元件提供型別檢查。
  • Pagefind：在 production build 後掃描 dist/，建立靜態搜尋索引；開發模式使用假搜尋結果，不能把 dev 搜尋行為當成 production 搜尋。
  • Vercel／Netlify／GitHub Pages：README 提供多種靜態部署方向；真正部署前須按平台調整 astro.config.mjs 的 site、base 及 trailing slash。

三、內容模型：Markdown 加 Zod schema

src/content/config.ts 使用 Astro Content Collections 的 defineCollection 及 Zod schema。文章 frontmatter 主要包括：

TEXT
---
title: My First Blog Post
published: 2023-09-09
description: A short description
image: ./cover.jpg
tags: [Astro, Blog]
category: Front-end
draft: false
lang: zh_TW
---

schema 對 title 及 published 作必要驗證；updated、draft、description、image、tags、category 及 lang 是可選欄位，並提供預設值。這個層次很重要：文章不是任意 HTML，而是先經過資料形狀驗證，建置時較早暴露日期格式、型別或缺漏問題。

schema 還包括 prevTitle、prevSlug、nextTitle 及 nextSlug 等內部欄位，用於文章前後導覽。這表示內容頁除了正文，也把導覽所需的資料視為明確模型的一部分。

四、Markdown 處理鏈

Fuwari 的 astro.config.mjs 顯示了一條相當完整的 Markdown pipeline：

  1. remarkMath：處理數學語法。
  2. remarkReadingTime：計算閱讀時間。
  3. remarkExcerpt：從正文取得摘要或 excerpt。
  4. remark-directive：支援自訂 directive 語法。
  5. GitHub admonition 轉換：讓 note、tip、warning、caution 等提示區塊能在 Markdown 中使用。
  6. remarkSectionize：按標題把內容整理成 section 結構。
  7. rehype-slug 與 autolink：為標題產生 anchor，方便目錄與段落連結。
  8. rehype-katex：將數學內容輸出成 KaTeX。
  9. rehype-components：把 GitHub repo card 及 admonition 等自訂元素渲染成元件。

這條鏈的優點是 Markdown 能表達技術文章常用的公式、提示框、程式碼及 GitHub 卡片；代價是 plugin 之間有順序依賴，升級 Astro、remark 或 rehype 套件時，應使用 pnpm check 及 production build 回歸測試。

五、前端與互動設計

靜態優先，互動局部化

搜尋、深色模式、Archive panel 及 Display settings 由 Svelte 元件提供互動；文章本身仍以 Astro 靜態頁面為主。這種 island-style 思路能避免整個部落格載入大型前端 runtime，適合閱讀型網站。

頁面轉場

專案使用 @swup/astro，啟用快取、預載、平滑滾動及 accessibility，並指定 main 與 #toc 為轉換容器。它能讓靜態頁面有較流暢的閱讀體驗，但轉場與第三方互動腳本整合時要注意生命週期，避免頁面切換後事件重複註冊或元件狀態殘留。

主題設定

src/config.ts 集中定義網站標題、副標題、語言、主題 hue、banner、目錄深度、favicon、導覽列、個人頭像及社交連結。使用者通常不需要改動頁面元件，就能完成品牌化；主題顏色可由 hue 控制，亦可設為 fixed 以隱藏訪客選色器。

六、程式碼與語法展示能力

專案整合 Expressive Code，並啟用可折疊區段、行號、語言標籤及自訂複製按鈕。這對技術部落格特別有用：程式碼不只是普通 pre 文字，而是可顯示語言、行號、diff 或終端風格的閱讀元件。

設定還把 code background、圓角、字型、行距及 terminal/editor frame 顏色連到 CSS variables，讓主題調整不必逐個重寫插件樣式。要注意的是，README 指出目前 code theme 偏向深色背景；若要完整支援淺色 code block，需額外檢查 Expressive Code theme 與 CSS override。

七、常用工作流程

TEXT
pnpm install
pnpm new-post my-post
pnpm dev
pnpm check
pnpm build
pnpm preview

scripts/new-post.js 會在 src/content/posts/ 建立 Markdown 檔案，填入標題、日期、描述、圖片、標籤、分類、draft 及語言欄位。建議流程是先用 pnpm new-post 建立草稿，再按 schema 補齊 frontmatter；寫完後先跑 pnpm check，最後用 pnpm build 驗證 Pagefind 與 production 輸出。

專案要求 Node.js 20 以上及 pnpm 9 以上，package manager 鎖定為 pnpm@9.14.4。preinstall 透過 only-allow pnpm 阻止使用 npm 或 yarn 安裝，能減少 lockfile 不一致，但新加入專案的協作者應先安裝正確 pnpm 版本。

八、優點

  • 部署簡單：輸出是靜態檔案，沒有必須長期維護的應用伺服器及資料庫。
  • 內容可版本化：文章、設定及主題改動都能以 Git diff 審查及回滾。
  • 內容 schema 清楚：Zod 驗證能在 build 階段提早發現 frontmatter 問題。
  • 技術文章友善：數學、admonition、GitHub card、程式碼高亮、目錄及 RSS 都已整合。
  • 互動有節制：以 Astro 靜態內容為主，只在搜尋、設定及主題等位置引入 Svelte。
  • 自訂入口集中：大部分個人化設定集中在 src/config.ts，新手較容易找到改動位置。

九、限制與風險

  • 沒有內建 CMS：非技術作者不能像 WordPress 一樣直接登入後台編輯；需要 Git、Markdown 及部署流程。
  • 建置即更新：新增文章通常要觸發 CI／部署，沒有資料庫即時發佈的模型。
  • Pagefind 只在 production 可完整驗證：dev 模式的搜尋是 mock data，不能用它確認正式索引已正確建立。
  • 套件鏈較長：Astro、Svelte、Tailwind、Swup、Expressive Code、remark/rehype 及 icon 套件共同升級時，回歸測試不可省略。
  • 第三方內容需審核：GitHub cards、外部圖片、社交連結及自訂 Markdown directive 可能引入外部請求或不適合內容。
  • 靜態站不等於沒有安全問題：部署 token、GitHub Actions secret、外部表單及 analytics 仍需按最小權限管理。

十、適合誰使用

Fuwari 適合熟悉或願意學習 Git 與 Markdown 的個人作者、工程師、設計師、研究筆記作者及小型文件團隊。它特別適合文章主要由檔案組成、更新頻率中等、不需要細緻會員權限及後台工作流的網站。

如果需求包括多人同時編輯、草稿審批、角色權限、留言管理、會員登入、即時資料、商店或非技術團隊大量日更，Fuwari 需要搭配 Headless CMS、Git-based CMS 或另外開發動態服務；不能只靠模板本身解決。

十一、實作建議

  1. 先複製模板並立即修改 src/config.ts 的 site title、subtitle、lang、profile 及 GitHub link，避免把 Demo 設定直接上線。
  2. 建立一篇測試文章，驗證日期、圖片、標籤、分類、draft、目錄、數學、admonition、GitHub card 及程式碼區塊。
  3. 在本地完成 pnpm check 與 pnpm build，再用 pnpm preview 檢查正式輸出及 Pagefind 搜尋。
  4. 把 content、config、public assets 及 deployment config 分開審查，避免把大圖片、秘密 token 或測試資料提交到 Git。
  5. 若使用 GitHub Pages，特別確認 site、base、trailing slash、sitemap 及 asset path；部署子路徑時不能假設 root domain 行為完全相同。
  6. 建立依賴更新節奏，升級後至少測試文章頁、首頁、搜尋、RSS、目錄、深色模式及手機版。

結論

Fuwari 的核心價值不是提供一個不可改的外觀，而是把 Astro 靜態部落格常見的內容模型、主題設定、Markdown 擴充、搜尋、RSS、程式碼展示及部署入口整理成可 fork 的起點。它用檔案與 Git 取代資料庫及後台，換來清晰、快速、低成本及可回溯；但也要求作者接受 Markdown、Node/pnpm、build 與部署這套工作方式。

如果你的首要目標是「一個漂亮、快速、可長期維護的個人技術部落格」，Fuwari 是相當完整的起步方案；如果你的首要目標是「多人內容營運平台」，應先補 CMS、權限及審批層，而不是只調整 CSS。

來源

GitHub：saicaca/fuwari｜目前分析 commit：6d39b0dec41282e7852e23e032998a5789abee28。專案採 MIT License；使用時仍應遵守其授權及第三方套件授權條款。