# GitBook 主題架構說明

GitBook 主題提供類似線上文件的閱讀體驗：左側為樹狀導覽、右側顯示文章資訊與公告，內頁則專注呈現 Notion 內容。本文件整理主題的檔案結構、各佈局元件的責任分工，以及常見的使用方式，方便日後整合或擴充。

## 專案結構

```
.
├── 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`：延遲檢查內容載入狀態，若仍無法抓到文章容器便導回首頁。

## 使用說明

1. **在 Next.js 匯入主題佈局**
   ```jsx
   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` 等共享資料。

2. **調整主題設定**
   - 於 `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。

3. **客製樣式與元件**
   - 全域樣式集中在 `style.js`，若需調整字體或底色可於此擴充。
   - 導覽列表、公告、底部工具列等都在 `components/`，可直接替換或新增對應元件。
   - 儀表板相關 UI 放在 `components/ui/dashboard/`，可拆分或擴充模組化功能。

4. **新增頁面佈局**
   - 建議在 `layouts/` 下新增檔案並於 `index.js` 匯出，維持與現有架構一致。
   - 若需要共用狀態，可在新佈局內透過 `useGitBookGlobal` 共享資料，避免重複定義內容。

## 開發提醒

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

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