웹사이트 검색

개요

Quarto는 웹사이트와 책에 대한 전체 텍스트 검색을 지원합니다. 기본적으로 Quarto는 사이트 콘텐츠를 자동으로 인덱싱하고, 로컬에서 생성한 인덱스를 사용해 검색할 수 있게 합니다. 또한 Quarto 검색을 호스팅된 Algolia 인덱스를 사용하도록 구성할 수 있습니다.

검색 표시

검색은 웹사이트와 책에서 기본 활성화됩니다. 사이트에 내비게이션 바가 있으면 검색 UI가 내비게이션 바에 표시되고, 없으면 사이드바에 표시됩니다. 다음 옵션으로 검색 위치를 제어할 수 있습니다:

옵션	설명
`location`	`navbar` 또는 `sidebar`(페이지에 내비게이션 바가 있으면 기본값 `navbar`).
`type`	`overlay` 또는 `textbox`(`overlay`는 버튼 클릭 시 검색 UI가 팝업되고, `textbox`는 인라인 검색).

예:

website:
  search: 
    location: navbar
    type: overlay

위 예시는 기본 동작과 동일하므로 명시적으로 지정할 필요는 없습니다. 또한 웹사이트에서 검색은 기본 활성화이며(search: false로 비활성화 가능) 기본값입니다.

overlay 옵션은 다음과 같이 검색 UI를 표시합니다:

Algolia 검색 오버레이가 'detached' 모드로 표시된 Quarto 페이지. 검색 다이얼로그 뒤 웹페이지가 어두워지고, 다이얼로그에는 입력 필드와 일치 문서 목록 및 미리보기가 표시됩니다.

textbox 옵션은 다음과 같이 표시됩니다:

내비게이션 바에 텍스트박스 형태의 Algolia 검색. 검색 다이얼로그가 오른쪽에서 텍스트박스 확장 형태로 드롭다운 표시됩니다.

검색을 텍스트박스로 표시할 때 기본적으로 자리 표시자 텍스트가 없습니다. 최상위 language 옵션의 search-text-placeholder 키로 자리 표시자 텍스트를 지정할 수 있습니다(이 옵션은 website 안이 아니라 최상위에 위치함):

language: 
  search-text-placeholder: Search

키보드 단축키

검색 UI를 클릭하는 것 외에도 s, f, / 단축키로 검색을 활성화할 수 있습니다. keyboard-shortcut 옵션으로 단축키를 변경할 수 있습니다. 예를 들어 아래 설정은 ? 또는 H로 검색을 활성화합니다:

website:
  search:
    keyboard-shortcut: ["?", "H"]

결과 사용자 정의

다음 search 옵션으로 검색 결과 표시 방식을 사용자 정의할 수 있습니다:

옵션	설명 \|
`limit`	검색 결과에 표시할 결과 수. 기본값 20. \|
`collapse-after`	문서에서 일치하는 섹션 중 몇 개까지 표시하고 이후를 ‘more matches’ 링크 뒤에 숨길지 설정. 기본값 2. \| \|
`copy-button`	true이면 검색 텍스트박스에 작은 아이콘이 포함되어, 클릭 시 검색 결과 URL을 클립보드에 복사합니다(검색 결과를 공유하고 싶을 때 유용). 기본값 false. \| \|
`show-item-context`	검색 결과 항목 옆에 페이지 상위 컨텍스트를 표시할지 제어합니다. `tree`, `parent`, `root` 또는 boolean 사용(true인 경우 기본값 `tree`). 예: `tree`는 “Guide > Authoring > Figures” 형태: \| \|

Algolia 사용

내장 검색 외에도 Quarto 웹사이트는 외부 Algolia 검색 인덱스를 사용하도록 구성할 수 있습니다. 웹사이트를 렌더링하면 Quarto가 JSON 파일(사이트 출력 디렉터리의 search.json)을 생성하며, 이 파일을 Algolia 인덱스 업데이트에 사용할 수 있습니다. Algolia에서 인덱스를 만드는 방법은 Send and Update Your Data 문서를 참고하세요.

기본 구성

Quarto가 Algolia 인덱스에 연결하려면 Quarto 프로젝트 파일에 기본 연결 정보를 제공해야 합니다. Algolia 대시보드의 API Keys 섹션에서 연결 정보를 확인할 수 있습니다. 필요한 기본 연결 정보는 다음과 같습니다:

옵션	설명 \|
`index-name`	검색에 사용할 인덱스 이름. \|
`application-id`	Algolia가 애플리케이션을 식별하는 고유 ID. \|
`search-only-api-key`	Algolia에 연결할 Search-Only API 키. \| Important Search Only API 키를 사용하세요. 이 키는 인덱스에 대한 읽기 전용 접근을 제공하며 프로젝트 파일에 포함해도 안전합니다. Admin API 키는 Quarto 문서나 프로젝트에 절대 사용하지 마세요. \|
`show-logo`	검색 결과 푸터에 ‘search by Algolia’ 로고를 표시합니다. \|

예:

website:
  search:
    algolia:
      index-name: <my-index-name>
      application-id: <my-application-id>
      search-only-api-key: <my-search-only-api-key>

사용자 정의 인덱스 스키마

Quarto가 생성한 search.json을 Algolia 인덱스로 그대로 사용하는 경우, 위의 구성만으로 충분합니다.

하지만 다른 방식으로 인덱스를 생성하는 경우 검색에 사용할 필드를 추가로 지정해야 할 수 있습니다. algolia 아래에 index-fields 키를 추가하고 인덱스의 필드 이름을 지정합니다.

옵션	설명 \|
`href`	인덱스 항목의 URL을 읽을 필드. 사용자가 검색 결과를 선택하면 이 URL로 이동합니다. Quarto는 URL(그룹화 시 앵커 제외) 기준으로 결과를 그룹화합니다. \| 이 필드는 필수입니다(인덱스의 기존 필드 또는 매핑된 필드 이름으로 제공). \|
`title`	인덱스 항목의 제목을 읽을 필드. \| 이 필드는 필수입니다(인덱스의 기존 필드 또는 매핑된 필드 이름으로 제공). \|
`text`	인덱스 항목의 텍스트를 읽을 필드. \| 이 필드는 필수입니다(인덱스의 기존 필드 또는 매핑된 필드 이름으로 제공). \|
`section`	인덱스 항목의 섹션을 읽을 필드. Quarto는 URL로 결과를 그룹화하고, 섹션 정보가 있으면 동일 문서의 일치하는 하위 섹션을 표시합니다. \| 이 필드는 선택 사항입니다.

위 옵션 중 일부 또는 모두를 Quarto 프로젝트 파일에 지정할 수 있습니다. 예:

website:
  search:
    algolia:
      index-name: <my-index-name>
      application-id: <my-application-id>
      search-only-api-key: <my-search-only-api-key>
      index-fields:
        href: url
        section: sec
        text: body

Algolia Insights

기본적으로 Algolia는 검색 성능에 대한 다양한 인사이트를 제공합니다. 추가로 결과 조회/클릭에 대한 더 자세한 추적이 필요할 수도 있습니다. analytics-events를 true로 설정하면 Algolia의 클릭/전환 추적을 활성화할 수 있습니다:

website:
  search:
    algolia:
      index-name: <my-index-name>
      application-id: <my-application-id>
      search-only-api-key: <my-search-only-api-key>
      analytics-events: true

이벤트가 Algolia로 제대로 전송되는지는 Event Debugger에서 확인할 수 있습니다. 클릭/전환 이벤트는 쿠키로 익명 사용자 식별자를 유지합니다. 쿠키 동의가 활성화되어 있으면 쿠키 동의가 허용된 경우에만 검색 이벤트가 활성화됩니다.

고급 구성

위 설정 외에도 검색 실행 시 Algolia 전용 파라미터를 전달할 수 있습니다. 예를 들어 특정 facet이나 태그 집합으로 결과를 제한할 수 있습니다. 파라미터를 지정하려면 algolia YAML에 params 키를 추가하고 파라미터를 제공합니다. 사용 가능한 파라미터는 Algolia Search API Parameters 문서를 참고하세요.

예:

website:
  search:
    algolia:
      index-name: <my-index-name>
      application-id: <my-application-id>
      search-only-api-key: <my-search-only-api-key>
      index-fields:
        href: url
        section: sec
        text: body
      params:
        tagFilters: ['tag1','tag2']

검색 비활성화/강제 포함

개별 문서에서 검색을 비활성화하려면 문서 메타데이터에 search: false를 추가합니다. 예:

---
title: "My Document"
search: false
---

웹사이트 전체의 검색을 비활성화하려면 _quarto.yml에 다음을 포함합니다:

website:
  search: false

개별 요소 강제 포함

일반적으로 검색에 포함되지 않는 요소를 포함해야 한다면 해당 요소에 quarto-include-in-search-index 클래스를 추가하세요. 문단 일부만 포함하려면 텍스트를 span 또는 div로 감싸고 해당 요소에 클래스를 추가합니다.