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/로 이관한다.