mintlify

Mintlify リファレンス

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

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

タスクで必要な場合に限り、これらのファイルをお読みください。このファイルと同じ階層にある reference/ ディレクトリにあります。見つけるには、このスキルファイルと同じディレクトリ（例：.claude/skills/mintlify/reference/）を確認してください。

ファイル	読むタイミング
reference/components.md	コンポーネント（コールアウト、カード、ステップ、タブ、アコーディオン、コードグループ、フィールド、フレーム、アイコン、ツールチップ、バッジ、ツリー、mermaid、パネル、プロンプト、色、タイル、更新情報、ビュー）を追加または変更するとき。
reference/configuration.md	docs.json の設定（テーマ、色、ロゴ、フォント、外観、ナビゲーションバー、フッター、バナー、リダイレクト、SEO、インテグレーション、API 設定）を変更するとき。スニペット、非表示ページ、.mintignore、カスタム CSS/JS、フロントマター項目の完全な一覧表についても説明しています。
reference/navigation.md	サイトのナビゲーション構造（グループ、タブ、アンカー、ドロップダウン、製品、バージョン、言語、ナビゲーション内の OpenAPI）を変更するとき。
reference/api-docs.md	API ドキュメント（OpenAPI、AsyncAPI、MDX による手動の API ページ、拡張機能、プレイグラウンド設定）をセットアップするとき。

始める前に

まず、プロジェクトの 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/ ディレクトリに保存します。ルート相対パスで参照してください。すべての画像に内容を説明する代替テキストが必要です。

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

ページのフロントマター

すべてのページのフロントマターに title が必要です。SEO 対策として description と keywords も含めてください。

---
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"）。

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

以下は、最もよく使われるコンポーネントです。すべてのプロパティと 24 種類すべてのコンポーネントについては、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!";

greeting = "Hello, world!"

```

Cards and columns

<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 にアップグレードします。

執筆基準

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

よくある間違い

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