Astro 블로그 검색 붙이기, Pagefind가 잘 맞는 이유

기술 블로그에 글이 조금 쌓이면 검색이 필요해진다.

처음에는 카테고리와 태그만으로 충분하다.
하지만 글이 100개를 넘어가면 상황이 달라진다.

예전에 쓴 글이 분명히 있음
그런데 제목이 기억 안 남
태그도 애매함
결국 직접 검색하고 싶음

Astro처럼 정적으로 빌드되는 블로그에서는 서버 검색을 붙이기 애매하다.
이때 Pagefind가 꽤 잘 맞는다.

Pagefind는 정적 사이트 검색에 맞다

Pagefind의 핵심은 단순하다.

빌드된 HTML을 읽음
→ 검색 색인을 만듦
→ 브라우저에서 검색

즉 서버가 필요 없다.

Astro 블로그는 빌드 결과물이 dist에 만들어지므로,
그 결과물을 대상으로 색인을 만들면 된다.

astro build
→ dist 생성
→ pagefind 색인 생성
→ dist에 검색 파일 포함

이 흐름이 GitHub Pages 같은 정적 배포와 잘 맞는다.

자주 하는 실수는 Pagefind를 너무 일찍 실행하는 것이다.

Pagefind는 markdown 원본이 아니라,
최종 HTML을 읽어야 한다.

그래서 순서는 보통 이렇게 간다.

{
  "scripts": {
    "build": "astro check && astro build && node scripts/build-pagefind.cjs"
  }
}

핵심은 astro build 다음에 검색 색인을 만드는 것이다.

블로그 검색에서 중요한 건 대부분 글 본문이다.

반대로 이런 페이지는 검색에 들어가면 결과가 지저분해진다.

그래서 본문 영역에는 data-pagefind-body를 주고,
검색에서 빼고 싶은 영역에는 data-pagefind-ignore를 쓰는 식으로 정리하는 게 좋다.

예를 들어 글 상세 페이지에서는:

<main id="main-content" data-pagefind-body>
  <article id="article">
    <Content />
  </article>
</main>

반면 이전/다음 글 링크나 공유 버튼은 검색 결과에 섞이지 않아도 된다.

검색창 디자인은 나중에 고쳐도 된다.

처음 확인할 것은 이것이다.

1. 최신 글이 검색되는가
2. 제목으로 검색되는가
3. 본문 키워드로 검색되는가
4. 광고 문구가 검색 결과에 섞이지 않는가
5. 카테고리 페이지가 결과를 오염시키지 않는가

검색 기능은 “보이는 UI”보다 “찾히는 결과”가 더 중요하다.

기술 블로그는 영어 키워드와 한글 설명이 섞인다.

예를 들어 Astro 글이라면 이런 검색어를 테스트해봐야 한다.

Astro
Pagefind
검색
빌드
카테고리
frontmatter

영어만 잘 되는지 보면 한글 검색 품질을 놓칠 수 있다.

로컬에서는 잘 되는데 배포 후 검색이 깨지는 경우가 있다.

대부분은 검색 파일 경로 문제다.

예를 들어 Pagefind 결과물이 이런 식으로 들어간다.

dist/pagefind/
  pagefind.js
  pagefind-ui.css
  pagefind-entry.json

배포 결과에 이 폴더가 포함되어 있어야 검색 UI가 정상 동작한다.

GitHub Pages에 올릴 때는 dist 전체가 배포되는지 확인해야 한다.

검색이 안 될 때는 브라우저 콘솔에서 이런 부분을 본다.

pagefind.js 404
pagefind-entry.json 404
MIME type error
base path mismatch

검색어 입력 UI가 떠도,
색인 파일을 못 읽으면 결과는 나오지 않는다.

Astro 블로그 검색은 서버를 붙이는 것보다
빌드 결과물에 정적 검색 색인을 붙이는 방식이 단순하다.

Pagefind는 이 흐름에 잘 맞는다.

핵심은 세 가지다.

검색은 방문자가 오래된 글을 다시 찾게 해주는 기능이다.
글이 늘어날수록 효과가 커진다.

Astro 정적 블로그 검색은 Pagefind처럼 빌드 후 HTML을 색인하는 방식이 가장 단순하고 운영하기 좋다.