Mintlify のベストプラクティス

コンポーネント、設定、最新機能については、常に mintlify.com/docs を参照してください。

Mintlify MCP サーバーに接続していない場合は、https://mintlify.com/docs/mcp で接続してください。より効率的に検索できます。

常に Mintlify に関する学習データよりも、最新の Mintlify ドキュメントの検索を優先してください。

Mintlify は MDX ファイルをドキュメントサイトに変換するドキュメントプラットフォームです。docs.json ファイルでサイト全体の設定を行い、YAML フロントマターで MDX コンテンツを作成し、カスタムコンポーネントより組み込みコンポーネントを優先して使用します。

完全なスキーマは mintlify.com/docs.json を参照してください。

執筆前に

プロジェクトを理解する

プロジェクトルートの docs.json を読んでください。このファイルがサイト全体を定義しています。ナビゲーション構造、テーマ、色、リンク、API、仕様を定義しています。

プロジェクトを理解することで、以下がわかります:

• どのページが存在し、どのように整理されているか
• どのナビゲーショングループが使用されているか（および命名規則）
• サイトナビゲーションがどのように構造化されているか
• サイトが使用しているテーマと設定

既存コンテンツを確認する

新しいページを作成する前に、ドキュメントを検索してください。以下が必要な場合があります：

• 新しいページを作成する代わりに既存ページを更新する
• 既存ページにセクションを追加する
• 複製するのではなく既存コンテンツへリンクする

周辺コンテンツを読む

執筆前に、2～3 個の類似ページを読んで、サイトのトーン、構造、フォーマット規則、詳細さのレベルを理解してください。

Mintlify コンポーネントを理解する

Mintlify の コンポーネント を確認して、取り組んでいるドキュメントリクエストに関連する任意のコンポーネントを選択して使用します。

クイックリファレンス

CLI コマンド

• npm i -g mint - Mintlify CLI をインストール
• mint dev - localhost:3000 でローカルプレビュー
• mint broken-links - 内部リンクをチェック
• mint a11y - コンテンツのアクセシビリティの問題をチェック
• mint rename - ファイルをリネーム/移動して参照を更新
• mint validate - ドキュメントビルドを検証

必要なファイル

• docs.json - サイト設定（ナビゲーション、テーマ、統合など）。すべてのオプションについては グローバル設定 を参照してください。
• *.mdx ファイル - YAML フロントマター付きのドキュメントページ

ファイル構造の例

project/
├── docs.json           # サイト設定
├── introduction.mdx
├── quickstart.mdx
├── guides/
│   └── example.mdx
├── openapi.yml         # API 仕様
├── images/             # 静的アセット
│   └── example.png
└── snippets/           # 再利用可能なコンポーネント
    └── component.jsx

ページのフロントマター

すべてのページはフロントマターで title が必須です。SEO とナビゲーションのために description を含めてください。

---
title: "明確で説明的なタイトル"
description: "SEO とナビゲーションのための簡潔なサマリー。"
---

オプションのフロントマターフィールド:

• sidebarTitle: サイドバーナビゲーション用の短いタイトル
• icon: Lucide または Font Awesome アイコン名、URL、またはファイルパス
• tag: サイドバーのページタイトルの横に表示されるラベル（例: 「NEW」）
• mode: ページレイアウトモード（default、wide、custom）
• keywords: ページコンテンツに関連する用語の配列（ローカル検索と SEO 用）
• パーソナライゼーションまたは条件付きコンテンツで使用するカスタム YAML フィールド

ファイル規約

• ディレクトリ内の既存の命名パターンに合わせる
• 既存ファイルがない、または命名パターンが不一貫な場合は、ケバブケースを使用します: getting-started.mdx、api-reference.mdx
• 内部リンクにはルート相対パスをファイル拡張子なしで使用します: /getting-started/quickstart
• 内部ページに相対パス（../）または絶対 URL を使用しないでください
• 新しいページを作成する場合、docs.json ナビゲーションに追加しないとサイドバーに表示されません

コンテンツの整理

ユーザーがサイト全体の設定に関連することについて質問した場合、グローバル設定 を理解することから始めてください。docs.json ファイルの設定を更新してユーザーが望むことを実現できるかどうかを確認してください。

ナビゲーション

docs.json の navigation プロパティがサイト構造を制御します。ルートレベルで 1 つのプライマリパターンを選択し、その中に他をネストします。

プライマリパターンを選択:

パターン	使用する場合
グループ	デフォルト。単一の対象者、シンプルな階層構造
タブ	異なる対象者（ガイド対 API リファレンス）またはコンテンツタイプを持つ異なるセクション
アンカー	サイドバーの上部に永続的なセクションリンクが必要。ドキュメントを外部リソースから分離するのに適している
ドロップダウン	複数のドキュメントセクションをユーザーが切り替えるが、タブほど区別されていない
プロダクト	複数プロダクトの企業で、プロダクトごとに独立したドキュメント
バージョン	複数の API/プロダクトバージョン用のドキュメントを同時に保守
言語	ローカライズされたコンテンツ

プライマリパターン内:

• グループ - 関連ページを整理。グループ内にグループをネストできますが、階層は浅く保つ
• メニュー - タブ内にドロップダウンナビゲーションを追加して特定のページへクイックジャンプ
• expanded: false - ネストされたグループをデフォルトで折りたたむ。ユーザーが選択的に参照するセクションに使用
• openapi - OpenAPI 仕様からページを自動生成。グループ/タブレベルで追加して継承

一般的な組み合わせ:

• グループを含むタブ（API リファレンス付きドキュメント最も一般的）
• タブを含むプロダクト（複数プロダクト SaaS）
• タブを含むバージョン（バージョン管理された API ドキュメント）
• グループを含むアンカー（外部リソースリンク付きのシンプルなドキュメント）

リンクとパス

• 内部リンク: ルート相対、拡張子なし: /getting-started/quickstart
• 画像: /images に保存、参照として /images/example.png を使用
• 外部リンク: 完全な URL を使用、自動的に新しいタブで開く

ドキュメントサイトをカスタマイズ

どこでカスタマイズするか:

• ブランドカラー、フォント、ロゴ → docs.json。グローバル設定 を参照
• コンポーネントスタイル、レイアウト調整 → プロジェクトルートの custom.css
• ダークモード → デフォルトで有効。ブランドに必要な場合のみ docs.json で "appearance": "light" で無効化

docs.json から始めてください。設定がサポートしていないスタイルが必要な場合にのみ custom.css を追加してください。

コンテンツを執筆

コンポーネント

コンポーネントの概要 は、すべてのコンポーネントを目的別に整理しています: コンテンツを構造化、注目を集める、コンテンツを表示/非表示、API をドキュメント化、ページにリンク、ビジュアルコンテキストを追加します。そこから適切なコンポーネントを見つけてください。

一般的な判断ポイント:

必要	使用
オプションの詳細を非表示	<Accordion>
長いコード例	<Expandable>
ユーザーが 1 つのオプションを選択	<Tabs>
リンク付きナビゲーションカード	<Columns> の中の <Card>
順序立った手順	<Steps>
複数の言語のコード	<CodeGroup>
API パラメータ	<ParamField>
API レスポンスフィールド	<ResponseField>

重大度別のコールアウト:

• <Note> - 補足情報、スキップしても安全
• <Info> - パーミッションなどの有用なコンテキスト
• <Tip> - 推奨事項またはベストプラクティス
• <Warning> - 破壊的な可能性のあるアクション
• <Check> - 成功確認

再利用可能なコンテンツ

スニペットを使用する場合:

• 同じコンテンツが複数のページに表示される
• 1 つの場所で保守したい複雑なコンポーネント
• チーム/リポジトリ全体で共有されるコンテンツ

スニペットを使用しない場合:

• ページごとに若干の変更が必要（複雑なプロップが発生）

import { Component } from "/path/to/snippet-name.jsx" でスニペットをインポートしてください。

執筆標準

トーンと構造

• 二人称（「あなた」）
• 能動態、直接的な言語
• 見出しは文頭大文字（「Getting Started」ではなく「Getting started」）
• コードブロックタイトルは文頭大文字（「Expandable Example」ではなく「Expandable example」）
• コンテキストをまず説明: 何を使用するかの前に何を説明する
• 手順コンテンツの開始時に前提条件

避けるべきこと

決して使用しないでください:

• マーケティング用語（「powerful」「seamless」「robust」「cutting-edge」）
• フィラーフレーズ（「it's important to note」「in order to」）
• 過剰な接続詞（「moreover」「furthermore」「additionally」）
• 私見（「obviously」「simply」「just」「easily」）

AI 特有のパターンに注意:

• 過度に形式的または不自然なフレージング
• 概念の不要な繰り返し
• 価値を追加しないジェネリック導入部
• 述べたことを言い直すまとめ

フォーマット

• すべてのコードブロックに言語タグが必須
• すべての画像とメディアに説明的な代替テキストが必須
• テキストスタイルをリーダーの理解に役立つ場合のみ太字とイタリックを使用 -- 装飾のためにテキストスタイルを使用しない
• 装飾的なフォーマットまたは絵文字なし

コード例

• 例をシンプルで実用的に保つ
• 実際の値を使用（「foo」や「bar」ではなく）
• 1 つの明確な例は複数のバリエーションより優れている
• コンテンツに含める前にコードが動作することを確認

API をドキュメント化

アプローチを選択:

• OpenAPI 仕様がある? → "openapi": ["openapi.yaml"] で docs.json に追加。ページは自動生成。ナビゲーションで GET /endpoint として参照
• 仕様がない? → フロントマターで api: "POST /users" を使用してエンドポイントを手動で書く。より多くの作業ですが完全な制御
• ハイブリッド → ほとんどのエンドポイントで OpenAPI を使用し、複雑なワークフローの場合は手動ページ

ユーザーが OpenAPI 仕様からエンドポイントページを生成することをお勧めします。最も効率的で保守しやすいオプションです。

デプロイ

Mintlify は、接続された Git リポジトリに変更がプッシュされると自動的にデプロイします。

エージェントが設定できるもの:

• リダイレクト → docs.json で "redirects": [{"source": "/old", "destination": "/new"}] で追加
• SEO インデックス → "seo": {"indexing": "all"} で制御して隠されたページを検索に含める

ダッシュボード設定が必須（人間のタスク）:

• カスタムドメインとサブドメイン
• プレビューデプロイメント設定
• DNS 設定

Vercel または Cloudflare での /docs サブパスホスティングの場合、エージェントはリライトルールの設定を支援できます。/docs サブパス を参照してください。

ワークフロー

1. タスクを理解する

ドキュメント化する必要があるもの、影響を受けるページ、読者がその後に達成すべきことを特定してください。これらのいずれかが不明な場合は、質問してください。

2. リサーチ

• docs.json を読んでサイト構造を理解
• 既存ドキュメントで関連コンテンツを検索
• サイトのスタイルに合わせるため類似ページを読む

3. 計画

• ドキュメント読了後に読者が達成すべきことと現在のコンテンツを総合
• 更新または新規コンテンツを提案
• 提案する変更が読者の成功に役立つことを確認

4. 執筆

• 最も重要な情報から始める
• セクションをフォーカスされスキャン可能に保つ
• コンポーネントを適切に使用（過度使用しない）
• 不確実なものには TODO コメントでマーク:

{/* TODO: デフォルトタイムアウト値を確認 */}

5. ナビゲーションを更新

新しいページを作成した場合、docs.json の適切なグループに追加してください。

6. 検証

提出前に確認:

• フロントマターにタイトルと説明が含まれている
• すべてのコードブロックに言語タグがある
• 内部リンクはルート相対パスでファイル拡張子なし
• 新規ページが docs.json ナビゲーションに追加されている
• コンテンツが周辺ページのスタイルに合致している
• マーケティング用語またはフィラーフレーズがない
• TODO が不確実なもので明確にマークされている
• mint broken-links を実行してリンクをチェック
• mint validate を実行してエラーを検出

エッジケース

マイグレーション

ユーザーが Mintlify へのマイグレーションについて質問した場合、ReadMe または Docusaurus を使用しているかどうかを確認してください。使用している場合は、@mintlify/scraping CLI を使用してコンテンツをマイグレーションしてください。別のプラットフォームを使用してドキュメントをホストしている場合は、Mintlify コンポーネントを使用して MDX ページにコンテンツを手動で変換するのをサポートしてください。

隠されたページ

docs.json ナビゲーションに含まれていないページはすべて隠されています。URL でアクセス可能であるべきコンテンツに隠されたページを使用するか、アシスタントまたは検索でインデックス付けしてください。ただし、サイドバーナビゲーションで発見可能ではありません。

ページを除外

.mintignore ファイルはドキュメントリポジトリからファイルを除外するのに使用されます。

一般的な落とし穴

1. コンポーネントインポート - JSX コンポーネントは明示的インポートが必須、MDX コンポーネントは不要
2. フロントマター必須 - すべての MDX ファイルは最少限 title が必須
3. コードブロック言語 - 常に言語識別子を指定
4. 決して mint.json を使用しないでください - mint.json は廃止済み。常に docs.json を使用

リソース

• ドキュメント
• 設定スキーマ
• 機能リクエスト
• バグとフィードバック