logo hsb.horse

Architecture Decision Record

Snippets collection policy for lightweight practical notes

Separate practical notes that are too short for blog posts into snippets, with index/detail routes at /snippets and /{lang}/snippets.

Accepted #content #snippets #blog #information-architecture #seo

Snippets collection policy for lightweight practical notes

Decision

  • Place lightweight practical notes (command fragments, minimal procedures, short config examples) in snippets.
  • Operate with three content types: timeline posts in blog, knowledge/definitions in glossary, and practical fragments in snippets.
  • Add the snippets collection and implement index/detail routes at /snippets and /{lang}/snippets.
  • Keep _template.ja.md in the collection and exclude _-prefixed files from publication.

Context

The current content model had no clear home for short practical notes:

  • Too thin for a blog post
  • Not a definition page for glossary

Mixing these into blog blurs list intent and search intent.
At the same time, glossary is definition-oriented and does not fit command-centric snippets.

Options

  • Option A: Keep short practical notes in blog.
  • Option B: Put them under glossary.
  • Option C: Add a dedicated snippets collection (chosen).

Rationale

  • Readers get clearer entry points: posts, knowledge, and practical snippets.
  • Isolating short notes helps preserve the quality bar of blog articles.
  • URL separation improves clarity of page intent for search engines.

Consequences

  • Add a snippets collection schema in src/content.config.ts.
  • Add src/features/snippets/*, src/pages/snippets/*, and src/pages/[lang]/snippets*.
  • Add snippets labels to header navigation and i18n dictionaries.
  • Migrate the first content item (avifenc batch conversion memo) into content/snippets/.