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

使用說明

在 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 讓後續維護者快速上手。

4.6 KiB Raw Blame History Unescape Escape

GitBook 主題架構說明

專案結構

主要佈局與職責

使用說明

開發提醒

4.6 KiB

Raw Blame History