EX FOUNDRYのサイト構成：プロダクト情報を静的サイトで配信する

何を一つにまとめ、何を分けるか

EX FOUNDRYは、複数の個人開発プロダクトを見つけるための案内と、各プロダクトの公式な説明・技術構成・リリース情報を一つのドメインにまとめています。一方で、プロダクト本体はそれぞれ別のリポジトリとサブドメインで運用しています。案内サイトとプロダクトを同じアプリケーションへ詰め込むのではなく、情報の責務と実行環境の責務を分けて設計しました。

ex-foundry.com
  ├─ プロダクト一覧・公式情報・リリース記事
  ├─ DevToys Web       → devtoys.ex-foundry.com
  ├─ ひまつぶし研究室  → maker.ex-foundry.com
  ├─ NPB Analysis      → npb-analysis.ex-foundry.com
  └─ クソゲーの森       → kusoge.ex-foundry.com

この分離によって、プロダクト側のデプロイが互いに影響しなくなり、EX FOUNDRYでは全体像と変更履歴を横断して説明できるようになります。例えば、ゲーム側でWeb Workerの構成を変更しても、静的な記事サイトの配信処理まで変える必要はありません。反対に、記事の分類やサイト内検索を改善しても、プロダクト本体の機能テストを再実行する必要はありません。

ただし、分離しただけでリンク切れや説明の不一致が自動的に防げるわけではありません。そこでプロダクト紹介には実際の公開URLを置き、技術構成の記事にはプロダクト側のREADMEやarchitectureドキュメントへのリンクを置いています。公開前には、リンク、サービス名、ログイン要否、データ処理の説明が実態と合っているかを照合します。

記事の静的生成

記事はMarkdownで管理し、Viteのビルド時にHTMLへ変換します。front matterにはタイトル、日付、対象プロダクト、記事の種類、タグ、カバー画像を記録し、本文のMarkdownとあわせてビルドへ渡します。記事一覧、sitemap、canonical、JSON-LDはすべて同じ記事データから生成するため、記事を1本追加するだけで公開URLの一覧にも自動的に反映されます。

Markdown
  ↓ front matterを読み込む
記事メタデータ + 本文HTML
  ├─ トップページ
  ├─ プロダクト情報一覧
  ├─ 記事詳細の静的HTML
  ├─ sitemap.xml
  └─ Article / ItemList の構造化データ

記事データの最小単位

記事を追加するときは、本文だけでなく、どのプロダクトのどの種類の情報なのかをfront matterに記録します。以下は実際のファイルで使っている項目を抜き出した、説明用の簡略例です。contentTypeを明示することで、紹介、技術構成、リリース、運用の記事を一覧で分類できます。

title: "EX FOUNDRYのサイト構成"
path: "/entry/1002"
contentType: "architecture"
product: "ex-foundry"
tags: ["Vite", "GitHub Pages", "静的サイト"]

このメタデータは一覧カードの表示だけに使うわけではありません。同じ入力から記事詳細のcanonical URL、sitemap、Articleの構造化データも生成しています。そのため本文を書いてから手作業でURL一覧を更新するといった手順は不要で、公開対象として認識された記事は自動的に各出力へ反映されます。

ブラウザ側では記事本文を個別のHTMLファイルから読み込むため、トップページのJavaScriptに全記事本文を含めることはしません。検索や分類は記事メタデータだけで実行します。こうすることで、トップページを開くために全記事を先に取得する必要がなくなり、一覧で見せたい情報と詳細ページで読む情報をきれいに分離できます。

記事の種類はプロダクト、技術構成、リリース、運用の4つに分けています。これは見た目だけのラベルではなく、同じ内容を複数ページへコピーしないための編集上の境界でもあります。プロダクトの現在の説明は紹介記事に集約し、変更の履歴はリリース記事へ、構成の理由は技術構成記事へ置くようにしています。

GitHub Pagesを選んだ理由

EX FOUNDRYの案内ページと記事は、リクエストごとのサーバー処理を必要としません。既知のURLをビルド時に生成できるため、GitHub Pagesの静的配信で構成を小さく保てます。訪問者ごとにデータベースを検索したり、ログインセッションを作ったりするサイトではないので、ページをファイルとして配信する方式が要件に合っています。

GitHub Actionsでは、変更をpushすると pnpm verify でフォーマット、型チェック、テスト、ビルドを実行します。成功した成果物だけをPagesへデプロイするため、手元の環境に依存しない公開手順になっています。特にコンテンツを変更したときは、Markdownのfront matterの誤り、リンク先の不備、sitemapからの漏れ、静的HTMLに記事本文が含まれない問題などをビルドで検出できます。

GitHub Pagesを採用したからといって、動的なプロダクトにまで同じ方式を強制するわけではありません。NPB Analysisのように検索条件ごとにSQLiteを読むものは、別の実行環境を使います。EX FOUNDRYは、プロダクトの構成を説明する場所として、静的サイトの制約と動的アプリケーションが必要になる条件の両方を公開しています。

プロダクト側との違い

NPB AnalysisのようにSQLiteとSSRを必要とするプロダクトは、EX FOUNDRYと同じ静的構成を採用していません。プロダクトごとに必要な実行環境を選び、EX FOUNDRY自身はその違いを説明する側に回ります。

構成を統一することよりも、要件に対して過不足のない配信方式を選べることを優先しています。情報サイトがデータベースを持つと更新経路や障害点が増えますし、逆に検索アプリケーションをすべて静的ページへ変換すると、更新のたびに大量のページを生成し直す必要が出てきます。機能の性質に応じて構成を変え、その選択理由を記事に残しておくことが、サイト全体の説明責任につながると考えています。