Pagefind(Indexing)

Indexing 기본 개념

Pagefind는 빌드 시점에 HTML 파일을 분석하여
검색에 사용할 정적 인덱스를 생성합니다.

이 과정은 서버나 백엔드 없이 수행되며,
생성된 인덱스는 배포된 정적 파일에 포함되어
사용자 브라우저에서 직접 검색에 활용됩니다.

기본적으로 Pagefind는
각 HTML 페이지를 하나의 검색 문서(document)로 취급합니다.

기본 인덱싱 동작

별도의 설정이 없는 경우 Pagefind의 기본 동작은 다음과 같습니다.

• 각 HTML 페이지는 하나의 검색 문서로 처리됨
• body 태그 내부의 텍스트가 자동으로 인덱싱됨
• nav, footer, script, form 등의 일부 요소는 기본적으로 제외됨
• 각 페이지는 검색 결과 카드 단위로 노출됨

즉,
아무 설정도 하지 않으면
”페이지 전체가 검색 대상”이 됩니다.

data-pagefind-body 를 통한 인덱싱 범위 제한

페이지 전체가 아닌
특정 영역만 검색 대상에 포함하고 싶을 경우
data-pagefind-body 속성을 사용할 수 있습니다.

이 속성이 적용된 요소 내부의 콘텐츠만
Pagefind의 검색 인덱스로 수집됩니다.

data-pagefind-body 의 의미

• data-pagefind-body가 존재하는 페이지는
  명시적으로 인덱싱 대상이 됨
• 해당 속성이 없는 페이지는
  검색 결과에 포함되지 않음
• Pagefind는 body 전체가 아닌
  지정된 영역만을 “본문”으로 인식함

이는
검색 대상 페이지를 명확히 통제하고 싶을 때
유용한 방식입니다.

복수 data-pagefind-body

한 페이지에 여러 개의 data-pagefind-body가 존재할 경우,
각 영역의 텍스트는 하나의 검색 문서로 병합되어 인덱싱됩니다.

이를 통해

• 본문
• 부가 설명
• 하단 요약 영역

등을 분리하면서도
하나의 검색 결과로 구성할 수 있습니다.

data-pagefind-ignore 옵션 이해하기

Pagefind는 인덱싱 과정에서
특정 요소를 제외하기 위해
data-pagefind-ignore 속성을 제공합니다.

이 속성은
“무엇을 얼마나 무시할 것인가”에 따라
두 가지 동작 모드를 가집니다.

기본 동작: data-pagefind-ignore (index)

data-pagefind-ignore에 값을 지정하지 않으면
기본값은 index입니다.

이 설정은
텍스트 검색 인덱스만 제외하고,
그 외의 정보 처리는 계속 수행합니다.

동작 방식 (index)

• 요소 내부 텍스트는 검색되지 않음
• 필터(data-pagefind-filter)는 처리됨
• 메타데이터(data-pagefind-meta)는 수집됨
• 페이지 제목(title) 및 대표 이미지(image) 추론에 사용될 수 있음

즉,
본문 검색에서는 제외되지만
페이지 정보를 구성하는 데에는 여전히 사용됩니다.

index 사용이 적합한 경우

• 사이드바 네비게이션
• 목차(TOC)
• 분류 정보가 포함된 영역
• 검색 결과 카드에 활용할 메타데이터나 이미지가 있는 영역

“본문 검색에는 필요 없지만,
페이지 정보로는 의미 있는 영역”에 적합합니다.

완전 제외: data-pagefind-ignore = all

data-pagefind-ignore에 all 값을 지정하면,
해당 요소와 그 자식 요소는
Pagefind의 모든 처리 대상에서 완전히 제외됩니다.

Pagefind는 이 영역을
존재하지 않는 것처럼 취급합니다.

동작 방식 (all)

• 텍스트 검색 인덱싱 제외
• 필터 처리 제외
• 메타데이터 수집 제외
• 제목 및 대표 이미지 추론 제외

all 사용이 적합한 경우

• 광고 영역
• 쿠키 배너
• UI 버튼, 토글
• 장식용 이미지
• 검색과 전혀 무관한 마크업

index 와 all 차이 요약

주의할 점

data-pagefind-ignore = all 내부에 있는 요소는
대표 이미지나 메타데이터로도 사용되지 않습니다.

대표 이미지나 메타데이터로 활용하고 싶다면
기본 data-pagefind-ignore(index) 설정을 사용해야 합니다.

정리

• data-pagefind-body 는
  “무엇을 검색 본문으로 볼 것인가”를 정의합니다.
• data-pagefind-ignore 는
  “무엇을 검색에서 제외할 것인가”를 정의합니다.
• index 는 검색어만 제외하고 정보는 유지합니다.
• all 은 모든 처리를 완전히 차단합니다.

실무에서는
”body로 포함 → ignore로 제외”
패턴을 기준으로 HTML 구조를 설계하는 것이 가장 안전합니다.

참조

• pagefind indexing