.
├── components/                 # 主題專用的視覺元件與工具（導覽清單、目錄抽屜、底部工具列…）
│   └── ui/dashboard/           # 儀表板頁面使用的額外組件
├── config.js                   # 主題設定（首頁導向、導覽開關、Widget 等）
├── index.js                    # 統一對外匯出的入口
├── layouts/                    # 依頁面職責拆分的佈局元件
│   ├── ArchiveLayout.jsx       # 歸檔頁
│   ├── AuthLayouts.jsx         # 登入／註冊頁
│   ├── BaseLayout.jsx          # 主架構：左右欄、行動裝置導覽、Loading 與廣告
│   ├── ListLayouts.jsx         # 首頁／文章列表／搜尋結果與儀表板
│   ├── NotFoundLayout.jsx      # 404 頁面
│   ├── SlugLayout.jsx          # 文章詳情頁
│   └── TaxonomyLayouts.jsx     # 分類與標籤索引
├── style.js                    # 只對 GitBook 主題生效的全域樣式
└── README.md                   # 本說明文件

主要佈局與職責

LayoutBase：包住所有內容的骨架，負責導覽抽屜、公告、目錄、回頂按鈕與 Loading 遮罩，並透過 useGitBookGlobal 共享狀態（搜尋、TOC、導覽列表）。
LayoutIndex：讀取 config.js 的 GITBOOK_INDEX_PAGE，在前端重新導向至指定文章，若找不到對應 slug 會注入錯誤提示。
LayoutPostList / LayoutSearch：此主題採左側導覽管理文章，頁面本身僅回傳空節點，確保路由存在。
LayoutArchive：使用 BlogArchiveItem 依年份渲染歸檔清單。
LayoutSlug：顯示單篇內容，處理加密文章、Meta 標題、分類／標籤、前後篇與留言，並在內容缺漏時自動導回 404。
LayoutCategoryIndex / LayoutTagIndex：輸出分類與標籤的索引列表，套用統一樣式與 locale 文案。
LayoutSignIn / LayoutSignUp：Clerk 驗證元件容器，會先顯示官方預設表單，再渲染 Notion 內容。
LayoutDashboard：搭配 components/ui/dashboard/* 顯示自訂儀表板。
Layout404：延遲檢查內容載入狀態，若仍無法抓到文章容器便導回首頁。

使用說明

在 Next.js 匯入主題佈局

import {
  LayoutBase,
  LayoutSlug,
  LayoutIndex,
  LayoutCategoryIndex
} from '@/themes/gitbook'

const Post = props => (
  <LayoutBase {...props}>
    <LayoutSlug {...props} />
  </LayoutBase>
)

export default Post

LayoutBase 處理共同框架；內層依頁面需求替換為 LayoutIndex、LayoutArchive、LayoutCategoryIndex…等。
需要使用 TOC 或導覽狀態時，可透過 useGitBookGlobal() 取得 searchModal、tocVisible 等共享資料。

調整主題設定
- 於 config.js 修改選項，或透過環境變數覆寫，例如 NEXT_PUBLIC_GITBOOK_INDEX_PAGE、NEXT_PUBLIC_GITBOOK_AUTO_SORT。
- 常用開關：
  - GITBOOK_AUTO_SORT：自動依分類整理導覽。
  - GITBOOK_EXCLUSIVE_COLLAPSE：導覽是否一次只展開一組。
  - GITBOOK_FOLDER_HOVER_EXPAND：滑鼠懸停是否自動展開導覽資料夾。
  - GITBOOK_WIDGET_REVOLVER_MAPS / GITBOOK_WIDGET_TO_TOP：控制右側 Widget。
客製樣式與元件
- 全域樣式集中在 style.js，若需調整字體或底色可於此擴充。
- 導覽列表、公告、底部工具列等都在 components/，可直接替換或新增對應元件。
- 儀表板相關 UI 放在 components/ui/dashboard/，可拆分或擴充模組化功能。
新增頁面佈局
- 建議在 layouts/ 下新增檔案並於 index.js 匯出，維持與現有架構一致。
- 若需要共用狀態，可在新佈局內透過 useGitBookGlobal 共享資料，避免重複定義內容。

開發提醒

本主題內的註解與靜態文字皆已改為臺灣常用的繁體中文，若新增內容請維持相同用語風格。
導覽列表仰賴 allNavPages，若調整資料格式請同步更新 NavPostList 相關邏輯。
重新導向或動態載入元件時請注意瀏覽器環境判斷（isBrowser），避免在 SSR 階段觸發錯誤。

如需額外備註，可持續更新本 README 讓後續維護者快速上手。

README.md Unescape Escape

GitBook 主題架構說明

專案結構

主要佈局與職責

使用說明

開發提醒

README.md