logo hsb.horse

Architecture Decision Record

Tools catalog management

Manage the tools list with YAML Content Collection and build individual tools as implemented pages.

Accepted #tools #content #architecture

Tools catalog management

Decision

  • Manage the /tools list with a Content Collection using YAML.
  • One YAML entry represents one tool’s metadata.
  • Store localized title / description inside the YAML entry.
  • Do not auto-generate /tools/<slug> pages from the catalog; build tool pages by implementation.
  • Treat url starting with / as internal links; otherwise as external links.
  • Keep categories flexible (not fixed enums).

Context

Tool pages require implementation (e.g., a UUID generator), so Markdown-based generation is not a fit. At the same time, the /tools list needs tags/categories for filtering and should be easy to update.

Alternatives

  • Markdown: unnecessary body content.
  • TS/JSON: type-safe but more code-oriented for updates.
  • External CMS: too heavy for a personal site.

Consequences

  • The list updates via YAML changes.
  • Tool pages remain free to implement.
  • category and tags can be used for search and filtering.