2. ローカル環境の構築と記事の執筆

手元のPC（ローカル環境）でプレビューを見ながら記事を書くための手順を説明します。

1. 必須要件の確認

• Docker および Docker Compose がインストールされていること
• Gitがインストールされていること （Pythonのインストールは不要です）

2. プロジェクトのクローン

ターミナルを開き、以下のコマンドを実行して自分のリポジトリを手元に取得します。

# クローン
git clone <あなたのリポジトリURL>
cd <クローンしたフォルダ名>

3. ローカルサーバーの起動とプレビュー

Dockerを使って、プレビュー用のサーバーを起動します。

docker compose up -d

ブラウザで http://127.0.0.1:8000/ にアクセスすると、現在のサイトが表示されます。 Markdownファイル（.md）を編集して保存すると、ブラウザのリロードなしで即座に画面に反映（ホットリロード）されます。

設定や記事の追加が画面に反映されない場合

ご利用のエディタ等の仕様により、新しいファイルの追加や mkdocs.yml の変更が自動で検知されない場合があります。その場合はコンテナを落とさず、以下のコマンドで再起動を行ってください。 bash docker compose restart mkdocs

※作業を完全に終えるときは docker compose down を実行してコンテナを停止・削除してください。

4. 記事の追加と設定

1. docs/ フォルダ内にMarkdownファイルを作成します。（例：how-to-use.md）
2. 記事を作成・編集します。
3. mkdocs.yml を開き、左側のメニューに表示されるように nav セクションを追加します。

nav:
  - ホーム: index.md
  - はじめに:
      - 概要: module1/index.md
      - 構築手順: module1/step1.md
  - 使い方: how-to-use.md

5. 画像や動画の挿入

画像

画像ファイルは、追加したい記事と同じ階層に assets フォルダを作り、その中に入れます。 Markdownからは以下のように相対パスで記述します。

![設定画面](assets/settings.png)

動画

動画ファイルはリポジトリには含めず、YouTube等にアップロードし、埋め込みタグを利用します。

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/xxxxxx"
  frameborder="0"
  allowfullscreen
></iframe>

6. 公開 (デプロイ)

記事が完成したら、変更をGitでコミットして、GitHubへPushします。

git add .
git commit -m "docs: 新しい記事を追加"
git push origin main

プッシュすると、GitHub Actions（裏側で動く自動実行システム）が自動的に最新のサイトのHTMLを生成し、数分ほどで公開用のURLに反映されます。