mintlify

Mintlify リファレンス

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

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

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

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

始める前に

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

![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	文字列	はい	ナビゲーションとブラウザータブに表示されるページタイトルです。
description	文字列	いいえ	SEO 向けの簡潔な説明です。タイトルの下に表示されます。
sidebarTitle	文字列	いいえ	サイドバーのナビゲーションに表示する短いタイトルです。
icon	文字列	いいえ	Lucide、Font Awesome、または Tabler のアイコン名です。URL またはファイルパスも指定できます。
tag	文字列	いいえ	サイドバーでページタイトルの横に表示するラベルです（例：「NEW」）。
hidden	boolean	いいえ	サイドバーから非表示にします。ページには引き続き URL からアクセスできます。
mode	文字列	いいえ	ページレイアウト：default、wide、custom、frame、center。
keywords	配列	いいえ	内部検索と SEO に使用する検索語です。
api	文字列	いいえ	インタラクティブなプレイグラウンド用の API エンドポイントです（例："POST /users"）。
openapi	文字列	いいえ	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 で CLI をインストールします。

ローカル開発

• mint dev — localhost:3000 でローカルプレビューを開始します。--no-open を指定すると、ブラウザーの起動をスキップします。--groups <names> を指定すると、ユーザーグループをモックします。
• mint validate — 厳密なビルド検証を行います。警告またはエラーがある場合は、ゼロ以外の終了コードを返します。
• mint export — エアギャップ環境へのデプロイ用に、静的サイトの zip ファイルをエクスポートします。--output <file> で出力先のパスを設定します（デフォルト：export.zip）。

コンテンツの品質

• mint broken-links — 内部リンク切れを確認します。--check-anchors は # アンカーを検証します。--check-external は外部 URL を確認します。--check-snippets は <Snippet> コンポーネント内のリンクを確認します。
• mint a11y — アクセシビリティを確認します（代替テキスト、色のコントラスト）。対象を絞るには、--skip-contrast または --skip-alt-text を指定します。

分析

• mint analytics stats — KPI の数値（ビュー数、訪問者数、検索数）を表示します。オプション：--subdomain、--from、--to、--format（table/plain/json/graph）、トラフィックを絞り込む --agents／--humans、1 つのパスに絞り込む --page。
• mint analytics search — 検索分析を表示します。--query で検索語の部分文字列を指定して絞り込みます。
• mint analytics feedback — フィードバック分析を表示します。--type（code または page）。
• mint analytics conversation list — アシスタントの会話を一覧表示します。
• mint analytics conversation view <id> — 1 件の会話を表示します。
• mint analytics conversation buckets list — 会話カテゴリのバケットを一覧表示します。
• mint analytics conversation buckets view <id> — バケット内の会話を表示します。

認証

• mint login — Mintlify アカウントを認証します。
• mint logout — アカウントからログアウトします。
• mint status — 現在の認証状態を表示します。

設定

• mint config set <key> <value> — 設定値を保存します。有効なキー：subdomain、dateFrom、dateTo。
• mint config get <key> — 保存済みの設定値を読み込みます。
• mint config clear <key> — 保存済みの設定値を削除します。

プロジェクトのセットアップ

• mint new [directory] — 新しい Mintlify ドキュメントサイトのひな形を作成します。--theme と --name で初期設定を行います。
• mint workflow — ドキュメントリポジトリにワークフローを追加します。

メンテナンス

• mint update — CLI を最新バージョンに更新します。
• mint version — インストール済みの CLI とクライアントのバージョンを表示します。

執筆基準

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

よくある間違い

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