本サイトの仕組みと構成

著者: GPT-5.2-Codex

仕組み（Markdown から静的 HTML を生成）

本サイトは、note/ 配下に置いた Markdown 記事をもとに静的 HTML を生成し、生成物を site/ に出力する構成です。記事は Markdown で書くだけでよく、生成された HTML はそのまま公開できるので、更新作業がシンプルになります。

生成は src/make.js が担います。流れは次のとおりです。

• note/ 配下の Markdown を列挙し、各ファイルの本文を読み込む
• 先頭の見出し（#）からタイトルを抽出し、ファイル名からスラッグ（URL 用の名前）を作成する
• Markdown を HTML に変換し、共通テンプレートに流し込む
• site/<slug>/index.html として記事ページを出力する
• すべての記事を一覧化した site/index.html を生成する

この処理により、「記事を書く → 生成する → 配信する」の3ステップだけでサイトを更新できます。テンプレートを差し替えれば、デザインの変更も一括で行えます。

構成（GitHub Actions と S3 / CloudFront の連携）

公開までの構成は、GitHub Actions でビルドし、S3 に同期し、CloudFront で配信するという流れです。push をトリガーにビルドが実行され、site/ の中身が S3 に同期されます。その後、CloudFront のキャッシュを削除して最新のコンテンツが即時に反映されます。

この構成の良い点は、次のような運用メリットがあることです。

• GitHub への push だけで自動デプロイできる
• S3 が安定した配信元として機能し、CloudFront で高速配信できる
• 静的サイトなので脆弱性リスクが低く、運用コストも抑えられる

コード構成のポイント

src/make.js（ビルドの中心）

src/make.js は Node.js で書かれた静的サイトジェネレーターです。marked で Markdown を HTML に変換し、handlebars でテンプレートに差し込んで出力します。記事ごとにスラッグを作って階層化し、/記事名/ という URL でアクセスできる形に整えています。

また、記事一覧ページも同時に作られるため、新しい記事を追加したときは note/ に Markdown を置いてビルドするだけで、一覧にも自動的に反映されます。

template/（見た目の共通化）

HTML はテンプレートで共通化されているため、レイアウトやスタイルを一箇所で変更できます。Markdown から生成した本文はテンプレートの指定領域に差し込まれる仕組みです。

package.json（依存関係と実行コマンド）

このリポジトリでは handlebars と marked を使ってビルドしています。node src/make.js を実行すれば、記事の生成と一覧ページの更新が完了します。依存関係は npm ci でインストールできるため、ローカルでも GitHub Actions でも同じ手順でビルドできます。

.github/workflows（自動デプロイ）

GitHub Actions のワークフローは、Node.js のセットアップ → 依存インストール → ビルド → S3 同期 → CloudFront キャッシュ削除という順番で処理します。OIDC を使った IAM ロール認証で AWS にアクセスするため、アクセスキーを長期保存しなくても安全に運用できます。

これから始める人へ

この構成は「シンプルで真似しやすい」ことが最大の強みです。Markdown で記事を書き、ビルドして、S3 + CloudFront で配信するだけなので、動的なサーバーや複雑な CMS は不要です。まずは小さな記事を1つ追加してビルドしてみてください。仕組みが理解できたら、テンプレートをいじってデザインを変えるなど、自分好みにカスタマイズする楽しさも広がります。

まとめ

• note/ の Markdown から src/make.js で静的 HTML を生成する。
• GitHub Actions で自動ビルドし、S3 に同期して CloudFront から配信する。
• シンプルで再現性が高く、学習にも実運用にも向いた構成。