docs: add comprehensive documentation for operations

This commit introduces a complete set of documentation files
covering various aspects of the project, including environment
setup, quality checks, command references, and architecture.
The documentation is structured to assist developers and
contributors in understanding the project's configuration,
workflow, and best practices.

Additionally, translations for Simplified and Traditional
Chinese have been added to ensure accessibility for a wider
audience. This enhances the overall usability and
maintainability of the project.

Signed-off-by: Bertrand Yuan <github@bertyuan.com>

8 files changed, 394 insertions, 0 deletions

diff --git a/Documentation/source/zh_TW/architecture.rst b/Documentation/source/zh_TW/architecture.rst
new file mode 100644
index 0000000..7c8da41
--- /dev/null
+++ b/Documentation/source/zh_TW/architecture.rst
@@ -0,0 +1,50 @@
+架構
+====
+
+分層視圖
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 34 44
+
+   * - 層
+     - 主要檔案
+     - 職責
+   * - 展示層
+     - ``src/app/(main)``、``src/components``
+     - 呈現公開頁面、路由處理器、共用 UI、富文字和版面。
+   * - 內容存取層
+     - ``src/lib/payload-posts.ts``
+     - 查詢 Payload，並把 CMS 文件正規化為前端可用的資料結構。
+   * - CMS 後台
+     - ``payload.config.ts``、``src/payload``
+     - 定義內容集合並提供後台管理體驗。
+   * - 認證與留言
+     - ``src/server/auth``、``src/server/comments``
+     - 處理 OAuth、Session、留言儲存與留言權限。
+   * - 資料層
+     - ``src/server/db``、``src/migrations``
+     - 管理 Drizzle schema、資料庫連線與應用遷移。
+
+文章讀取流程
+------------
+
+1. ``/posts/[slug]`` 頁面接收文章 slug。
+2. Server Component 呼叫 ``getPostBySlug``。
+3. ``src/lib/payload-posts.ts`` 取得 Payload client 並查詢 ``published`` 狀態的文章。
+4. 原始 Payload 文件被轉換為 ``BlogPost``。
+5. 頁面呈現富文字，並掛載分享、留言等互動。
+
+資料邊界
+--------
+
+Payload 負責編輯內容與媒體中繼資料；應用層負責認證、留言、路由行為、UI 狀態與整合邏輯。新增功能前應先判斷資料歸屬：編輯內容放入 Payload collection；帳號、互動、審核與營運記錄放入 Drizzle schema。
+
+已知風險
+--------
+
+* 正式環境不應使用 Payload secret 預設值。
+* RSS 路徑應統一為 ``/rss.xml``。
+* 標籤統計與搜尋索引目前依賴批次讀取，內容規模變大後應引入快取或資料庫側聚合。
+* 留言角色策略需要更明確的服務端規則與測試覆蓋。
diff --git a/Documentation/source/zh_TW/contributing.rst b/Documentation/source/zh_TW/contributing.rst
new file mode 100644
index 0000000..8b12920
--- /dev/null
+++ b/Documentation/source/zh_TW/contributing.rst
@@ -0,0 +1,38 @@
+貢獻指南
+========
+
+工作流程
+--------
+
+1. 先判斷變更屬於哪個子系統。
+2. 閱讀相鄰實作和測試。
+3. 確認變更是否影響執行期行為、schema、UI、文件或維運流程。
+4. 保持 patch 聚焦，不做無關重構。
+
+提交訊息
+--------
+
+推薦格式：
+
+.. code-block:: text
+
+   <type>(<scope>): <short summary>
+
+常用類型包括 ``build``、``ci``、``docs``、``feat``、``fix``、``perf``、``refactor`` 和 ``test``。摘要使用祈使句、現在式，不以句號結尾。
+
+程式碼完整性
+------------
+
+* 發布版本時優先使用簽名 commit 和簽名 tag。
+* 不提交密鑰、本機資料庫狀態或建置產物。
+* 依賴變更應和原始碼變更一樣認真審查。
+* 非平凡變更應在分支上開發，並通過測試和文件建置。
+
+提交前檢查
+----------
+
+.. code-block:: bash
+
+   pnpm lint
+   pnpm test
+   make -C Documentation html
diff --git a/Documentation/source/zh_TW/frontend.rst b/Documentation/source/zh_TW/frontend.rst
new file mode 100644
index 0000000..b13a747
--- /dev/null
+++ b/Documentation/source/zh_TW/frontend.rst
@@ -0,0 +1,49 @@
+前端
+====
+
+頁面職責
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 34 44
+
+   * - 路由
+     - 主要檔案
+     - 職責
+   * - ``/``
+     - ``src/app/(main)/(home)/page.tsx``
+     - 首頁，包含 Hero、最新文章和 Newsletter CTA。
+   * - ``/posts``
+     - ``src/app/(main)/(home)/posts/page.tsx``
+     - 已發布文章的分頁列表。
+   * - ``/posts/[slug]``
+     - ``src/app/(main)/(home)/posts/[slug]/page.tsx``
+     - 文章詳情、富文字、metadata、分享和留言。
+   * - ``/tags``
+     - ``src/app/(main)/(home)/tags/page.tsx``
+     - 標籤索引與文章數量。
+   * - ``/tags/[tag]``
+     - ``src/app/(main)/(home)/tags/[...slug]/page.tsx``
+     - 按標籤篩選的文章列表。
+   * - ``/login``
+     - ``src/app/(main)/(auth)/login/page.tsx``
+     - OAuth 登入入口。
+
+UI 原則
+-------
+
+* 閱讀優先：排版、行寬和對比度應服務長文閱讀。
+* 導航輕量：文章、標籤、搜尋、主題切換和帳號入口應容易找到。
+* 視覺一致：延續虛線邊框、角標和克制動效。
+* 跨端一致：行動端和桌面端保持相同資訊層級。
+
+元件約定
+--------
+
+新增元件前先檢查 ``src/components/ui`` 和現有頁面元件。共用元件應接收正規化 props，資料取得應放在 Server Component 或 ``src/lib`` helper 中。圖示按鈕必須有明確的可存取名稱。
+
+可存取性
+--------
+
+自訂控制項要保留鍵盤焦點；圖示按鈕和連結需要可讀名稱；淺色和深色主題都要保持足夠對比度；表單必須覆蓋空、載入、成功和錯誤狀態。
diff --git a/Documentation/source/zh_TW/getting-started.rst b/Documentation/source/zh_TW/getting-started.rst
new file mode 100644
index 0000000..5ab7907
--- /dev/null
+++ b/Documentation/source/zh_TW/getting-started.rst
@@ -0,0 +1,72 @@
+快速開始
+========
+
+本頁說明本機開發的基本流程：安裝依賴、準備環境變數、啟動資料庫、執行應用與建置文件。
+
+準備工具
+--------
+
+需要安裝：
+
+* Node.js，版本需符合 Next.js 15；
+* pnpm 10.x；
+* Docker 或 Podman，用於本機 PostgreSQL；
+* Git；
+* 可選：Sphinx，用於本機建置文件。
+
+環境變數
+--------
+
+複製範例檔：
+
+.. code-block:: bash
+
+   cp .env.example .env
+
+環境變數由 ``src/env.js`` 透過 ``@t3-oss/env-nextjs`` 和 ``zod`` 驗證。只做本機 UI 或文件除錯時，可以暫時使用 ``SKIP_ENV_VALIDATION=1``，但正式環境不應依賴它。
+
+資料庫
+------
+
+啟動本機 PostgreSQL：
+
+.. code-block:: bash
+
+   ./start-database.sh
+
+資料庫可用後，按需要執行：
+
+.. code-block:: bash
+
+   pnpm payload:migrate
+   pnpm db:push
+
+執行專案
+--------
+
+.. code-block:: bash
+
+   pnpm install
+   pnpm dev
+
+公開站台預設位於 ``http://localhost:3000``，Payload 後台位於 ``/admin``。
+
+常用檢查
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 50
+
+   * - 命令
+     - 作用
+   * - ``pnpm lint``
+     - 驗證內容連結並執行 Biome lint。
+   * - ``pnpm check``
+     - 執行 Biome 檢查。
+   * - ``pnpm test``
+     - 執行 Vitest 測試。
+   * - ``pnpm build``
+     - 建置 Next.js 應用並產生網站地圖。
+   * - ``make -C Documentation html``
+     - 建置 Sphinx 文件。
diff --git a/Documentation/source/zh_TW/index.rst b/Documentation/source/zh_TW/index.rst
new file mode 100644
index 0000000..1dc6fb7
--- /dev/null
+++ b/Documentation/source/zh_TW/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+Next Blog 文件（繁體中文）
+=============================
+
+這是 Next Blog 文件的繁體中文版本。本文面向維護者、貢獻者與部署人員，說明專案的產品邊界、架構設計、前端約定、維運流程與貢獻規則。
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   getting-started
+   architecture
+   frontend
+   operations
+   contributing
+   reference
diff --git a/Documentation/source/zh_TW/introduction.rst b/Documentation/source/zh_TW/introduction.rst
new file mode 100644
index 0000000..8ca15d4
--- /dev/null
+++ b/Documentation/source/zh_TW/introduction.rst
@@ -0,0 +1,46 @@
+專案介紹
+========
+
+Next Blog 是一個以閱讀體驗為核心的全端部落格平台。它使用 Next.js App Router 建置公開站台，使用 Payload CMS 管理內容，並透過 PostgreSQL、Drizzle ORM、better-auth 與 Fuma Comments 提供認證、留言與應用資料能力。
+
+產品範圍
+--------
+
+目前專案聚焦於以下能力：
+
+* 透過 Payload CMS 建立、編輯、發布文章；
+* 呈現首頁、文章列表、文章詳情、標籤頁與個人頁面；
+* 透過 Google 與 GitHub OAuth 登入；
+* 為登入使用者提供留言功能；
+* 輸出搜尋索引、RSS、網站地圖、JSON-LD 與 Open Graph 圖片；
+* 提供 Newsletter 表單與 React Email 範本。
+
+這個專案不是通用社群 CMS，而是一個受控的個人發布系統：公開側重閱讀，後台側重內容管理。
+
+核心角色
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 34 36
+
+   * - 角色
+     - 目標
+     - 主要入口
+   * - 訪客
+     - 瀏覽和閱讀內容。
+     - ``/``、``/posts``、``/posts/[slug]``、``/tags``
+   * - 回訪讀者
+     - 透過標籤篩選內容並使用訂閱入口。
+     - ``/tags/[tag]``、``/rss.xml``
+   * - 登入使用者
+     - 發表留言與使用帳號相關操作。
+     - ``/login``、``/posts/[slug]``
+   * - 內容管理員
+     - 維護、排程與發布內容。
+     - ``/admin``
+
+文件定位
+--------
+
+``Documentation/source`` 是本專案正式的 Sphinx 文件來源目錄。``docs/`` 中的 Markdown 檔案可以作為調研或草稿材料，但穩定的工程文件應整理為 reStructuredText 後進入本目錄。
diff --git a/Documentation/source/zh_TW/operations.rst b/Documentation/source/zh_TW/operations.rst
new file mode 100644
index 0000000..a513a10
--- /dev/null
+++ b/Documentation/source/zh_TW/operations.rst
@@ -0,0 +1,65 @@
+維運
+====
+
+環境設定
+--------
+
+關鍵環境變數在 ``src/env.js`` 中驗證：
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 44
+
+   * - 變數
+     - 用途
+   * - ``DATABASE_URL``
+     - PostgreSQL 連線字串。
+   * - ``RESEND_API_KEY``
+     - Resend API key。
+   * - ``RESEND_AUDIENCE_ID``
+     - Resend audience ID。
+   * - ``EMAIL_FROM``
+     - 寄件信箱。
+   * - ``BETTER_AUTH_SECRET``
+     - better-auth secret，正式環境必填。
+   * - ``GOOGLE_CLIENT_ID`` / ``GOOGLE_CLIENT_SECRET``
+     - Google OAuth 憑證。
+   * - ``GITHUB_CLIENT_ID`` / ``GITHUB_CLIENT_SECRET``
+     - GitHub OAuth 憑證。
+
+資料庫流程
+----------
+
+Payload collection 變更：
+
+.. code-block:: bash
+
+   pnpm payload:migrate:create
+   pnpm payload:migrate
+   pnpm payload:generate
+
+應用 schema 變更：
+
+.. code-block:: bash
+
+   pnpm db:generate
+   pnpm db:migrate
+
+品質檢查
+--------
+
+.. code-block:: bash
+
+   pnpm lint
+   pnpm check
+   pnpm test
+   pnpm build
+
+文件建置
+--------
+
+.. code-block:: bash
+
+   make -C Documentation html
+
+產生的 ``Documentation/build`` 不應提交。
diff --git a/Documentation/source/zh_TW/reference.rst b/Documentation/source/zh_TW/reference.rst
new file mode 100644
index 0000000..4da4c12
--- /dev/null
+++ b/Documentation/source/zh_TW/reference.rst
@@ -0,0 +1,57 @@
+參考
+====
+
+常用命令
+--------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 26 50
+
+   * - 命令
+     - 說明
+   * - ``pnpm dev``
+     - 啟動開發伺服器。
+   * - ``pnpm build``
+     - 建置正式應用。
+   * - ``pnpm lint``
+     - 執行內容連結驗證和 Biome lint。
+   * - ``pnpm test``
+     - 執行測試。
+   * - ``pnpm db:migrate``
+     - 套用 Drizzle 遷移。
+   * - ``pnpm payload:generate``
+     - 產生 Payload TypeScript 型別。
+
+路由
+----
+
+.. code-block:: text
+
+   /
+   /posts
+   /posts/[slug]
+   /tags
+   /tags/[tag]
+   /about
+   /login
+   /admin
+   /api/auth/[...all]
+   /api/comments/[...comment]
+   /api/search
+   /rss.xml
+
+術語
+----
+
+Payload
+   管理文章、使用者、媒體和後台介面的 CMS。
+
+Drizzle
+   管理應用自有資料庫表的 TypeScript ORM。
+
+better-auth
+   提供 OAuth 和 Session 能力的認證庫。
+
+BlogPost
+   ``src/lib/payload-posts.ts`` 回傳的前端正規化文章結構。