NextPDF 文件組織結構

重點摘要

NextPDF 手冊依一份固定契約擴充。每個頁面只有一個主題、一種 Diataxis 模式，以及一種頁面類型。每種頁面類型都有一組必備的第二層標題。少數幾份 manifest（清單檔）與 gate，會在手冊擴張時維持結構一致。

本頁說明這套系統的整體結構，讓你的貢獻能放在正確位置。完整且具規範性的契約，包括確切的標題清單、引用規則，以及逐步的 gate 接線程序，記載於內部治理文件 docs/style/expansion-standard.md。請先讀本頁；實際撰寫時，再查閱該文件。

選擇頁面類型

依下列順序套用規則，判斷該新增頁面或擴充既有頁面：

1. 如果這份內容是一個獨立主題，且讀者不會預期它出現在既有頁面，就新增一個頁面。
2. 如果這份內容是在補足既有頁面已經涵蓋的主題，就擴充該頁面。
3. 如果這份內容是深入細節，會讓安裝、quickstart（快速上手）或 task（任務）頁面變得臃腫，就把它移到獨立頁面並連結過去。
4. 其餘情況，擴充既有頁面。

一旦確認頁面應該存在，就設定它的 Diataxis 模式，這會決定頁面類型：

• Tutorial（教學）用來教導學習者，因此採用寫成 recipe（範例）形式的 task guide（任務指南）。
• How-to（操作指引）用來協助有經驗的讀者完成一項任務，因此採用 task guide、server API 指南或 SDK 指南。
• Reference（參考）用來陳述確切事實，因此採用 API reference（API 參考）或 Index（索引）頁面。
• Explanation（說明）用來建立理解，因此採用 developer guide（開發者指南）或 premium 功能指南。

淺白用語是每一種模式的基準，並不是獨立的模式。

頁面類型總覽

手冊契約認可下列幾種類型。只要你的頁面帶有 API 表格，就沿用既有類型；只有在頁面完全沒有 API 表格時，才為它引入一個僅有標籤（label-only）的新類型。

• Index 類型：section-index、api-index、extension-index。
• Reference 類型：api-reference。任何帶有標準 API 表格的頁面都沿用這個類型，包含 server 與 Python SDK 參考。
• Explanation 類型：developer-guide。架構、生命週期與擴充點的說明文字都沿用這個類型，包含 server 與 Python SDK 指南。
• 僅有標籤的新類型：premium-feature-guide 與 task-guide，兩者皆用於沒有 API 表格的頁面。

每個頁面都以 ## At a glance 起頭。每個 api-reference 頁面都帶有共用的 API 表格與 Development notes 標題。必備標題必須剛好是第二層，且各自獨立成行；你可以在它們底下再加更多標題。

撰寫檢查清單

撰寫頁面時，請同時滿足這兩份檢查清單。內部標準會以規範性語氣陳述每一項，並連結其依據的標準。

開發者友善度：

• 從 examples/ 或 tests/Cookbook 取用可執行的範例，並為每個圍欄程式碼區塊加上 title= info string。
• 在 front-matter（前置資料）與開場段落說明先決條件。
• 任何會產生輸出的範例，都要顯示其預期輸出。
• 讓區塊保持可直接複製貼上：每個區塊只使用一種語言，首次使用時寫出完整名稱，結尾不留提示字元。
• 展示預設即安全的程式碼：正式環境範例使用 try/catch，搭配最具體的 NextPDF 例外，且絕不寫空的 catch。
• 以後續延伸閱讀連結收尾，並設定 front-matter 的 related:。

翻譯就緒度：

• 一句話只寫一個概念，避免機器翻譯產生過長且難以斷句的句子。
• 標題與標籤保持簡短，因為多數目標語言譯後會變長。
• 避免使用慣用語。
• 符號名稱、config 鍵、CLI 旗標與例外名稱維持程式碼格式；像 PDF/A-4、PAdES 與 eIDAS 這類標準名稱絕不翻譯。
• 誠實設定 i18n_ready 與 xliff_segments，並以 Unicode NFC 撰寫。

關於語氣、程式碼範例、術語與引用樣式，請遵循內部標準引用且已通過審定的樣式覆寫表。

接上各個 gate

新頁面依一套有先後順序的程序接入：

1. 建立頁面骨架，讓它的 front-matter 符合站台 schema（綱要）。
2. 依該頁面類型所必備的標題撰寫內文。
3. 將一筆 { path, owner, kind, headings[] } 項目加入 docs/manual-contract.json。路徑相對於 src/content/docs，使用正斜線，且不帶開頭斜線、不含 ..。
4. 若是 API 參考，請把該頁面的符號加入 docs/api-coverage-manifest.json；每個符號都必須出現在頁面中，並實際存在於原始碼裡。
5. 只有在頁面來自一個新的來源儲存庫時，才更新 docs/source-manifest.json。
6. 將該頁面以一筆明確的項目加入 astro.config.mjs 中正確的側邊欄群組。
7. 為僅有英文的頁面新增一列語系覆蓋率，並把全部十七個語系欄位都設為 missing。
8. 執行文件 gate、建置，以及效能預算檢查。

站台自有頁面放在 src/content/docs 底下，將 owner 設為 nextpdf-docs，且絕不帶 aggregate（聚合）標記。聚合而來的頁面源自某個來源儲存庫；它們的發布旗標位於來源端的 front-matter，所以你要在那裡編輯，而不是在這裡。

另請參閱

• Integrations：跨多個套件完整示範手冊結構的範例。
• 內部治理文件 docs/style/expansion-standard.md 保存完整契約：每種頁面類型的確切標題清單、引用規則，以及完整的 gate 接線程序。