個人 GitHub Page 建置

2026-03-27 （更新：2026-04-03） · 6 分鐘閱讀時間 Live Site ↗

動機

工作和學習過程中累積了不少筆記與研究資料，一直散落在各種工具和資料夾裡。希望有一個集中的平台來：

整理知識 — 將技術筆記、工具用法系統化歸類
記錄研究 — 追蹤正在關注的技術趨勢與分析
展示成果 — 呈現完成的專案，作為個人作品集

最終選擇以靜態網站的形式實現，部署在 GitHub Pages 上，不需要後端伺服器、零維運成本。

功能概覽

分類瀏覽

網站內容分為三大類，各自獨立的列表頁面與文章頁面：

分類	路徑	用途
研究	`/research`	技術趨勢追蹤、分析報告
知識庫	`/knowledge`	技術筆記、工具記錄、學習整理
作品集	`/portfolio`	專案成果展示

每篇文章支援 Frontmatter 標籤，可透過 /tags 頁面交叉瀏覽。

系列文章

多篇文章可組成系列，支援跨分類（如研究 + 知識庫混合系列）。系列功能包含：

系列索引頁 (/series) — 列出所有系列，依最新更新排序
系列詳情頁 (/series/[id]) — 顯示系列內所有文章
文章內導航 — SeriesNav 元件顯示完整文章清單（超過 5 篇自動收合）+ 上/下一篇連結
浮動導航按鈕 — 固定在畫面右側的 ← ≡ → 按鈕，隨時切換系列文章
系列可同時包含公開與私人文章，所有權由第一篇文章（最小 seriesOrder）所屬集合決定

全站搜尋

使用 Pagefind 實現純靜態搜尋，在建置時產生索引。搜尋範圍僅包含文章內容，不包含首頁、分類頁等非文章頁面。

私人空間

部分內容需要密碼保護。使用 CryptoJS AES 在建置時加密文章正文，瀏覽時由客戶端解密：

支援全域密碼（所有私人文章共用）與單篇密碼（個別文章獨立密碼）
文章標題與描述公開顯示於列表，僅正文加密
密碼存於 sessionStorage，關閉分頁即失效
私人頁面不進入搜尋索引與 sitemap

私人區域完整鏡像公開網站結構，擁有獨立的分類列表、系列頁面、標籤頁面與搜尋功能：

路徑	功能
`/private/`	密碼入口 + 登入後總覽（分類捷徑、近期文章）
`/private/research/`	私人研究文章列表
`/private/knowledge/`	私人知識庫文章列表
`/private/portfolio/`	私人作品集列表
`/private/series/`	私人系列索引
`/private/tags/`	私人標籤頁面
`/private/search/`	私人搜尋（基於 metadata 的客戶端搜尋）

由於加密文章無法被 Pagefind 索引，私人搜尋採用建置時產生的 JSON metadata（標題 + 描述 + 標籤），搭配分類篩選頁籤進行即時過濾。

Unlisted 文章

文章可設為 unlisted: true，從分類與標籤列表中隱藏，但保留頁面產生、搜尋索引與系列導航。適用於系列中的子章節 — 不適合單獨出現在列表中，但作為系列的一部分仍可存取。

中英語系切換

透過 data-i18n 屬性系統實現客戶端即時切換，涵蓋導覽列、按鈕文字、頁面標題、placeholder 等 40+ 組翻譯鍵。切換時瀏覽器分頁標題同步更新，選擇以 localStorage 記憶。

主題切換

提供亮色（櫻粉）與暗色（夜櫻）兩套主題，以 CSS custom properties 實現。透過 <script is:inline> 在 HTML 解析前套用已儲存的主題偏好，避免畫面閃爍（FOUC）。

Mermaid 圖表

文章中可使用 Mermaid fenced code block，支援流程圖、序列圖、甘特圖、心智圖等。圖表在客戶端渲染，自動適配亮色 / 暗色主題。

HTML 報告嵌入

可將獨立設計的 HTML 文件透過 iframe 嵌入文章，保留原始樣式，並自動偵測內容高度調整 iframe 大小。

閱讀體驗

閱讀時間估計 — 根據 CJK 字數（400 字/分鐘）與拉丁字數（200 詞/分鐘）自動估算
閱讀進度條 — 文章頁面頂部的捲動進度指示條
Code 複製按鈕 — 程式碼區塊右上角一鍵複製，hover 時顯示
語法高亮（私人頁面） — 使用 highlight.js 在客戶端做語法高亮，配色匹配 GitHub Light/Dark 主題
文章歸檔 — /archive 頁面，所有公開文章依年份分組的時間線瀏覽
麵包屑導航 — 顯示頁面層級路徑（如首頁 / 研究 / 文章標題）
列印友善 — @media print 樣式，隱藏導覽元素、顯示連結 URL、避免跨頁斷裂
自訂 404 頁面 — 符合網站主題的錯誤頁面，提供返回首頁連結

其他功能

作者標示 — 可選 author 欄位，在文章標頭與卡片上顯示作者資訊
漸進式載入 — 列表頁面文章過多時，顯示「顯示更多」按鈕逐步載入
導航高亮 — 當前頁面對應的導覽列連結自動高亮
私人頁面強調色 — 所有私人頁面頂部顯示 sticky 色條，視覺區分公開與私人區域

技術選型

graph LR
    A[Astro] -->|SSG 建置| B[靜態 HTML]
    B --> C[GitHub Pages]
    A ---|樣式| D[Tailwind CSS v4]
    A ---|搜尋索引| E[Pagefind]
    A ---|加密| F[CryptoJS]
    A ---|圖表| G[Mermaid]
    A ---|SEO| H[Sitemap + OG Tags]

項目	技術	選用理由
Framework	Astro 6	內容優先、零 JS 預設、Content Collections 管理 Markdown
Styling	Tailwind CSS v4	Utility-first、CSS custom properties 整合主題系統
Search	Pagefind	建置時產生索引、無需後端、檔案小
Encryption	CryptoJS (AES)	純前端加密解密、不依賴伺服器
Diagrams	Mermaid	Markdown 內直接撰寫、支援多種圖表類型
SEO	@astrojs/sitemap	自動產生 sitemap.xml、搭配 OG/Twitter Card meta
Deploy	GitHub Actions	Push 到 main 自動建置部署、零成本
Package Manager	pnpm	快速安裝、節省磁碟空間

網站架構

graph TD
    subgraph Content["內容來源"]
        RC[research 文章]
        KC[knowledge 文章]
        PC[portfolio 文章]
        PRC[private 文章]
    end

    subgraph Layout["版型層"]
        AL[ArticleLayout]
        PL[PrivateLayout]
        BL[BaseLayout]
    end

    subgraph Pages["頁面"]
        HP[首頁]
        LP[分類列表頁]
        SP[系列頁面]
        TP[標籤頁面]
        SR[搜尋頁面]
        PV[私人頁面]
    end

    RC --> AL
    KC --> AL
    PC --> AL
    AL --> BL
    PRC -->|AES 加密| PV
    PV --> PL
    PL --> BL
    HP --> BL
    LP --> BL
    SP --> BL
    TP --> BL
    SR --> BL

設計細節

版型結構

BaseLayout — 核心版型，包含 Header（導覽列、語系/主題切換）、Footer、Mermaid 初始化、i18n 標籤系統
ArticleLayout — 文章版型，繼承 BaseLayout，加入 TOC 側欄、浮動導航按鈕、系列導航元件、heading 高亮追蹤、閱讀進度條、麵包屑導航
PrivateLayout — 私人區域版型，繼承 BaseLayout，加入 session 驗證、私人導覽列、登出功能、強調色頂部條

導覽列與行動版選單均支援 Astro named slots，讓私人頁面可覆寫為專屬導覽內容。

主題系統

以 data-theme 屬性搭配 CSS custom properties，在 :root 與 [data-theme="dark"] 分別定義色票：

亮色主題以柔和的櫻粉色調為基底
暗色主題以深紫色調呈現夜櫻風格
Tailwind 的 dark variant 設定為讀取 data-theme 而非 prefers-color-scheme
各分類有專屬卡片色系：研究（天空藍）、知識（嫩葉綠）、作品（紫藤紫）

響應式設計

桌面版：導覽列水平排列 + TOC 側欄 + 浮動導航按鈕
行動版：漢堡選單 + TOC 隱藏、內容全寬顯示

部署流程

sequenceDiagram
    participant D as Developer
    participant G as GitHub
    participant A as GitHub Actions
    participant P as GitHub Pages

    D->>G: git push main
    G->>A: 觸發 workflow
    A->>A: pnpm install
    A->>A: pnpm build（含 Pagefind 索引）
    A->>P: 部署 dist/ 到 Pages
    P-->>D: 網站上線

Push 到 main 分支即觸發 GitHub Actions 自動建置與部署，完整流程約需 1–2 分鐘。

小結

這個網站從規劃到上線的過程中，涵蓋了靜態網站開發的多個面向：內容管理、系列文章系統、搜尋整合、客戶端加密、多語系、主題系統、SEO 優化、CI/CD 部署。作為個人知識管理平台，未來將持續新增研究記錄與技術筆記。

動機