logo hsb.horse

Architecture Decision Record

軽量な実用メモを管理する Snippets コレクション導入方針

ブログほど長くない実用メモを snippets に分離し、/snippets と /{lang}/snippets で一覧・詳細を提供する。

採用 #content #snippets #blog #information-architecture #seo

軽量な実用メモを管理する Snippets コレクション導入方針

Decision

  • 背景説明が短い実用メモ(コマンド断片、最小手順、短い設定例)は snippets に配置する。
  • 時系列で読む記事は blog、定義・知識整理は glossary、実用断片は snippets として3分類で運用する。
  • snippets コレクションを追加し、/snippets/{lang}/snippets に一覧と詳細ページを実装する。
  • テンプレートは _template.ja.md を配置し、_ 始まり除外ルールで公開対象から外す。

Context

既存運用では、次のような短い実用メモの置き場が曖昧だった。

  • ブログとしては分量が薄い
  • 用語集としては定義ページではない

この種のメモを blog に混在させると、記事一覧の意図と検索意図がぶれやすい。
一方 glossary は概念整理向けであり、コマンド断片中心の内容とは性質が異なる。

Options

  • Option A: 短い実用メモも blog に統一する。
  • Option B: glossary に含める。
  • Option C: snippets を新設して分離する(採用)。

Rationale

  • 読者の期待値に合わせて、入口を「記事」「知識」「実用断片」で分けられる。
  • 短いメモを独立させることで、blog の記事品質基準を維持しやすい。
  • URL を分離することで、検索エンジンにもページ意図を伝えやすい。

Consequences

  • src/content.config.tssnippets コレクション定義を追加する。
  • src/features/snippets/*src/pages/snippets/*src/pages/[lang]/snippets* を追加する。
  • ヘッダーナビと i18n 辞書に snippets 文言を追加する。
  • 初回コンテンツとして avifenc の一括変換メモを content/snippets/ に移行する。