mintlify

Mintlify リファレンス

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

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

タスクで必要な場合にのみ、これらのファイルをお読みください。このファイルと同じディレクトリにある reference/ ディレクトリ内にあります。

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

新しいドキュメントサイトの作成

ユーザーが新しいドキュメントサイトを作成したい場合、ドキュメントを公開したい場合、またはまだ 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、ファイルシステム関連の手順を省略してください。

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

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

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

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 は、ノード ID として private-page-<uuid> または private-folder-<uuid> を受け付けます。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 で最新のドキュメントを確認してください。

内容に関する本格的な作業の前に、reference/product-context.md を読み、.mintlify/product-brief.md があるか確認してください。

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

外観やブラウザーの動作を変更する場合は、reference/customization/index.md を読んでください。

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

サイトの文体、構成、書式に合わせるため、類似するページを 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/ ディレクトリに保存します。ルート相対パスで参照してください。すべての画像に内容を説明する代替テキストが必要です。

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 のアイコン名です。絵文字 1 文字、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 などを含むすべての項目については、reference/configuration.md をご覧ください。

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

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

コールアウト

<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 です。すべてのフラグとサブコマンドについては、reference/cli.md をご覧ください。

執筆基準

• 二人称の文体（「あなた」）を使います。
• 能動態で、直接的な表現にします。
• 見出しは文頭のみ大文字にします（「Getting started」のようにし、「Getting Started」にはしません）。
• コードブロックのタイトルは文頭のみ大文字にします。
• すべてのコードブロックに言語タグを付けます。
• すべての画像に内容を説明する代替テキストを付けます。
• マーケティング的な表現、不要な言い回し、絵文字は使いません。
• コード例はシンプルで実用的なものにし、テストしてください。

よくある間違い

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