開発者向けドキュメントの構築において、多くのエンジニアリングチームやテクニカルライティングチームが Mintlify を採用しています。煩雑なフロントエンドのルーティングや独自の CSS を手作業で保守する代わりに、Mintlify は「Docs-as-Code（コードとしてのドキュメント）」のアプローチを採用し、サイト全体のビジュアルと情報設計をリポジトリルートの単一設定ファイル docs.json（旧仕様では mint.json）に集約しています。チームはレンダリングエンジンに手を加えることなく、バージョン管理された JSON 上でグローバルなブランド資産、多層構造のサイドバー、折りたたみ可能なグループ、そして複数の製品領域を跨ぐトップレベルのタブを宣言的に定義できます。
本記事では、技術ドキュメントチームが docs.json を活用してブランド外観のカスタマイズ、サイドバーナビゲーションの階層化、およびタブグループによるマルチセクション構成を実装する具体的な手法を解説します。
1. コアアーキテクチャ：docs.json の役割とファイル解決規約
Mintlify サイトの全グローバル設定およびナビゲーション構造は、ルートディレクトリの docs.json によって統括されます。最新の docs.json スキーマは、レイアウトテーマ、ナビゲーション構造、API プレイグラウンド設定、各種外部連携を単一の仕様として統合しています。
スキーマ検証とパスの解決ルール
エディタ（VS Code 等）での入力補完やリアルタイムの構文検証を有効にするため、docs.json の先頭で公式 JSON スキーマを指定することが推奨されます。
{
"$schema": "https://mintlify.com/docs.json",
"name": "Acme Developer Hub",
"theme": "maple"
}
チーム運用において把握しておくべき主要な規則は以下の通りです。
- 拡張子なしのファイルパス：
navigation配列内で指定する各ページパスは、リポジトリルートからの相対パスとし、.mdxや.mdの拡張子を省略して記述します。例えば"pages": ["getting-started/quickstart"]は、物理ファイルgetting-started/quickstart.mdxに解決されます。 - Git ネイティブなレビュー運用：ナビゲーションの変更や新規ページの追加、ブランドカラーの調整はすべて JSON の差分として記録されるため、Pull Request を通じたコードレビューやプレビュー環境での事前確認が可能です。
- Web エディタとの双方向同期：ブラウザ上の Mintlify Web エディタでページ順序のドラッグ＆ドロップや構造変更を行った場合も、その変更は Git コミットとして自動的に
docs.jsonへ反映されます。
2. カスタムブランディングとビジュアル設計の設定
Mintlify では、過度なスタイル上書きを行うことなく、企業のブランドガイドラインに適合したドキュメントポータルを構築できます。ブランディングに関する設定は、主に 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：両モード共通のホバー状態やセカンダリアクションに適用されます。
デュアルモード Logo と Favicon
テーマ切り替え時にもロゴの鮮明さを維持するため、ライト用とダーク用の独立した SVG ファイルを用意し、クリック時の遷移先 URL を指定します。
"logo": {
"light": "/images/logo-light.svg",
"dark": "/images/logo-dark.svg",
"href": "https://acme.com"
},
"favicon": "/images/favicon.svg"
logo.href を省略した場合、ロゴをクリックするとドキュメントのトップページへ遷移します。
タイポグラフィ、アイコン、背景装飾
- フォント指定：
fonts設定により、Google Fonts のフォント名（"Inter"や"Fira Code"等）を指定して自動ロードできるほか、独自ホストの.woff2ファイルを指定することも可能です。fonts.headingとfonts.bodyで見出しと本文のフォントを分けることもできます。 - アイコンライブラリ：Mintlify は Font Awesome、Lucide、Tabler を標準サポートしています。
"icons": { "library": "lucide" }と指定することで、各ナビゲーション項目で"book-open"などのアイコン名がそのまま利用できます。カスタム SVG や絵文字の利用も可能です。 - 背景装飾：
"background": { "decoration": "gradient" }または"grid"を指定することで、繊細なグラデーションやグリッドパターンを背景に付与できます。 - モード固定：ブランドの要件でダークモードのみに固定したい場合は、
"appearance": { "default": "dark", "strict": true }と指定することで、テーマ切り替えボタンを非表示にできます。
3. サイドバーナビゲーションの構築：グループ、ネスト、ルートページ
サイドバーは、ユーザーを順序立てて誘導するための重要なインターフェースです。Mintlify では、navigation オブジェクト内の階層ツリーでこれを定義します。
基本グループとアイコン付きグループ
関連するページを論理的なセクションにまとめるには、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 設定は階層ツリーを通じて下位グループへ再帰的に継承されるため、トップレベルで "directory": "card" を指定し、特定の子グループでのみ "directory": "none" で上書きする運用が可能です。
4. タブグループ（Tabs）によるマルチプロダクト・ドメイン分割
プロダクトガイド、完全な API リファレンス、各種言語向け SDK、変更履歴など、性質の異なる大量のコンテンツを単一のサイドバーに詰め込むと、ユーザーの認知負荷が極度に高まります。上部に配置されるタブグループ（Tabs）は、コンテンツを並列のセクションに整理するための最適なソリューションです。
サイトレベルのナビゲーションタブ
タブを定義すると、ヘッダーに水平ナビゲーションが生成され、タブごとに独立したサイドバーツリーと URL パスが割り当てられます。
設定例は以下の通りです。
"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"
}
]
}
ユーザーが上部の「ガイド」「API リファレンス」「SDK」を切り替えると：
- サイドバーが即座に切り替わり、選択されたタブ配下のグループとページのみが表示されます。
- ブラウザの URL にセクションパスが反映されます。
hrefを指定した外部リンク項目は、ヘッダーのデザインを保ったまま外部サイトへ遷移します。
タブ内のドロップダウンメニュー（menu）
ひとつのタブ内に複数の主要プロダクトやサービスが含まれる場合、タブ内に menu をネストしてドロップダウン形式の選択肢を提供できます。
{
"tab": "プロダクト",
"icon": "layers",
"menu": [
{
"item": "決済エンジン",
"icon": "credit-card",
"description": "オンライン決済と精算の統合ドキュメント",
"groups": [
{
"group": "導入手順",
"pages": ["payments/intro", "payments/checkout"]
}
]
},
{
"item": "ID プラットフォーム",
"icon": "key-round",
"description": "SSO、OAuth2、ディレクトリ同期の設定",
"groups": [
{
"group": "認証連携",
"pages": ["identity/overview", "identity/saml"]
}
]
}
]
}
グローバルアンカー（Anchors）とタブの使い分け
- Tabs（タブ）：ドキュメントの主たるカテゴリを水平に切り替えるために使用し、切り替えによってサイドバー全体が変化します。
- Global Anchors（グローバルアンカー）：
navigation.global.anchorsで定義され、サイドバーの最上部または最下部に常駐するユーティリティリンク（「システム稼働状況」「GitHub」「コミュニティフォーラム」など）として機能します。どのタブを表示していても常にアクセス可能です。
注意点：サイトレベルのタブとページ内 MDX タブの区別
初学者が混同しやすい概念として、docs.json のグローバルナビゲーションタブと、MDX ファイル内で記述する <Tabs> コンポーネントの違いがあります。
- グローバルナビゲーションタブ（
docs.json）：サイト全体のルーティングとサイドバーの切り替えを担う構造要素。 - ページ内
<Tabs>コンポーネント：単一ページ内でプログラミング言語ごとのコードスニペット（cURL、JavaScript、Python 等）を切り替える UI 要素。Mintlify では、ページ内の複数の<Tabs>でラベル名が一致している場合、連動してアクティブタブが同期されます（sync={false}を指定すると連動を解除可能）。
5. 本番環境向け設定ファイルの完全な構成例
以下は、ブランド設定、グローバルアンカー、複数タブ、ネストされたグループ、およびカード型ディレクトリインデックスを網羅した本番環境用 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": "コンピュート API",
"root": "api/compute/overview",
"pages": [
"api/compute/instances",
"api/compute/snapshots"
]
}
]
}
]
}
}
6. 運用のベストプラクティスとトラブルシューティング
ドキュメント運用を安定させ、チームの生産性を高めるための実務的なポイントは以下の通りです。
- Mintlify CLI によるローカルでの検証：変更をプッシュする前に、必ずローカル環境で
npx mintlify devを実行します。ローカル開発サーバーにより、パスのタイポ、構文エラー、未定義の MDX ファイルへの参照を即座に検知できます。 - ページパスの整合性維持：
pages配列に記載する文字列は、実際のファイル名と厳密に一致している必要があります。ファイル名をguides/cli.mdxからguides/cli-tooling.mdxに変更した際は、同一コミット内でdocs.jsonも漏れなく更新してください。 - ダークモード時のコントラスト比チェック：ライトモードの
primaryカラーの見た目だけに気を取られず、ダークモード用のlightカラーの明度を適切に調整してください。WCAG AA 基準を満たすコントラスト比を維持することが、長時間の閲覧における快適性に直結します。 - サイドバーのネスト深度の抑制：サイドバーの階層は、最大でも2階層（主グループ > 子グループ > ページ）までに留めるのが理想的です。それ以上の深さになるとモバイル端末や狭い画面で操作性が著しく低下します。構造が複雑化する場合は、タブやドロップダウンを活用して水平方向に階層を分割してください。