Mintlify リファレンス

Mintlify でドキュメントを構築するためのリファレンス。このファイルでは、すべてのタスクに適用される必須事項をカバーしています。特定のトピックの詳細については、以下のリファレンスインデックスに記載されているファイルをお読みください。

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

タスクに必要な場合のみ、これらのファイルをお読みください。これらは、このスキルファイルと同じディレクトリの reference/ ディレクトリに格納されています (例: .claude/skills/mintlify/reference/)。

ファイル	読むタイミング
reference/components.md	コンポーネントの追加または変更時 (callouts、cards、steps、tabs、accordions、code groups、fields、frames、icons、tooltips、badges、trees、mermaid、panels、prompts、colors、tiles、updates、views)。
reference/configuration.md	docs.json の設定を変更する場合 (テーマ、色、ロゴ、フォント、外観、navbar、footer、バナー、リダイレクト、SEO、インテグレーション、API 設定)。スニペット、非表示ページ、.mintignore、カスタム CSS/JS、および完全な frontmatter フィールドテーブルもカバーしています。
reference/navigation.md	サイトナビゲーション構造を変更する場合 (グループ、tabs、アンカー、ドロップダウン、プロダクト、バージョン、言語、nav の OpenAPI)。
reference/api-docs.md	API ドキュメントのセットアップ時 (OpenAPI、AsyncAPI、MDX 手動 API ページ、拡張機能、playground 設定)。

始める前に

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

新しいページを作成する前に、既存のコンテンツを検索してください。既存のページを更新したり、セクションを追加したり、既存のコンテンツにリンクしたりする必要があるかもしれません。

サイトのボイス、構造、およびフォーマットに合わせるため、同様のページ 2～3 ページをお読みください。

ファイル形式

Mintlify は YAML frontmatter を含む 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 テキストが必要です。

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

ページの frontmatter

すべてのページでは frontmatter に title が必須です。SEO のため description と keywords も含めてください。

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

一般的な frontmatter フィールド

フィールド	型	必須	説明
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	いいえ	インタラクティブ playground の API エンドポイント (例: "POST /users")。
openapi	string	いいえ	OpenAPI エンドポイント参照 (例: "GET /endpoint")。

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

以下は最も一般的に使用されるコンポーネントです。完全なプロップとすべての 24 個のコンポーネントについては、reference/components.md をお読みください。

Callouts

<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

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

Tabs とコードグループ

<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!";

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 — Mintlify CLI をインストールします。
• mint dev — localhost:3000 でローカルプレビューします。
• mint broken-links — 内部リンクをチェックします。
• mint a11y — アクセシビリティの問題をチェックします。
• mint validate — ドキュメントのビルドを検証します。
• mint upgrade — mint.json から docs.json へアップグレードします。

ライティング標準

• 二人称 ("you")。
• アクティブボイス、直接的な言語。
• 見出しはセンテンスケース ("Getting started"、"Getting Started" ではなく)。
• コードブロックのタイトルはセンテンスケース。
• すべてのコードブロックには言語タグが必須です。
• すべての画像には説明的な alt テキストが必須です。
• マーケティング用語、フィラー表現、絵文字なし。
• コード例は簡潔で実用的、かつテストされたものにしてください。

よくある間違い

• コードブロックに言語タグがない (``` ではなく ```python を使用)。
• 相対パス (../page) を使用していて、ルート相対パス (/section/page) を使用すべき場合。
• 新しいページを docs.json ナビゲーションに追加するのを忘れている。
• alt テキストのない画像。
• 内部リンクにファイル拡張子を追加している (/page ではなく /page.mdx)。