在建構面向現代開發者的技術文件時，越來越多工程與文件團隊選擇 Mintlify。與維護繁瑣的客製化前端路由或手寫 CSS 樣式不同，Mintlify 採用「文件即程式碼」（Docs-as-Code）理念，將整套網站的外觀風格與資訊架構收斂至根目錄下的單一設定檔：docs.json（早期版本為 mint.json）。團隊無需介入底層渲染引擎，即可在受版本控制的 JSON 檔案中宣告全域視覺資產、側邊欄多層級架構、可折疊分組以及頂部跨業務網域標籤頁。
本文深入解析技術文件團隊如何利用 docs.json 完成品牌外觀客製、側邊欄資訊層級組織與多產品標籤分組搭建，協助團隊快速交付具備企業級體驗的開發者入口網站。
一、核心配置架構：docs.json 規範與工程解析
Mintlify 網站的全部全域行為與導覽層級均由專案根目錄下的 docs.json 主導。最新的 docs.json 規範將版面主題、導覽拓撲、API 互動控制台及第三方分析工具整合進統一的資料結構中。
Schema 驗證與檔案定址約定
在工程協作中，建議在 docs.json 開頭引入官方 Schema，以便團隊成員在 VS Code 等主流編輯器中獲得自動補全、即時語法驗證與欄位提示說明：
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme 開發者中心",
"theme": "maple"
}
技術團隊在組織檔案結構時需掌握以下原則：
- 無副檔名路徑宣告：在
navigation陣列中宣告的頁面路徑，均相對於程式碼儲存庫根目錄，且省略.mdx或.md副檔名。例如"pages": ["getting-started/quickstart"]對應實體檔案getting-started/quickstart.mdx。 - Git 原生審查流程：導覽結構的調整、頁面的增刪以及品牌配色的微調均以純文字 JSON 儲存在儲存庫中，可透過 Pull Request 走標準的程式碼審查與預覽部署流程。
- 視覺化編輯器雙向同步：對於習慣所見即所得介面的非技術寫作人員，在 Mintlify Web 編輯器中拖曳調整頁面與分組順序時，系統會自動將變更生成 Git Commit 回寫至
docs.json。
二、配置自訂品牌外觀與視覺規範
Mintlify 讓團隊在不撰寫繁雜 CSS 的前提下，輕鬆貼合企業的品牌設計系統（Design System）。品牌屬性主要配置在 docs.json 的頂層欄位中。
版面主題（Theme）
Mintlify 提供了多款面向不同業務情境的內建版面主題，透過 theme 欄位一鍵切換：
mint：經典文件佈局，適合常規開源軟體和輕量級工具庫。maple：現代感強、視覺層次清爽，是 AI 原生產品和 SaaS 平台的主流選擇。palm：排版嚴謹、資訊密度適中，適合金融科技及大型企業級複雜平台。willow：極簡閱讀風格，減少周邊雜訊干擾。- 此外亦支援
linden、almond、aspen、sequoia與luma。
品牌配色與深色模式自適應
在 colors 物件中定義品牌主色與深色模式適配色，Mintlify 會自動處理元件的高對比度渲染：
"colors": {
"primary": "#2563EB",
"light": "#60A5FA",
"dark": "#1D4ED8"
}
primary：核心品牌色，用於淺色模式下的文字強調、啟用狀態、主要操作按鈕和連結。light：在深色背景下用於重點醒目與高亮狀態，確保夜間閱讀時的色彩對比度。dark：用於跨模式的滑鼠懸停（Hover）狀態與次級互動按鈕。
雙模式 Logo 與 Favicon
為保證在淺色與深色背景下均呈現清晰銳利的品牌圖標，建議分別指定向量 SVG 資源，並配置統一跳轉連結：
"logo": {
"light": "/images/logo-light.svg",
"dark": "/images/logo-dark.svg",
"href": "https://acme.com"
},
"favicon": "/images/favicon.svg"
若未提供 logo.href，點擊 Logo 預設導向文件首頁。
字型、圖示庫與背景裝飾
- 排版字型：在
fonts中可直接指定 Google Fonts 字型家族名稱（如"Inter"或"Fira Code"），系統會自動非同步載入；亦可配置fonts.heading與fonts.body分別指定標題和內文字型，或指向自行代管的.woff2格式檔案。 - 圖示生態整合：Mintlify 原生支援 Font Awesome、Lucide 與 Tabler 圖示庫。透過
"icons": { "library": "lucide" }宣告後，即可在導覽節點直接使用"book-open"等圖示名稱，同時支援內嵌 SVG 與 Emoji。 - 背景修飾：透過
"background": { "decoration": "gradient" }或"grid"可為頁面注入細微漸層或網格質感，增強現代開發質感。 - 強制外觀模式：若產品規範要求統一深色外觀，可配置
"appearance": { "default": "dark", "strict": true }鎖定深色並隱藏前端模式切換開關。
三、建構側邊導覽欄：分組、巢狀與目錄落地頁
側邊導覽欄承擔著引導讀者循序漸進閱讀技術文件的核心任務。在 Mintlify 中，側邊欄完全由 navigation 物件中的邏輯樹定義。
基礎分組與帶圖示分組
分組（Group）用於將功能相關或閱讀時序相近的頁面聚合在一起。每個分組必須包含 group 標題與 pages 頁面清單：
"navigation": {
"groups": [
{
"group": "快速入門",
"icon": "rocket",
"pages": [
"quickstart",
"installation",
"authentication"
]
}
]
}
多層巢狀與預設折疊控制
隨著系統複雜度上升，單一扁平清單會造成嚴重的認知負擔。Mintlify 支援將子分組直接巢狀置入父級分組的 pages 陣列中。
為了防止側邊欄過於冗長，團隊可透過 expanded 布林值控制巢狀分組的初始折疊狀態：
{
"group": "核心架構",
"icon": "cpu",
"pages": [
"architecture/overview",
{
"group": "資料儲存層",
"icon": "database",
"expanded": false,
"pages": [
"architecture/storage/relational",
"architecture/storage/caching"
]
},
{
"group": "安全與合規",
"icon": "shield-check",
"tag": "NEW",
"pages": [
"architecture/security/rbac",
"architecture/security/encryption"
]
}
]
}
提示：頂層主分組在側邊欄中始終保持展開，expanded 屬性專門用於控制巢狀層級中的子分組展開或收合。
可點擊分組標題與根頁面（root）
在預設行為下，點擊側邊欄中的分組名稱僅觸發其子頁面的展開或收折。但許多情境下，團隊希望分組標題本身就是一篇系統綜述或概念落地頁。
透過配置 root 屬性即可將分組標題直接綁定至對應 MDX 頁面：
{
"group": "API 介面參考",
"root": "api/overview",
"pages": [
"api/users",
"api/billing",
"api/webhooks"
]
}
配置後，讀者在側邊欄點擊「API 介面參考」，右側立即載入 api/overview.mdx，同時側邊欄聯動呈現其下轄的所有端點子頁面。
自動化目錄索引（directory）
為了讓概覽落地頁具備清晰的導流能力，Mintlify 為帶有 root 屬性的分組提供了 directory 自動化索引佈局，平台會在落地頁的正文末尾自動注入子級頁面的結構化卡片或折疊清單。
directory 支援以下模式：
"card"：以水平網格卡片形式展示子頁面標題與摘要，視覺指引清晰明瞭。"accordion"：以可折疊手風琴面板形式分段呈現子目錄，適合項目繁多的參考類文件。"none"：關閉目錄自動渲染（預設值）。
directory 具備層級繼承特性，在頂層宣告後代節點會自動繼承，且支援在深層節點手動覆蓋。
四、利用標籤分組（Tabs）實現跨模組與多業務網域拆分
當技術門戶同時涵蓋架構概念、開發指南、完整 RESTful API 參考與多語言 SDK 時，將所有內容塞進單一線性側邊欄會導致頁面過長、導覽邏輯混亂。標籤分組（Tabs）提供了頂部第一維度的水平導覽能力。
網站級頂部標籤頁
Tabs 將文件切分為若干平行的業務模組，每個標籤享有完全獨立的側邊欄選單樹與路由路徑。
在 navigation.tabs 中配置標籤陣列：
"navigation": {
"tabs": [
{
"tab": "開發指南",
"icon": "book-open",
"groups": [
{
"group": "核心流程",
"pages": ["guides/overview", "guides/quickstart"]
},
{
"group": "正式環境部署",
"pages": ["guides/docker", "guides/kubernetes"]
}
]
},
{
"tab": "API 參考",
"icon": "square-terminal",
"groups": [
{
"group": "端點集合",
"pages": ["api/v1/auth", "api/v1/payments", "api/v1/webhooks"]
}
]
},
{
"tab": "SDK 用戶端",
"icon": "code-2",
"groups": [
{
"group": "語言庫",
"pages": ["sdks/node", "sdks/python", "sdks/go"]
}
]
},
{
"tab": "更新日誌",
"icon": "megaphone",
"href": "https://changelog.acme.com"
}
]
}
當讀者在頂部導覽列切換標籤時：
- 側邊欄內容立即切換為該標籤專屬的分組與頁面結構。
- 瀏覽器 URL 路徑隨之更新。
- 外部連結（如帶有
href的更新日誌）無縫嵌入頂部導覽並支援外跳。
標籤下的次級下拉選單（menu）
如果某個頂級標籤包含多個大型獨立產品線，團隊可以在該標籤內巢狀置入 menu 下拉選單，讓讀者在切換標籤時先行選擇具體產品套件：
{
"tab": "產品矩陣",
"icon": "layers",
"menu": [
{
"item": "支付引擎",
"icon": "credit-card",
"description": "跨境收單與結算串接文件。",
"groups": [
{
"group": "接入準備",
"pages": ["payments/intro", "payments/checkout"]
}
]
},
{
"item": "身分與存取雲",
"icon": "key-round",
"description": "SSO、OAuth 2.0 與多租戶安全規範。",
"groups": [
{
"group": "身分驗證",
"pages": ["identity/overview", "identity/saml"]
}
]
}
]
}
全域錨點（Anchors）與標籤的區別
- Tabs（標籤）：用於組織平行的文件主體，切換標籤會徹底替換側邊欄顯示內容。
- Global Anchors（全域錨點）：透過
navigation.global.anchors配置，常駐在側邊欄頂部或底部的快捷外鏈或固定入口（如「系統運作狀態」、「開發者社群」、「API 變更紀錄」），跨所有標籤持續可見。
觀念釐清：全域導覽標籤 vs 頁面內 MDX 標籤
初學者常將 docs.json 中的網站級標籤與 MDX 語法中的 <Tabs> 元件混淆：
- 網站級 Tabs：控制全站頂部路由與側邊欄切換。
- 頁面內
<Tabs>元件：用於單一頁面內文中的程式碼語言切換（如 cURL、TypeScript、Python）。Mintlify 預設會在頁面內跨程式碼區塊同步相同名稱標籤的選取狀態，若需獨立切換可宣告sync={false}。
五、企業級完整設定工程範例
以下提供一個包含完整品牌外觀、全域錨點、多業務標籤頁、巢狀折疊與目錄卡片的生產級 docs.json 參考範本：
{
"$schema": "https://mintlify.com/docs.json",
"name": "CloudScale 開發者文件",
"theme": "maple",
"colors": {
"primary": "#059669",
"light": "#34D399",
"dark": "#047857"
},
"logo": {
"light": "/assets/brand/cloudscale-logo-light.svg",
"dark": "/assets/brand/cloudscale-logo-dark.svg",
"href": "https://cloudscale.dev"
},
"favicon": "/assets/brand/favicon.png",
"appearance": {
"default": "system",
"strict": false
},
"fonts": {
"family": "Inter"
},
"icons": {
"library": "lucide"
},
"background": {
"decoration": "gradient"
},
"navigation": {
"global": {
"anchors": [
{
"anchor": "服務可用狀態",
"icon": "activity",
"href": "https://status.cloudscale.dev"
},
{
"anchor": "開發者社群 Slack",
"icon": "messages-square",
"href": "https://cloudscale.dev/slack"
}
]
},
"tabs": [
{
"tab": "產品指南",
"icon": "book-open",
"groups": [
{
"group": "架構概觀與設定",
"root": "guides/index",
"directory": "card",
"pages": [
"guides/quickstart",
"guides/architecture",
"guides/cli-tooling"
]
},
{
"group": "運算與叢集",
"icon": "server",
"pages": [
"guides/compute-clusters",
{
"group": "虛擬網路與 DNS",
"expanded": false,
"pages": [
"guides/networking/vpc-peering",
"guides/networking/tls-certificates"
]
}
]
}
]
},
{
"tab": "API 參考",
"icon": "square-terminal",
"groups": [
{
"group": "身分鑑權",
"pages": [
"api/auth/tokens",
"api/auth/service-accounts"
]
},
{
"group": "運算引擎介面",
"root": "api/compute/overview",
"pages": [
"api/compute/instances",
"api/compute/snapshots"
]
}
]
}
]
}
}
六、工程落地最佳實踐與防錯要點
在團隊協作推進文件建設的過程中，遵循以下規範能夠有效避免建置失敗與體驗劣化：
- 本機使用 CLI 即時預覽：在提交程式碼前，技術寫手與工程師應在本機執行
npx mintlify dev。本機伺服器能夠秒級熱重載，並精確捕捉因檔名錯別字、漏填路徑或 JSON 格式錯誤引發的解析異常。 - 確保頁面路徑絕對精準：
pages清單中的每個字串均嚴格對應實體 MDX 檔案。若發生檔案重新命名（例如將guides/intro.mdx調整為guides/overview.mdx），必須在同一次 Git 提交中同步修改docs.json，杜絕失效死鏈。 - 嚴謹檢驗深色模式對比度：許多團隊配置了完美的淺色模式
primary品牌色，卻忽視了light的亮度微調，導致使用者在深色模式下閱讀連結與選單高亮時對比度嚴重不足。務必遵循 WCAG AA 視覺對比標準檢驗雙模色彩。 - 控制側邊欄巢狀深度：強烈建議將側邊欄巢狀控制在兩層以內（主分組 > 子分組 > 頁面）。三層以上的過深層次在行動裝置與小螢幕設備上極易產生橫向溢出與閱讀疲倦；若層次複雜，應果斷拆分至獨立頂部標籤（Tabs）或下拉選單中。