설정 사전: 검색과 콘텐츠 발견

$ 게시 2026-11-13 | | 수정 2026-11-14
컨텍스트: 실제 코드로 사이트 검색 설정, 문구, 개별 글 수록 규칙을 설명하며 검색, 최신 글, 관련 글, 태그, RSS, 기계 읽기 출력을 구분합니다.

검색 입구, 글 수록, 언어 인덱스와 다른 콘텐츠 입구입니다.


출력
단어 3.6k 토큰 4.7k

먼저 첫 글 쓰기를 읽고 로컬 미리보기·배포는 배포 가이드를 참고하세요. 설정 위치·설치는 첫 가이드, 다른 모듈은 설정 사전 시작 페이지에 있습니다.

두 가지를 구분합니다. 검색창은 빌드한 인덱스에서 글을 찾고 홈 최신 글, 태그, 글 하단 추천, RSS는 다른 입구이며 검색 스위치 하나로 제어하지 않습니다. 기본값은 demo 덮어쓰기가 아닌 테마 패키지 기준입니다.

theme.search.enabled: 사이트 전체 검색 스위치

  • 타입 / 기본값: boolean / true.
  • 상태와 역할: 적용됩니다. 공용 헤더에 검색 입구를 표시하고 참여 글에 인덱스 표식을 출력하며 빌드 후 정적 Pagefind 자원을 만듭니다.
  • 제한: false는 표준 헤더 입구와 이번 빌드 인덱스 생성을 함께 끕니다. 개별 search: true로 전역 꺼짐을 우회할 수 없습니다. 글 삭제, 검색 엔진 수록 차단, 이전 호스팅 인덱스 삭제를 뜻하지 않습니다.
  • 예시: theme: { search: { enabled: false } }.

theme.search의 유일한 공개 말단 필드입니다. 서비스 주소, API key, 인덱스 경로, 결과 정렬, 키워드 가중치, 언어 간 검색 스위치는 없습니다. 빌드 시 Pagefind를 사용하므로 별도 검색 백엔드를 운영할 필요는 없습니다.

개별 글 search: site.config 필드가 아닙니다

위치 타입 / 기본값 상태·역할·제한 예시
src/content/blog/<locale>/some-post.md의 frontmatter.search boolean, 생략 가능 / schema에는 미설정이며 글 레이아웃 기본 true 조건부 적용: 전역 검색이 켜졌을 때 글 인덱스 루트 표식을 출력할지 정합니다. false여도 목록, 관련 글, RSS, 기계 읽기 출력, 공개 주소에는 영향이 없습니다. search: false

해당 글만 사이트 검색에서 빼려면 기존 frontmatter에 추가하세요.

search: false

theme.search: false나 site.config 최상위 search: false로 쓰지 마세요. frontmatter.search는 비공개 스위치도 아닙니다. 현재 draft·미래 게시일 필터는 없으므로 미공개 콘텐츠는 컬렉션 밖에 두세요. 전체 필드는 글 사전에 있습니다.

어떤 콘텐츠가 인덱스에 들어가나요?

표준 글 레이아웃은 전역·개별 스위치가 모두 허용하면 data-anglefeint-search 루트 표식을 출력합니다. 현재 명시된 본문 영역은 제목, 보이는 부제, 본문입니다. 부제와 같은 context는 부제 위치에서 한 번만 처리하며 모든 context의 별도 필드 인덱스는 아닙니다.

내비게이션, 플레이어, 푸터, 댓글, 관련 글은 본문에 함께 넣지 않습니다. frontmatter.description은 이 UI가 직접 쓰는 결과 요약이 아니며 태그도 설정 가능한 검색 필터가 아닙니다. 결과는 Pagefind의 제목 메타데이터와 본문 요약을 사용합니다. 이미지 픽셀·영상·오디오 속 글자를 OCR·전사하지 않습니다.

기본 About, Fragments, Decoder, 홈, 목록은 글 인덱스 루트 표식이 없으므로 검색을 켜도 자동으로 결과가 되지 않습니다. 사용자 페이지는 직접 인덱스 표식 규약을 따라야 하며 존재하지 않는 site.config 필드 하나로 켤 수는 없습니다.

messages.search: 열한 검색 문구

전체 접두사는 i18n.locales.<locale>.messages.search.입니다. 모두 생략 가능한 string이며 현재 언어 내장 문구와 대체 연결을 사용합니다. 표에는 중국어 간체 / 영어 기본값을 나열하고 필드 예시 값은 한국어로 제공합니다. 모두 조건부 적용이며 검색 입구와 해당 UI·상태가 있을 때 사용합니다.

필드 중국어 간체 / 영어 기본값 역할·제한·자리표시자 한국어 예시 값
label 搜索 / Search 검색 버튼의 접근 가능한 이름, 안내, 팝업 제목입니다. 검색 키워드가 아닙니다. "글 검색"
close 关闭搜索 / Close search 닫기 버튼 이름과 안내입니다. 보이는 esc 안내와 아이콘은 구현이 고정합니다. "검색 닫기"
placeholder 搜索文章… / Search articles… 입력창 자리표시자와 접근성 라벨이며 키워드를 미리 채우지 않습니다. "검색할 단어 입력"
hint 搜索当前语言的文章。 / Search articles in the current language. 운영 환경에서 키워드를 입력하지 않았을 때 안내입니다. "현재 언어의 글을 검색합니다."
loading 正在搜索… / Searching… 검색·준비 중 안내이며 지연·자원 로드 전략은 바꾸지 않습니다. "검색 중…"
empty 没有找到匹配的文章。 / No matching articles. 결과 없음 안내이며 현재 언어에 인덱스가 없을 때도 나올 수 있습니다. "일치하는 글이 없습니다."
error 搜索加载失败,请重试。 / Search could not load. Please try again. 인덱스 manifest, 검색 모듈, 결과 상세 로드 실패 안내이며 빌드 오류 생성에 사용하지 않습니다. "현재 검색을 이용할 수 없습니다. 다시 시도하세요."
retry 重试 / Retry 실패 시 재시도 버튼입니다. 기존 검색 엔진을 다시 로드하며 브라우저에서 인덱스를 재생성하지 않습니다. "다시 불러오기"
more 加载更多 / Load more 미표시 결과의 추가 로드 버튼이며 배치 개수를 바꾸지 않습니다. "결과 더 보기"
results 找到 {count} 篇文章 / {count} articles found 결과 개수 안내입니다. 리터럴 {count} 첫 등장만 바꾸며 현재 표시 카드 수가 아닙니다. "총 {count}개의 글을 찾았습니다"
dev 本地完整搜索请先运行 npm run build,再运行 npm run preview。 / To test full search locally, run npm run build, then npm run preview. dev 모드 안내입니다. 개발 중 실제 검색하지 않으며 문구 변경으로 인덱스를 만들 수 없습니다. "빌드한 뒤 preview에서 검색을 확인하세요."

문구는 텍스트로 출력하며 설정 HTML을 실행하지 않습니다. 빈 문자열은 문구를 덮어쓰지만 버튼을 숨기지 않으며 접근 가능한 이름을 불명확하게 만들 수 있습니다. results의 {count}를 사용자 문장에 자동 추가하지 않으므로 숫자가 필요하면 한 번 유지하세요.

병합 가능한 설정 예시

src/site.config.ts의 기존 defineThemeConfig({…})에 합치고 import, export, 다른 개인 설정을 유지하며 theme·i18n을 중복 생성하지 마세요.

theme: { search: { enabled: true } },
i18n: {
  locales: {
    ko: {
      messages: {
        search: {
          label: '글 검색',
          placeholder: '검색할 단어 입력',
          results: '총 {count}개의 글을 찾았습니다',
          empty: '일치하는 글이 없습니다.',
        },
      },
    },
  },
},

언어, 자원 로드, 결과 표시

  • 빌드는 언어 목록 anglefeint.json과 Pagefind 모듈이 있는 pagefind/를 출력합니다. 검색을 열어야 목록·엔진을 로드하지만 UI 스크립트는 입구가 있는 페이지와 함께 로드합니다. 검색 코드 전체가 클릭까지 대기하는 것은 아닙니다.
  • 자원 경로는 Astro BASE_URL을 자동 포함합니다. HTML만 배포하거나 pagefind/를 빠뜨리거나 경로를 HTML로 잘못 재작성하면 실패할 수 있습니다. 독립적인 site.config 인덱스 경로 설정은 없습니다.
  • 클라이언트는 문서 html lang을 인덱스 목록과 대소문자 구분 없이 비교합니다. 현재 언어에 인덱스가 없으면 빈 결과이며 영어로 전환하지 않습니다. 페이지의 유효 언어값을 쓰고 문구의 대체 언어로 글을 찾지 않습니다.
  • 입력 후 약 200밀리초에 검색합니다. 중국어 IME 조합이 끝난 뒤 예약하며 폼 제출은 즉시 실행할 수 있습니다. 빈 키워드는 전문 검색하지 않습니다. 지연은 설정 필드도 원격 AI 요청도 아닙니다.
  • 배치당 상세 결과 최대 8개를 가져오고 “더 보기”로 이어갑니다. pageSize 설정은 없습니다. 개수 안내는 전체 결과 수이며 현재 배치 수가 아닙니다. 링크는 같은 출처만 유지하고 요약은 텍스트와 키워드 mark 강조만 허용하며 글의 임의 HTML을 렌더링하지 않습니다.
  • 결과 순서는 Pagefind가 반환합니다. 테마 정렬·추천 알고리즘 매개변수는 없습니다. 일반 번역 대체는 다른 언어 글을 결과에 넣지 않습니다.

언어 메타데이터, 활성화·비활성화, 대체값은 언어 사전을 참고하세요. search 문구는 UI만 바꾸며 언어 글을 만들거나 인덱스 언어를 바꾸지 않습니다.

dev에서 실제 검색이 없는 이유

인덱스는 Astro 빌드 후 생성하며 npm run dev는 이 단계를 실행하지 않습니다. 개발 환경은 messages.search.dev 안내를 표시하고 키워드가 있어도 실제 검색하지 않습니다. 현재 동작이며 검색 고장이나 설정 누락이 아닙니다.

콘텐츠를 준비하고 로컬에서 실행하세요.

npm run build
npm run preview

preview는 빌드 결과를 사용합니다. 글, 언어 메타데이터, 개별 참여 스위치, 사이트 경로를 바꾸고 새 인덱스를 보려면 재빌드해야 합니다. 정식 사이트에는 페이지와 pagefind 자원을 함께 배포하세요. dev에서 문구를 바꿔도 온라인 인덱스가 갱신된 것은 아닙니다.

색인할 글이 없어도 식별 가능한 빈 언어 목록을 만들며 UI는 빈 결과를 표시할 수 있습니다. 빌드 인덱스 실패는 오류를 내고 거짓 성공 인덱스를 조용히 게시하지 않습니다. 재시도는 기존 자원 읽기만 다시 하며 방문자 브라우저에서 빌드를 고치거나 없는 글을 만들 수 없습니다.

다른 콘텐츠 입구가 쓰는 설정

기존 모듈 필드·기본값을 사용하며 주 설명도 원래 사전에 있습니다. 새로운 검색 설정을 만들지 않습니다.

설정 경로 또는 위치 타입 / 기본값 역할·제한·예시 상세 설명
theme.homeLatestCount number / 3 홈 최신 글 수입니다. 예: theme: { homeLatestCount: 5 }. 검색 배치나 하단 관련 글 수는 바꾸지 않습니다. 홈 개수
theme.blogPageSize number / 10 Blog List·태그 목록 페이지당 수입니다. 예: theme: { blogPageSize: 8 }. 검색 결과 수가 아닙니다. 목록 페이지 나누기
theme.tags.enabled boolean / true 태그 입구·표준 페이지입니다. 예: theme: { tags: { enabled: false } }. 글 tags를 지우거나 전문 검색을 끄지 않습니다. 태그 스위치
글 frontmatter.tags string[], 생략 가능 / 미설정 태그 보관함·표시입니다. 예시 값 [‘Astro’, ‘에세이’]. 현재 관련 글의 관련도 계산이나 검색 허용 목록이 아닙니다. 글 필드
i18n.locales.<locale>.messages.blog.related string / 현재 언어 내장값, 아래 중국어 간체·영어 표 참조 하단 관련 글 제목 문구만 바꿉니다. 예시 값 ‘계속 읽기’. 글 문구
i18n.locales.<locale>.messages.blog.relatedAria string / 현재 언어 내장값, 아래 중국어 간체·영어 표 참조 관련 글 영역 접근 가능한 이름입니다. 예시 값 ‘다른 글’. 글 문구

관련 글은 현재 언어에서 자신을 뺀 최신 세 글입니다. 공통 태그, canonicalTopic, 유사도는 쓰지 않습니다. relatedCount, 관련 글 스위치, 수동 추천 목록의 site.config 필드는 없습니다. 다른 글이 없으면 숨깁니다. search: false인 글도 추천될 수 있습니다.

문구 중국어 간체 / 영어 기본값
messages.blog.related 相关文章 / Related
messages.blog.relatedAria 相关文章 / Related posts

RSS, SEO, 기계 읽기 출력은 사이트 검색과 다릅니다

입구 현재 동작과 설정 관계
/<locale>/rss.xml 활성 언어별 글 요약 구독입니다. 제목은 사이트 이름, 설명은 해당 messages.blog.archiveDescription입니다. 항목은 title, description, pubDate, 공개 경로에서 오며 search: false로 제외하지 않습니다. 전문 RSS는 아니며 theme.search 안에 RSS 스위치는 없습니다.
페이지 메타 정보·검색 엔진 사이트 검색 인덱스와 별개입니다. search: false는 noindex 추가·sitemap 끄기를 하지 않으므로 인터넷 검색 엔진 수집 제어에 쓰면 안 됩니다.
공개 기계 읽기 텍스트 글, About, Fragments는 자체 내보내기가 있으며 Pagefind 수록에 의존하지 않습니다. 언어별 공개 보충은 언어 사전을 참고하세요. search: false는 비공개 필터가 아닙니다.

사이트 이름, 도메인, 구독 설명은 실제 값을 쓰세요. 공개 주소·배포는 배포 가이드, RSS의 archiveDescription은 목록 문구에 있습니다. “사이트 검색 결과 없음”을 “공개하지 않음”으로 해석하지 마세요.

현재 전역·개별 search와 열한 검색 문구 모두 소비 위치가 있으며 입력해야 할 이전 검색 호환 필드는 없습니다. 미소비 글 필드 canonicalTopic 등을 검색 근처에 두어도 인덱스 분류가 되지 않습니다. 글 사전을 참고하세요. 언어 통합 검색, 이미지 OCR, 검색어 분석, 결과 가중치, 새 인덱스 타입 설정은 공개하지 않습니다.

설정 사전 시작 페이지에서 다른 모듈을 조회하세요.