83 lines
4.6 KiB
Markdown
83 lines
4.6 KiB
Markdown
# 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 讓後續維護者快速上手。
|