クイックスタート

数分でドキュメントをデプロイ

このクイックスタートガイドでは、数分でドキュメントサイトをセットアップしてデプロイする方法を説明します。

このガイドを完了すると、カスタマイズや拡張が可能な公開済みのドキュメントサイトが用意できます。

前提条件: 始める前に、アカウントを作成し、オンボーディングを完了してください。

はじめに

オンボーディングを完了すると、ドキュメントサイトは次の形式の固有のURLに自動デプロイされます：

https://<your-project-name>.mintlify.app

ダッシュボードの「概要」ページでURLを確認できます。

サイトのURLはすぐに利用可能です。ドキュメントサイトのセットアップ中は、このURLをテストやチームへの共有にご利用ください。

GitHub App をインストールする

Mintlify では、リポジトリに変更をプッシュするとデプロイを自動化する GitHub App を提供しています。

オンボーディングチェックリストまたはダッシュボードの案内に従って GitHub App をインストールします。

1. Mintlify のダッシュボードで Settings に移動します。
2. サイドバーから GitHub App を選択します。
3. Install GitHub App を選択します。新しいタブで GitHub App のインストールページが開きます。
4. アプリをインストールする組織またはユーザーアカウントを選択します。
5. 接続するリポジトリを選択します。

ドキュメントを別のリポジトリに移動した場合は、GitHub App の権限設定を更新してください。

GitHubアカウントを承認する

1. MintlifyのダッシュボードでSettingsに移動します。
2. サイドバーからMy Profileを選択します。
3. Authorize GitHub accountを選択します。GitHubの承認ページが新しいタブで開きます。

組織の設定によっては、GitHub組織の管理者による承認が必要な場合があります。

編集ワークフロー

Mintlify は、ドキュメントを作成・管理するために 2 つのワークフローを提供しています:

Code-based workflow

ローカル環境で既存のツールを使って作業したいユーザー向けです。クリックしてこのセクションに移動します。

Web editor workflow

ウェブブラウザ上のビジュアルインターフェースでの作業を好むユーザー向けです。クリックしてこのセクションに移動します。

コードベースのワークフロー

コードベースのワークフローは、既存の開発環境やGitリポジトリと統合できます。コードと同一リポジトリでドキュメントを管理したい技術チームに最適です。

CLI をインストールする

ローカルでドキュメントを編集・運用するには、ターミナルで以下のコマンドを実行して、コマンドラインインターフェース（CLI）である mint をインストールしてください。

npm

npm i -g mint

Node.js がインストールされている必要があります。インストール時に問題が発生した場合は、トラブルシューティングガイドをご確認ください。

ドキュメントを編集する

環境のセットアップが完了したら、ドキュメントファイルの編集を始められます。例として、イントロダクションページのタイトルを更新してみましょう。

1. オンボーディング時に作成したリポジトリを開きます。
2. index.mdx を開き、ファイル先頭の記述を確認します。

index.mdx

---
title: "Introduction"
description: "This is the introduction to the documentation"
---

3. title フィールドを "Hello World" に更新します。

index.mdx

---
title: "Hello World"
description: "This is the introduction to the documentation"
---

変更内容をプレビューする

ローカルでプレビューするには、次のコマンドを実行します：

mint dev

プレビューは localhost:3000 で確認できます。

変更をプッシュする

変更を公開する準備ができたら、リポジトリにプッシュします。

Mintlify は変更を自動検出し、ドキュメントをビルドしてサイトに更新をデプロイします。デプロイ状況は、GitHub リポジトリのコミット履歴またはダッシュボードで確認できます。

デプロイが完了すると、最新の更新は <your-project-name>.mintlify.app で閲覧できます。

カスタムドメインの追加に移動

必要に応じて、ウェブエディタのワークフローをスキップして、カスタムドメインの追加に移動できます。

ウェブエディタのワークフロー

ウェブエディタのワークフローは、ドキュメントの作成・編集を行えるWYSIWYG（見たまま編集）インターフェースを提供します。追加のローカル開発ツールを使わず、ウェブブラウザだけで作業したい方に最適です。

ウェブエディタにアクセスする

1. ダッシュボードにログインします。
2. 左側のサイドバーでEditorを選択します。

GitHub Appをインストールしていない場合は、ウェブエディタを開いた際にインストールを求められます。

ドキュメントを編集する

ウェブエディタでは、サイドバーからドキュメントファイルをナビゲートできます。イントロダクションページを更新してみましょう。

ファイルエクスプローラーで index.mdx を見つけて選択します。

次に、エディタでタイトル欄を「Hello World」に更新します。

エディタには豊富な書式設定ツールとコンポーネントが用意されています。エディタで / を入力してコマンドメニューを開き、これらのツールにアクセスできます。

変更を公開する

編集内容に問題がなければ、右上のPublishボタンをクリックします。変更は即座にドキュメントサイトにデプロイされます。

本番サイトにデプロイする前に、ブランチを使ってプルリクエストで変更をプレビュー・レビューしましょう。

ブランチやプルリクエストを使った共同編集や変更のプレビューなど、ウェブエディタの使い方の詳細は、ウェブエディタのドキュメントをご覧ください。

カスタムドメインの追加

<your-project-name>.mintlify.app のサブドメインはテストや開発には適していますが、本番ドキュメントには多くのチームがカスタムドメインを使用します。

カスタムドメインを追加するには、ダッシュボードの Domain Setup ページに移動します。

ドメイン（例：docs.yourcompany.com）を入力し、表示される手順に従ってドメインプロバイダーで DNS 設定を構成してください。

DNS の変更が反映されるまで最大 48 時間かかる場合がありますが、通常はより早く完了します。

次のステップ

おめでとうございます！Mintlify を使ってドキュメントサイトのデプロイに成功しました。ドキュメントをさらに充実させるために、次のステップをご確認ください。

グローバル設定を行う

サイト全体のスタイル、ナビゲーション、連携などを docs.json ファイルで設定します。

テーマをカスタマイズする

ドキュメントサイトの色やフォント、全体の見た目のカスタマイズ方法を学びます。

ナビゲーションを整理する

直感的なナビゲーション構造を設計し、ユーザーが必要な情報を探しやすくします。

インタラクティブなコンポーネントを追加する

アコーディオン、タブ、コードサンプルなどのインタラクティブなコンポーネントでドキュメントを強化します。

API リファレンスをセットアップする

OpenAPI や AsyncAPI の仕様からインタラクティブな API リファレンスを作成します。

トラブルシューティング

セットアップ中に問題が発生した場合は、次の一般的な解決策を確認してください。

ローカルプレビューが動作しない

Node.js v19 以上がインストールされていることを確認し、docs.json があるディレクトリで mint dev を実行してください。

変更が本番サイトに反映されない

デプロイには数分かかる場合があります。GitHub Actions（コードベースのワークフローの場合）または Mintlify ダッシュボードのデプロイログを確認し、ビルドエラーがないか確認してください。

カスタムドメインが接続されない

DNS レコードが正しく設定されているか確認し、DNS の伝播に十分な時間（最大 48 時間）を確保してください。DNSChecker などのツールで CNAME レコードを確認できます。