Pagefind 완전 설명 — Rust + WASM 정적 검색 엔진

한 줄 정의

정적 사이트(Static Site)를 위한 서버리스 전문 검색 엔진. Rust로 작성되고 WebAssembly로 브라우저에서 실행된다.

1. 탄생 배경

정적 사이트(GitHub Pages, Netlify 등)는 서버가 없다. 서버가 없으니 검색 쿼리를 처리할 백엔드도 없다. 기존 해결책들의 문제:

Pagefind는 이 모든 문제를 해결하기 위해 2022년 CloudCannon이 만들었다.

2. 핵심 작동 원리

2단계로 작동한다: 빌드 타임 + 런타임

빌드 타임 (인덱싱)

Zola/Jekyll 등으로 사이트를 빌드한 뒤 Pagefind CLI를 실행하면:

npx pagefind --site public

1. public/ 안의 모든 .html 파일을 읽는다
2. 각 페이지의 텍스트를 추출, 역색인(Inverted Index) 을 만든다
3. 역색인을 알파벳/음절 단위 청크 파일로 분할해 저장한다

public/pagefind/
  ├── pagefind.js          (~30KB, WASM 로더)
  ├── pagefind.wasm        (Rust 컴파일 검색 엔진)
  ├── index_a.pf_index     ("a"로 시작하는 단어들의 역색인)
  ├── index_r.pf_index     ("rust", "rayon" 등)
  ├── index_n.pf_index     ("network", "node" 등)
  └── data_xxxxx.pf_meta   (문서 제목, URL, 스니펫)

런타임 (검색)

사용자가 "rust" 를 입력하면:

① pagefind.js 초기화 (첫 focus 시 1회만, ~30KB)
       ↓
② "r"로 시작하는 청크 파일 1개만 fetch (index_r.pf_index, ~10KB)
       ↓
③ WASM 바이너리에서 역색인 조회 (네이티브 속도)
       ↓
④ "rust" 포함 문서 ID 목록 + 관련도 점수 반환
       ↓
⑤ 상위 5개 문서의 메타데이터(제목, URL, 스니펫) fetch
       ↓
⑥ JavaScript가 결과를 DOM에 렌더링

이 과정에서 브라우저 메모리에 올라온 데이터: ~50KB — 글이 10개든 10만 개든 동일.

3. 왜 메모리가 항상 일정한가

lunr.js : 메모리 = O(N)   (글 수에 선형 비례)
Pagefind: 메모리 = O(1)   (검색 1회당 청크 1~2개 고정)

도서관 비유:

• lunr.js: 도서관 모든 책의 색인을 통째로 복사해서 가방에 넣고 검색한다
• Pagefind: 색인 카드를 ㄱ/ㄴ/ㄷ... 서랍으로 나눠두고, 해당 서랍 하나만 꺼낸다

역색인 구조:

빌드 타임 생성:
  "rust"    → [문서 B (8%), 문서 D (20%)]
  "base64"  → [문서 A (15%)]
  "network" → [문서 A (5%), 문서 C (12%)]

→ index_r.pf_index 에는 "r"로 시작하는 단어 역색인만 저장 (~10KB)

런타임:
  "rust" 입력
  → index_r 1개 fetch (~10KB)
  → WASM 조회
  → 결과 반환 (총 메모리: ~50KB)

4. 왜 Rust + WASM인가

Pagefind의 .pf_index 파일은 JSON이 아닌 바이너리 포맷으로, WASM이 이를 파싱·조회하는 작업을 JS 대비 2~10배 빠르게 처리한다.

Rust를 선택한 이유:

5. 클라이언트 사이드 메모리 비교

6. 실제 성능 수치

7. 주요 특징

8. HTML 연동 방법

<!-- 검색 입력창 -->
<input type="text" id="pagefind-search" placeholder="Search...">
<div id="pagefind-dropdown"></div>

<script>
var pagefind = null;

// Focus 시 lazy load — 한 번만 실행
async function initPagefind() {
  if (pagefind) return;
  try {
    pagefind = await import('/pagefind/pagefind.js');
  } catch(e) {
    console.log('Pagefind not available');
  }
}

// 검색 실행
async function search(query) {
  if (!query || !pagefind) return;
  const result = await pagefind.search(query);
  const data = await Promise.all(
    result.results.slice(0, 5).map(r => r.data())
  );
  renderResults(data);
}

function renderResults(results) {
  const drop = document.getElementById('pagefind-dropdown');
  drop.innerHTML = results.map(r =>
    `<a href="${r.url}">${r.meta.title}</a>`
  ).join('');
}

document.getElementById('pagefind-search')
  .addEventListener('focus', initPagefind);

var timer;
document.getElementById('pagefind-search')
  .addEventListener('input', function() {
    clearTimeout(timer);
    timer = setTimeout(() => search(this.value.trim()), 200);
  });
</script>

특정 요소 인덱싱 제어

<!-- 이 요소만 인덱싱 (나머지 제외) -->
<article data-pagefind-body>
  ...본문...
</article>

<!-- 이 요소는 인덱싱에서 제외 -->
<nav data-pagefind-ignore>...</nav>

<!-- 커스텀 메타데이터 추가 -->
<span data-pagefind-meta="author">홍길동</span>

9. 한계

10. 사용 적합성

🧒 어린이를 위한 설명

Pagefind는 도서관 사서 같은 존재예요.

1. 사서가 색인 카드를 만든다 (빌드 타임): 도서관(사이트)이 완성되면, 사서(Pagefind)가 모든 책을 읽고 "이 책에는 'rust'라는 단어가 있어!"라고 카드를 ㄱ/ㄴ/ㄷ 서랍에 정리한다.

2. 손님이 단어를 말하면 (런타임): "rust 찾아줘"라고 하면, 사서는 'ㄹ' 서랍(~10KB)만 열어서 바로 찾아준다. 책이 100만 권이어도 그 서랍만 열면 된다.

3. 서버가 필요 없다: 사서(카드 색인)가 이미 정리돼 있어서, 도서관장(서버)이 없어도 손님이 직접 서랍을 열어볼 수 있다.

참고

• Pagefind 공식 문서
• Pagefind GitHub
• CloudCannon 블로그 — Pagefind 소개