はじめに

MkDocsは、シンプルで使いやすいドキュメンテーションビルドツール（静的ウェブサイトを構築するためのツール）です。
MkDocsを使用することで、Markdown形式で記述したドキュメントを簡単にHTMLに変換し、静的なウェブサイトとして公開することができます。
最近よく使うので、使い方を簡単に整理しておこうと思います。

本記事では、MkDocsを使用してAzure Static Web Appsに自己紹介サイトをデプロイする手順をステップバイステップで説明します。（デプロイ先はgithub pagesとかでも可）

ステップ１：MkDocsのインストール

MkDocsをインストールします。Pythonパッケージとして提供されているため、pipを使用してインストールできます。

pip install mkdocs

ステップ２：MkDocsプロジェクトの作成

MkDocsプロジェクトを作成します。新しいディレクトリを作成し、そのディレクトリに移動して以下のコマンドを実行します。

mkdocs new mydocs

これにより、"mydocs" という名前の新しいMkDocsプロジェクトが作成されます。

ステップ３：コンテンツの編集

"mydocs" ディレクトリに移動し、MkDocsの設定ファイルである mkdocs.yml を編集します。このファイルでは、ドキュメントのナビゲーション構造やテーマの設定などを行います。

MkDocsでは、コンテンツはMarkdown形式で記述します。コンテンツファイルは docs ディレクトリ内に作成します。Markdownファイルを追加してコンテンツを記述しましょう。

mkdocs.yml やMarkdown、その他の設定の例はこちら

ステップ４：ローカルでのプレビュー

以下のコマンドを使用して、ローカルでMkDocsサイトをプレビューします。

cd mydocs
mkdocs serve

プレビュー用のローカルサーバーが起動し、MkDocsサイトがブラウザで表示されます。必要に応じて、コンテンツや設定を調整します。

ステップ５：ビルド

MkDocsサイトをビルドするには、以下のコマンドを実行します。

mkdocs build

上記のコマンドを実行すると、ビルドされたHTMLファイルが site ディレクトリに生成されます。このディレクトリ内のファイルをWebサーバーにデプロイすることで、MkDocsサイトを公開できます。

ビルドされたファイルは静的なHTMLファイルであり、必要な場合はCDNや静的ウェブホスティングサービスなどにアップロードして公開することができます。

ステップ６：Azure Static Web Appsのセットアップ

Azure Portalにログインし、Azure Static Web Appsのセットアップを行います。Azure Portalのメニューから "Static Web Apps" を検索し、新しいインスタンスを作成します。必要な情報を入力し、デプロイするGitHubリポジトリを指定します。

GitHubリポジトリの設定:

GitHubリポジトリにMkDocsプロジェクトをプッシュします。MkDocsプロジェクトのルートディレクトリに mkdocs.yml が存在することを確認してください。

Azure Static Web Appsのビルド設定:

Azure Static Web Appsの設定で、ビルドコマンドと出力ディレクトリを設定します。

ビルドコマンド: pip install mkdocs && mkdocs build --clean
出力ディレクトリ: site
デプロイの監視:
Azure Static Web AppsがGitHubリポジトリを監視し、自動的にデプロイを開始します。Azure Portalのデプロイのセクションで進行状況を確認できます。

デプロイの確認:

デプロイが正常に完了したら、Azure Static Web AppsのURLを使用してデプロイされたMkDocsサイトにアクセスできます。

以上がMkDocsを使用してAzure Static Web Appsにデプロイする手順です。必要に応じて各ステップの詳細をドキュメントやリファレンスから確認してください。