decisiondecided

HTMLツールをpublic配下に配置し記事内リンクで参照する

HTML製の小規模ツールはpublic/tools/配下に静的配置し、記事一覧には出さず必要な記事本文からリンクする方針を採用する。

コンテキスト

ADR管理を主目的とする本サイトとは別に、HTML/CSS/JS で作った小規模ツール(プロジェクト用アプリ等)の置き場所が必要になった。以下の制約がある。

  • ミニマルなブログ構成を崩したくない
  • 今後何を追加するか未定(数も種類も予測不能)
  • 新規サーバー・別プロジェクト立ち上げは過剰
  • ツールは記事ではなく、記事一覧に混ぜたくない

選択肢

案配置一覧化汚染度
Baseline (A) 別Pagesプロジェクトを立てる別リポジトリ─0(分離)
B public/tools/ 配下に置く + 記事本文からリンク同プロジェクトなし+
C public/tools/ + 専用一覧ページ src/pages/tools.astro同プロジェクトあり(手動)++
D src/content/ にツール用 collection 追加、自動一覧化同プロジェクトあり(自動)+++

評価(Pugh Matrix)

評価軸:

  • C1: 追加時の手間の少なさ
  • C2: ミニマル構成の維持
  • C3: 拡張余地
  • C4: 記事一覧を汚さない
案C1C2C3C4合計
Baseline (A)00000
B+++++++6
C+0+++3
D-—+++0

決定

案B を採用する。HTML ツールは public/tools/<slug>/ に配置し、一覧ページは作らない。参照は該当ツールに言及する記事本文から通常の Markdown リンクで行う。

配置規約

public/
└── tools/
├── <tool-slug>/
│ ├── index.html
│ ├── app.js
│ └── style.css
└── ...
  • ツール slug は小文字英数字とハイフン
  • 各ツールは自己完結(外部 JS/CSS への依存は CDN + SRI で許容)
  • public/ 配下は Astro のビルドを通らず、そのまま静的配信される

参照方法

ツールを紹介・利用する記事の本文中で、通常の Markdown リンクとして記述する。

[Regex Tester](/tools/regex-tester/) で確認できる。

一覧ページ・ナビゲーション・サイドバーには載せない。存在を知る導線は記事本文のみ。

根拠

  • 完全フラット構造原則との整合: ツールは frontmatter を持たず、記事 collection に混ざらない。NormalizedEntry の対象外なので schema・派生値計算に影響ゼロ
  • ビルド影響ゼロ: public/ はコピーされるだけでビルドパイプラインを通らない。ツール数が増えてもビルド時間は増えない
  • YAGNI: 一覧ページや自動化は「必要になってから」導入すればよい。案 C/D への移行はいつでも可能
  • ADR 的思想との親和性: ツールを紹介する記事は自然と「なぜ作ったか」を含む decision/reference になり、記事 = ツールの文脈となる

帰結

良い影響

  • 記事一覧・RSS・sitemap にツールが混入しない
  • schema 変更不要、src/ 側に手を入れずツール追加可能
  • ツールを削除するときも public/tools/<slug>/ を消すだけ

許容するトレードオフ

  • ツール一覧は存在しない。ユーザーがツールに到達するには関連記事経由が必須
  • 記事化されないツールは実質「URL を知っている人のみアクセス可能」な状態になる(意図的な挙動として許容)
  • ツール数が 10 を超えたあたりで一覧が欲しくなる可能性はある。その時点で再判断する

将来の再検討トリガー

  • ツール数が 10 を超え、記事横断で参照したくなった場合 → 案 C(手動一覧)へ移行
  • ツールごとにメタデータ(タグ・説明・作成日)を持たせて分類したくなった場合 → 案 D(Content Collection 化)を検討

静的サイト側の技術的背景は 静的サイトの仕組みと配信方式の比較 を参照。