Pagefind 사이트 검색 도입 방침

결정

• 사이트 전역 검색 엔진으로 Pagefind를 채택한다.
• 검색 라우트는 /search 및 /{lang}/search로 제공하며, html[lang] 기반의 언어별 인덱스를 사용한다.
• 빌드 파이프라인에서 astro build 이후 Pagefind 인덱싱을 필수 단계로 둔다.
• 헤더의 검색 진입 경로는 항상 현재 로케일의 검색 페이지로 연결한다.

배경

이 사이트는 완전 정적 배포 구조이며, 서버 측 검색 인프라를 추가하지 않고 전문 검색을 제공해야 한다. 또한 ja/en/ko/fr/de/pt 다국어 URL을 운영 중이므로 검색 결과 역시 언어 단위로 분리되는 것이 바람직하다.

옵션

• 옵션 A: 외부 호스팅 검색 서비스(SaaS) 도입
• 옵션 B: 커스텀 검색 API를 직접 구현 및 운영
• 옵션 C: 정적 인덱스를 생성하는 Pagefind 도입(채택)

근거

• Pagefind는 정적 HTML 생성 이후 실행되며 Astro 워크플로와 자연스럽게 맞는다.
• html[lang] 기반 언어별 인덱스 선택을 기본 기능으로 지원한다.
• 클라이언트 사이드 검색으로 운영 복잡도와 인프라 의존성을 늘리지 않는다.

영향

• 프로덕션 빌드에서는 dist/pagefind/ 생성이 필수다.
• 초기 검색 UI는 @pagefind/default-ui를 사용하고, 필요 시 이후 단계에서 커스텀 UI로 전환한다.
• 제외 셀렉터, 가중치, 메타데이터 강화 같은 품질 튜닝은 실제 사용 데이터를 본 뒤 확장한다.