mintlify

Mintlify リファレンス

Mintlify プロジェクトで作業するためのリファレンスです。このファイルでは、すべてのタスクに共通する基本事項を説明します。特定のトピックについて詳しく知りたい場合は、以下のリファレンスインデックスに記載されているファイルをお読みください。

リファレンスインデックス

タスクで必要な場合にのみお読みください。各リンク先は、Mintlify のドキュメントページ、またはエージェントのワークフローに関するガイダンスの場合は GitHub 上のソースファイルです。

リファレンス	読むタイミング
コンポーネント	コンポーネント（コールアウト、カード、ステップ、タブ、アコーディオン、コードグループ、フィールド、フレーム、アイコン、ツールチップ、バッジ、ツリー、mermaid、MDX、パネル、プロンプト、色、タイル、更新情報、ビュー）の追加や変更を行う場合。また、テーブルの列幅についても説明します。
グローバル設定	docs.json の設定（テーマ、色、ロゴ、フォント、外観、ナビゲーションバー、フッター、バナー、リダイレクト、SEO、インテグレーション、API 設定）を変更する場合。また、スニペット、非表示ページ、.mintignore、カスタム CSS/JS、フロントマターの全フィールドを掲載した表についても説明します。
ナビゲーション	サイトのナビゲーション構造（グループ、タブ、アンカー、ドロップダウン、製品、バージョン、言語、OpenAPI、ナビゲーション内の SDK リファレンス）を変更する場合。
API プレイグラウンド	API ドキュメント（OpenAPI、AsyncAPI、MDX による手動の API ページ、拡張機能、プレイグラウンド設定）を設定する場合。
CLI コマンド	一般的な CLI コマンド（dev、validate、add-domain、analytics、score、broken-links、a11y、format、config）と主要なフラグを使用する場合。
製品コンテキスト	大規模なコンテンツ作業（新しいサイト、大幅な再構成、初めてのセクション設定）を始める前に、.mintlify/product-brief.md があるか確認し、内容を維持する場合。
カスタムスクリプト	CSS、JavaScript、React スニペット、セレクター、CSS 変数を使って、外観やブラウザーの動作をカスタマイズする場合。
ページの作成	ページの作成や、1～2 文を超える文章の執筆を始める前に、創作を避けるルール、ページの作成・編集手順、品質基準、対象読者、タイトルと説明、リンクについて確認する場合。
公開とレビュー	公開、ブランチとプルリクエスト、「これは公開されていますか」という質問、変更の取り消し、提案やコメントを使ったページのレビューを行う場合。
プロジェクト設定	ダッシュボード設定（ドメイン、Git ソース、認証、メンバー、ワークフロー、検索、アドオン）の確認や変更、どのツールでも扱えない設定、分析に関する質問に対応する場合。
サイト構築	サイト全体、セクション、または数ページを超える範囲の構築や移行を行う場合。調査範囲の見積もり、生成順序、ランディングページ、一般的なサイトの構成、移行ルールについて説明します。

新しいドキュメントサイトの開始

ユーザーが新しいドキュメントサイトを作成したい、ドキュメントを公開したい、またはまだ docs.json がない場合は、このワークフローを自分で実行してください。自分では提供できない情報や承認だけをユーザーに求めてください。ターミナルコマンドを実行できる場合は、ブラウザーを先に使うクイックスタートにユーザーを誘導しないでください。

1. node --version を確認します（v20.17.0 以降）。mint --version を実行し、インストールされていない場合は npm i -g mint でインストールします。インストール済みの場合は、mint update を実行します。
2. mint status を実行します。組織が表示された場合は、既存のアカウントを使用します。表示されない場合は、Mintlify アカウントを持っているかユーザーに確認します。持っている場合は mint login を実行します。持っていない場合は、名、姓、会社名、メールアドレスを尋ね、バックグラウンドプロセスとして mint signup --firstName <first> --lastName <last> --company <company> --email <email> を実行します。この処理はメール認証が完了するまで待機します。認証リンクをクリックして、ブラウザーでオンボーディングを完了するようユーザーに伝えてください。登録情報を決して捏造しないでください。
3. 認証とオンボーディングの完了後、もう一度 mint status を実行し、組織とサブドメインがあることを確認します。サブドメインが表示されない場合は、オンボーディング用のブラウザータブで GitHub リポジトリの選択または接続を完了してもらってから、再試行します。
4. すでにそのリポジトリで作業している場合を除き、接続済みリポジトリの URL（mint status には表示されません）をユーザーに尋ねて、クローンします。ユーザーが自分のドキュメントリポジトリを接続した場合は、その内容を保持し、docs.json がなければ追加します。Mintlify がリポジトリを作成した場合、スターターコンテンツが含まれています。プレースホルダーのページを書くのではなく、既存の Markdown ドキュメントで置き換えてください。ユーザーがスターターとは異なるテーマを希望する場合に限り、mint new <directory> --name <name> --theme <theme> を使用し、新しい空のディレクトリにスキャフォールドを作成します。ユーザーのファイルがあるディレクトリで --force を決して使用しないでください。
5. docs.json があるディレクトリから、バックグラウンドプロセスとして mint dev --no-open を実行します。プレビューできるよう、ローカル URL を伝えてください。mint validate と mint broken-links を実行し、自分が発生させた問題を修正します。
6. 接続済みリポジトリにコミットしてプッシュし、デプロイします。
7. URL を報告する前に、https://<subdomain>.mintlify.site が読み込まれることを確認します。

ユーザーがブラウザーを使う必要があるのは、メール認証、OAuth 承認、GitHub の接続のみです。

ローカルリポジトリがない場合

ローカルのチェックアウトと CLI の両方がない場合（たとえば、Mintlify Admin MCP サーバー経由や Mintlify エディター内で編集している場合）は、このスキルにおける mint、git、ファイルシステムの手順を省略します。

• branch 上で Admin MCP ツールを使って、ページ、ナビゲーション、docs.json を読み取り、変更します。
• create_node でページを作成します。write_page は既存のページのみを置き換えます。
• mint dev の代わりに、ツールが返す editorUrl でプレビューします。検証は書き込みごとに実行されるため、mint validate を実行する代わりに、書き込みで返されたエラーを修正します。
• プッシュの代わりに publish で公開します。ただし、ユーザーから依頼された場合に限ります。
• 製品コンテキスト の製品概要は、.mintlify/product-brief.md に書き込まず、会話内に保持します。
• 新しいサイトの場合は、既存のプロジェクトに対して サイト構築 に従います。

別のプラットフォームからの移行

Docusaurus、GitBook、ReadMe、Fern、Document360 から移行する場合は、Mintlify Search MCP サーバーを使って該当するガイド（https://mintlify.com/docs/migration/<platform>、たとえば docusaurus）を読み、手順に従います。それ以外のプラットフォームの場合は、https://mintlify.com/docs/migration/manual に従います。スクレーパーが対応するのは、シンプルな公開サイトのみです。複雑なサイトはソースファイルから移行します。移行ルールについては、サイト構築 を参照してください。

MCP サーバー

Mintlify MCP サーバーは 2 つ利用できます。このスキルのリファレンスファイルと併せて使用してください。

Mintlify 検索

Mintlify の公開ドキュメントに読み取り専用でアクセスできます。参照ファイルに特定の詳細が記載されていない場合、最新のコンポーネントシグネチャが必要な場合、または不明な設定オプションを確認する場合に使用してください。

ツール：

• search_mintlify — クエリで Mintlify ナレッジベースを検索します。ガイド、例、API リファレンスを探すのに適しています。
• query_docs_filesystem_mintlify — ドキュメントのファイルツリー（ls、cat、grep、find など）を参照します。特定のドキュメントページを読むのに適しています。
• submit_feedback — 誤りがある、古い、わかりにくい、または不完全なドキュメントページを報告します。パス（相対パスまたは完全な URL）は公開ページまたはリダイレクト元と一致している必要があります。一致しない場合、ツールはエラーを返し、何も記録しません。

Mintlify 管理

Mintlify プロジェクトへの書き込みアクセスです。初回使用時に OAuth が必要です。プロンプトが表示されたら、ブラウザーで認証を完了してください。

ユーザーが Mintlify のコンテンツを編集したり、ナビゲーションを再構成したり、プルリクエストを作成したりする場合は、このサーバーを使用してください。すべてのコンテンツツールでは branch 引数を指定します。編集、publish、discard、コメントの書き込みでは必須で、読み取りでは任意です（デフォルトはデプロイブランチです）。呼び出し間で何も記憶されないため、毎回 branch を渡してください。デプロイブランチへの編集は、publish を呼び出すまで未公開の変更として残ります。それ以外のブランチへの編集は、プルリクエストを通じて行われます。プロジェクト管理ツールによる変更は、ブランチやプルリクエストなしでライブプロジェクトに即座に適用されます。

ワークフロー：branch を指定して read／search／edit_page／write_page／list_nodes／create_node／update_node／move_node／delete_node／update_config を使用して変更し、その後、branch と title を指定して publish を呼び出し公開します（または discard で破棄します）。デプロイブランチを直接編集する場合は、そのブランチを渡してください。プロジェクトでプルリクエストが必須の場合（Push directly to your deploy branch がオフ、ブランチ保護でプルリクエストが必須、デプロイブランチの編集がロックされている、または接続でクライアントトークンもしくはマシン間トークンが使用されている場合）、デプロイブランチへの編集は理由とともに拒否され、変更は行われません。create_branch を呼び出し、その branchName を branch として渡してください。 主なツール：

• create_branch — titleを指定してデプロイブランチから新しいブランチを作成します。このタイトルはプルリクエストの名前にもなります。branchNameと、変更をリアルタイムでプレビューするためのブランチ単位のeditorUrlを返します。ブランチ上では、Mintlifyが最後の変更から約15秒後に編集内容を自動でコミットし、最初のコミット時にプルリクエストが作成されます。
• list_branches — 既存のブランチを一覧表示します。いずれかのブランチをbranchとして渡します。存在しないブランチは拒否されます。
• list_deployments — この接続からアクセスできるプロジェクトを確認します。
• read / search — ページのMDXを取得するか、ページを横断して検索します。
• edit_page / write_page：対象を絞った編集を適用するか、ページを上書きします。edit_pageは、1件の置換にoldStringとnewStringを指定するか、順番に適用する最大100件の置換を含むeditsリストを指定します。いずれかの編集に失敗すると、どの編集も適用されません。どちらのツールも、エディターが削除するマークアップ（<script>、<style>、イベントハンドラー、JavaScript式など）について、代わりに使用するものとともにnotRenderedを返します。
• read_comments / add_comment / suggest_edit / reply_to_comment / resolve_comment：ページ上の未解決のエディターコメントスレッドを読み取る、正確なテキストを指定してスレッドを開始する、変更履歴付きの提案を行う（oldStringからnewStringへの変更。newStringが空の場合は削除の提案です。任意のcommentで理由を説明でき、その内容は提案スレッド内でエージェントの返信として投稿されます）、エージェントとして返信する、またはスレッドを解決します。コメントの追加、提案、返信、解決にはOAuthセッションが必要で、branchのスレッドに対して実行されます。デプロイブランチへの編集にプルリクエストが必要な場合でも、デプロイブランチ上で動作します。
• list_nodes / create_node / update_node / move_node / delete_node：ナビゲーションツリーを管理します。create_node、update_node、move_node、delete_nodeの呼び出しによってナビゲーションが無効になった場合（たとえば、タブと並んでルートにページが配置された場合）、レスポンスにnavigationErrorsフィールドが含まれます。Mintlifyは公開時に無効なノードを公開済みナビゲーションから削除することがあるため、publishの前にこれらのエラーを修正してください。branch上のpathにページがすでに存在する場合、create_nodeは新しい内容をそのページに書き込み、ナビゲーション上の位置を維持して、updated: trueを返します。
• update_config — docs.json（テーマ、ナビゲーションのルート、インテグレーション、SEO）を変更します。
• upload_image / finalize_image_upload — ローカル画像をbranchに追加します。保存先のpath（例：images/dashboard.png）、contentType、バイト単位の正確なsizeを指定してupload_imageを呼び出します。返されたheadersを付けて、返されたuploadUrlにファイルのバイトデータをPUTし、その後、uploadIdと同じpathを指定してfinalize_image_uploadを呼び出します。返されたsrcをMDX内、またはdocs.jsonのlogoやfaviconフィールドで使用します。既存のpathにアップロードすると、画像が置き換えられます。MintlifyではロゴとファビコンにSVGのみ使用できるため、両方のツールにpurpose: "logo"を渡してください。画像は、他の編集内容とともにpublish時に公開されます。
• プロジェクト管理ツール — get_deployment_settings、get_analytics_report、get_workflows、list_repos_and_prsで読み取ります。update_deployment_settings、manage_custom_domain、manage_git_source、manage_access_auth、manage_workflow、manage_members_sharingで書き込みます。subdomain（組織全体の接続では必須。読み取りツールでは最大25件のsubdomainsも指定可能）と、操作を選択するaction（またはreport）を含むrequestオブジェクトを渡します。書き込みはライブプロジェクトに即時適用され、更新後のstateが返されるため、先に意図した変更であることを確認してください。 プライベートページ：list_nodes は visibility: "private" を受け取り、OAuth ユーザーがアクセスできるプライベートページとフォルダーを一覧表示します（ほかのフィルターは無視し、各ノードの role を返します）。read、edit_page、write_page、update_node、delete_node は private-page-<uuid> または private-folder-<uuid> のノード ID を受け取ります。create_node は visibility: "private" と data.type: "page" または "group" を受け取ります。プライベートページの操作には OAuth セッションが必要です（管理者用 MCP はクライアントトークンとマシン間トークンを拒否します）。branch は不要で、ロール要件が適用されます。読み取りには read、書き込みと更新には editor 以上、削除には manager が必要です。作成したノードの manager には呼び出し元がなります。
• diff — branch とデプロイブランチの差分をすべて確認します。
• status — branch 上の未公開の編集済みファイル、docs.json のキー、ナビゲーションの変更を一覧表示します。デプロイブランチでは、自分の変更のみを一覧表示します。
• publish — title を指定して branch を公開します。ユーザーが公開、出荷、またはマージを求めた場合にのみ呼び出してください。編集後に独断で呼び出してはいけません。デプロイブランチでは、自分の保留中の変更のみをコミットします。ブランチでは、保留中の変更をすべてコミットし、そのブランチのプルリクエストを返します。プルリクエストがない場合は作成します。ユーザーが求めており、デプロイブランチへの編集が許可されている場合に限り、merge: true を渡すと、そのプルリクエストもマージします。それ以外の場合は merge_not_allowed を返し、プルリクエストは開いたままにします。publish は mode を無視します。コミット対象がなく、プルリクエストもない場合は no_pending_changes を返します。応答には、最初に作成または更新されたページを開く editorUrl が含まれます。変更がデプロイブランチに反映されると、commitSha と deployment オブジェクトも返します。
• deployment_status — 公開した変更が反映されたか確認します。publish の commitSha を渡すか、省略して最新のデプロイを確認します。state（pending、queued、building、live、not_live、failed、skipped のいずれか）、live の真偽値、message を返します。live が true になるまで、変更は反映されていません。約30秒ごとに再確認し、状態が failed、not_live（サイトでは引き続き以前のバージョンが配信されています）、または skipped の場合は message を報告してください。
• discard — デプロイブランチでは、自分の保留中の変更のみを取り消します。別のブランチでは、そのブランチを作成した場合に限り、ブランチを削除してプルリクエストを閉じます。それ以外の場合は何も変更しません。

各ブランチの変更は1つに絞ってください。ブランチが小さいほど、プルリクエストをレビューしやすくなります。editorUrl を開くと、変更がライブでレンダリングされる様子を確認できます。create_branch の editorUrl より、create_node または publish が返すページ単位の editorUrl を優先してください。

作業を始める前に

Mintlify は頻繁に変更されるため、覚えている情報だけに頼らないでください。このスキルに記載のない詳細については、Mintlify Search MCP サーバーまたは https://mintlify.com/docs で最新のドキュメントを確認してください。

まとまったコンテンツ作業を始める前に、製品コンテキストを読み、.mintlify/product-brief.md があるか確認してください。

まず、プロジェクトの docs.json ファイルを読んでください。サイトのナビゲーション、テーマ、色、設定が定義されています。

外観やブラウザーの動作を変更する場合は、カスタムスクリプトを読んでください。

新しいページを作成する前に、既存のコンテンツを検索してください。内容を重複させるのではなく、既存ページの更新、セクションの追加、または既存コンテンツへのリンクが必要な場合があります。

サイトの文体、構成、書式に合わせるため、類似ページを2～3ページ読んでください。

ファイル形式

Mintlify では、YAML フロントマターを含む MDX ファイル（.mdx または .md）を使用します。

project/
├── docs.json           # Site configuration (required)
├── index.mdx
├── quickstart.mdx
├── guides/
│   └── example.mdx
├── openapi.yml         # API specification (optional)
├── images/             # Static assets
│   └── example.png
└── snippets/           # Reusable components
    └── component.jsx

ファイル名

• ディレクトリ内の既存の命名パターンに合わせます
• 既存ファイルがない場合、または命名パターンが混在している場合は、kebab-case を使用します：getting-started.mdx
• 新しいページを docs.json のナビゲーションに追加してください。追加しないとサイドバーに表示されません

内部リンク

• 拡張子を付けずにルート相対パスを使用します：/getting-started/quickstart
• 内部ページへのリンクには相対パス（../）や絶対 URL を使用しないでください

画像

画像は images/ ディレクトリに保存します。ルート相対パスで参照してください。すべての画像に内容を説明する alt テキストが必要です。

Mintlify は、リポジトリに保存され、ルート相対パスで参照されている画像を自動的に最適化します。対応している場合は AVIF または WebP 形式で配信し、圧縮して、幅 2500px までのサイズ変更版を生成し、幅と高さを追加します。これらの画像を自分で変換したりサイズ変更したりしないでください。GIF、SVG、ICO ファイル、絶対 URL で参照されている画像、認証が必要なページ上の画像は最適化されずに配信されるため、GIF や外部ホストの画像は追加前に圧縮してください。

![Dashboard showing analytics overview](/images/dashboard.png)

ページのフロントマター

フロントマターには title、description、keywords を含めます。title は技術的には省略可能で、省略した場合は Mintlify がファイルパスから生成しますが、明確さと SEO のために明示的に設定してください。

---
title: "Clear, descriptive title"
description: "Concise summary for SEO and navigation."
keywords: ["relevant", "search", "terms"]
---

よく使うフロントマターフィールド

フィールド	型	説明
title	string	ナビゲーションとブラウザータブに表示されるページタイトルです。省略した場合はパスから自動生成されます。
description	string	SEO 用の簡潔な説明です。タイトルの下に表示されます。
sidebarTitle	string	サイドバーナビゲーションに表示される短いタイトルです。
icon	string	Lucide、Font Awesome、Tabler のアイコン名です。単一の絵文字、URL、またはファイルパスも指定できます。
tag	string	サイドバーのページタイトルの横に表示されるラベルです（例：「NEW」）。
hidden	boolean	サイドバーから非表示にします。ページには引き続き URL からアクセスできます。
mode	string	ページレイアウトです：default、wide、custom、frame、center。
keywords	array	内部検索と SEO 用の検索語です。
api	string	インタラクティブなプレイグラウンド用の API エンドポイントです（例："POST /users"）。
openapi	string	OpenAPI エンドポイントの参照です（例："GET /endpoint"）。

searchable、boost、deprecated、related、groups などを含む全項目については、Pages をご覧ください。

コンポーネントのクイックリファレンス

以下は、最もよく使われるコンポーネントです。すべてのプロパティと全 26 種類のコンポーネントについては、Components をご覧ください。

コールアウト

<Note>Supplementary information, safe to skip.</Note>
<Info>Helpful context such as permissions or prerequisites.</Info>
<Tip>Recommendations or best practices.</Tip>
<Warning>Potentially destructive actions or important caveats.</Warning>
<Check>Success confirmation or completed status.</Check>
<Danger>Critical warnings about data loss or breaking changes.</Danger>

ステップ

<Steps>
  <Step title="First step">
    Instructions for step one.
  </Step>
  <Step title="Second step">
    Instructions for step two.
  </Step>
</Steps>

タブとコードグループ

<Tabs>
  <Tab title="npm">
    ```bash
    npm install package-name
    ```
  </Tab>
  <Tab title="yarn">
    ```bash
    yarn add package-name
    ```
  </Tab>
</Tabs>

<CodeGroup>

```javascript example.js
const greeting = "Hello, world!";
```

```python example.py
greeting = "Hello, world!"
```

</CodeGroup>

カードと列

<Columns cols={2}>
  <Card title="First card" icon="rocket" href="/quickstart">
    Card description text.
  </Card>
  <Card title="Second card" icon="book" href="/guides">
    Card description text.
  </Card>
</Columns>

<Columns> を使用すると、カード（またはその他のコンテンツ）をグリッド状に配置できます。cols には 1～4 を指定できます。

アコーディオン

<AccordionGroup>
  <Accordion title="First section">Content one.</Accordion>
  <Accordion title="Second section">Content two.</Accordion>
</AccordionGroup>

CLI コマンド

npm i -g mint でインストールします。主なコマンドは、mint dev（ローカルプレビュー）、mint validate、mint broken-links、mint a11y、mint score、mint analytics（トラフィック、検索、フィードバック、アシスタントとの会話。Pro および Enterprise プラン）、mint new、mint signup です。すべてのフラグとサブコマンドについては、CLI commands をご覧ください。

執筆基準

• 二人称で書きます（「あなた」）。
• 能動態を使い、簡潔に書きます。
• 見出しは文頭のみ大文字にします（「Getting started」。 「Getting Started」ではありません）。
• コードブロックのタイトルは文頭のみ大文字にします。
• すべてのコードブロックに言語タグを付けます。
• すべての画像に内容を説明する alt テキストを付けます。
• マーケティング表現、冗長なフレーズ、絵文字は使いません。
• コード例はシンプルで実用的なものにし、テスト済みのものを使います。

よくある間違い

• mint.json を使用する — 非推奨です。設定ファイルは常に docs.json です。
• コードブロックに言語タグがない（``` ではなく ```python を使用してください）。
• ルート相対パス（/section/page）ではなく、相対パス（../page）を使用する。
• 新しいページを docs.json のナビゲーションに追加し忘れる。
• alt テキストのない画像。
• 内部リンクにファイル拡張子を付ける（/page ではなく /page.mdx）。