버전: 3.9.2

검색

여러분의 웹사이트에 검색을 추가할 수 있는 몇 가지 옵션이 있습니다.

🥇 Algolia DocSearch (공식)
👥 Typesense DocSearch
👥 로컬 검색
👥 직접 만든 SearchBar 컴포넌트

정보

🥇 도큐사우루스는 Algolia DocSearch를 공식적으로 지원합니다.

👥 다른 옵션은 커뮤니티에서 유지보수합니다. 버그는 각 저장소에 제보해 주세요.

🥇 알골리아 DocSearch 사용하기

도큐사우루스는 Algolia DocSearch를 공식 지원합니다.

개발자 문서나 기술 블로그라면 이 서비스를 무료로 사용할 수 있습니다. 체크리스트를 읽고 DocSearch 프로그램에 신청하세요.

DocSearch는 웹사이트를 일주일에 한 번 크롤링하고(일정은 웹 화면에서 설정할 수 있습니다) 알골리아 인덱스의 모든 콘텐츠를 수집합니다. 웹 사이트에서는 알골리아 API를 사용해 수집된 콘텐츠에 대한 검색을 실행할 수 있습니다.

웹사이트가 무료 호스팅 버전 DocSearch의 이용 요건을 충족하지 못하거나, 방화벽 뒤에 있어 공개되지 않았다면 DocSearch 크롤러를 직접 실행할 수 있습니다.

참고

도큐사우루스 프리셋은 기본적으로 Algolia 크롤러가 사용할 수 있는 sitemap.xml을 생성합니다.

기존 DocSearch에서 이전하시나요?

기존 DocSearch 인프라에서 마이그레이션하는 방법은 블로그 글이나 DocSearch 마이그레이션 문서에서 확인할 수 있습니다.

색인 설정

애플리케이션이 승인되고 배포되면 프로젝트에 DocSearch를 추가하기 위해 필요한 모든 세부 사항이 담긴 이메일을 받게 됩니다. 웹 인터페이스에서 크롤링을 편집하고 관리할 수 있습니다. 인덱스는 배포 후 바로 사용할 수 있는 상태가 되기 때문에 별도 구성은 필요치 않습니다.

권장 크롤러 설정 사용하기

공식 도큐사우루스 v3 크롤러 설정을 사용하는 것을 강력히 권장합니다. 다른 크롤러 설정을 선택하면 지원해 드릴 수 없습니다.

크롤러 설정을 업데이트할 때

크롤러 설정에는 initialIndexSettings가 포함되며, Algolia 인덱스가 아직 없는 경우에만 이를 사용해 인덱스를 초기화합니다.

크롤러의 initialIndexSettings 설정을 업데이트하면 인터페이스에서 인덱스를 직접 갱신할 수 있습니다. 하지만 새 설정으로 완전히 다시 초기화하려면 Algolia 팀은 인덱스를 삭제한 후 크롤링을 다시 시작할 것을 권장합니다.

알골리아 연결하기

도큐사우루스의 @docusaurus/preset-classic은 Algolia DocSearch 연동을 지원합니다. classic preset을 사용한다면 추가적인 설치가 필요하지 않습니다.

@docusaurus/preset-classic을 사용하지 않을 때의 설치 단계

패키지를 설치합니다.

npm
Yarn
pnpm
Bun

npm install --save @docusaurus/theme-search-algolia

yarn add @docusaurus/theme-search-algolia

pnpm add @docusaurus/theme-search-algolia

bun add @docusaurus/theme-search-algolia

docusaurus.config.js에 테마를 등록하세요:

docusaurus.config.js
export default {
  title: 'My site',
  // ...
  themes: ['@docusaurus/theme-search-algolia'],
  themeConfig: {
    // ...
  },
};

그런 다음 themeConfig에 algolia 필드를 추가하세요. **DocSearch에 신청**하여 Algolia 인덱스와 API 키를 받으세요.

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      // Algolia에서 제공한 애플리케이션 ID
      appId: 'YOUR_APP_ID',

      // 공개 API 키: 저장소에 커밋해도 안전합니다
      apiKey: 'YOUR_SEARCH_API_KEY',

      indexName: 'YOUR_INDEX_NAME',

      // 선택 사항: 아래 문서 내용 참고
      contextualSearch: true,

      // 선택 사항: history.push 대신 window.location으로 이동할 도메인을 지정합니다. Algolia 설정이 여러 문서 사이트를 크롤링하고 window.location.href로 이동하려 할 때 유용합니다.
      externalUrlRegex: 'external\.com|domain\.com',

      // 선택 사항: Algolia 결과 항목 URL의 일부를 바꿉니다. 서로 다른 baseUrl로 배포한 여러 사이트에서 같은 검색 인덱스를 사용할 때 유용합니다. `from` 매개변수에는 정규식이나 문자열을 사용할 수 있습니다. 예: localhost:3000과 myCompany.com/docs
      replaceSearchResultPathname: {
        from: '/docs/', // 또는 정규식으로: /\/docs\//
        to: '/',
      },

      // 선택 사항: Algolia 검색 매개변수
      searchParameters: {},

      // 선택 사항: 기본적으로 활성화되는 검색 페이지의 경로(비활성화하려면 `false`)
      searchPagePath: 'search',

      // 선택 사항: DocSearch의 인사이트 기능 활성화 여부(기본값은 `false`)
      insights: false,

      // 선택 사항: 새로운 Ask AI 기능 사용 여부(기본값은 undefined)
      askAi: 'YOUR_ALGOLIA_ASK_AI_ASSISTANT_ID',

      //... 기타 Algolia 매개변수
    },
  },
};

정보

searchParameters 옵션은 도큐사우루스 v1에서 algoliaOptions라는 이름으로 사용되었습니다.

사용 가능한 값은 공식 DocSearch 문서를 참고하세요.

경고

알골리아에서 사이트를 크롤링할 때까지 검색 기능이 안정적으로 작동하지 않습니다.

주요 변경 후 검색이 동작하지 않으면 Algolia 대시보드에서 새 크롤링을 실행하세요.

상황별 검색 기능

컨텍스트 검색은 기본적으로 활성화됩니다.

검색 결과가 현재 언어 및 버전과 관련되도록 보장합니다.

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      contextualSearch: true,
    },
  },
};

문서 버전 2개(v1과 v2)와 언어 2개(en과 fr)가 있다고 가정해 보겠습니다.

v2 문서를 보고 있는데 v1 문서에 대한 검색 결과를 반환한다면 적절한 결과가 아니겠죠. v1과 v2 문서 내용은 어느 정도 비슷할 수 있습니다. 때문에 같은 질의에 대해 중복된 검색 결과가 나올 수 있습니다(버전 당 하나의 결과가 나오는 것이지요).

마찬가지로 프랑스어 사이트를 탐색하는데 영어 문서에 대한 검색 결과를 반환하는 것도 적절하지 않습니다.

이런 문제를 해결하기 위해 상황별 검색 기능은 현재 보고 있는 문서 버전과 언어를 이해하고 적절한 필터를 동적으로 만들어줍니다.

/en/docs/v1/myDoc에서는 v1 문서의 영어 결과만 검색됩니다(+ 버전이 없는 다른 페이지)
/fr/docs/v2/myDoc에서는 v2 문서의 프랑스어 결과만 검색됩니다(+ 버전이 없는 다른 페이지)

정보

contextualSearch: true(기본값)를 사용하면 컨텍스트 패싯 필터가 algolia.searchParameters.facetFilters로 제공된 필터와 병합됩니다.

특정 요구사항이 있다면 contextualSearch를 비활성화하고 자체 facetFilters를 정의할 수 있습니다:

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      contextualSearch: false,
      searchParameters: {
        facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
      },
    },
  },
};

관련 Algolia 패싯 문서를 참고하세요.

컨텍스트 검색이 동작하지 않나요?

컨텍스트 검색을 비활성화했을 때만 검색 결과가 나온다면 인덱스 설정 문제일 가능성이 매우 높습니다.

Ask AI

Ask AI는 문서에 관해 질문할 수 있는 새로운 기능입니다.

Ask AI는 문서에 AI의 기능을 더합니다:

대화형 검색: 사용자가 자연어로 질문하고 문맥에 맞는 답변을 받을 수 있습니다.
완전 무료: Ask AI 자체에는 추가 비용이 들지 않습니다. 사용하는 제공업체에 LLM 사용 요금만 지불하면 됩니다.
BYOLLM(자체 LLM 사용): 원하는 언어 모델 제공업체를 사용하여 AI 경험을 완전히 제어할 수 있습니다.
Algolia 인덱스와 직접 연동: 제공업체/모델이 Algolia 인덱스에서 관련 문맥을 직접 검색하므로 정확하고 최신인 답변을 제공합니다.
최근 질문 및 대화 기록: 최근 질문을 쉽게 다시 확인하고 이전 Ask AI 대화로 돌아갈 수 있습니다.
간편한 연동: 검색 모달에서 바로 Ask AI를 사용할 수 있습니다.

활성화하려면 algolia 설정에 askAi 필드를 추가하세요:

docusaurus.config.js
export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      askAi: 'YOUR_ALGOLIA_ASK_AI_ASSISTANT_ID',

      // 또는 사용자 정의 매개변수 사용
      askAi: {
        assistantId: 'YOUR_ALGOLIA_ASK_AI_ASSISTANT_ID',
        indexName: 'YOUR_ALGOLIA_INDEX_NAME',
        apiKey: 'YOUR_ALGOLIA_API_KEY',
        appId: 'YOUR_ALGOLIA_APP_ID',
        suggestedQuestions: true, // 선택 사항: 추천 질문 활성화(기본값: false)
      },

      //... 기타 Algolia 매개변수
    },
  },
};

정보

Ask AI를 사용하려면 Ask AI 어시스턴트가 활성화된 Algolia 인덱스가 필요합니다. Ask AI 설정 방법을 자세히 알아보세요.

알골리아 검색 기능에 스타일 적용하기

문서 검색 기능에 기본 제공되는 테마는 표준에 따라 색상, 고대비 등의 접근성을 지원하도록 설계됐습니다.

그래도 /src/css/custom.css 파일을 편집하여 도큐사우루스의 Infima CSS 변수를 재사용하면 DocSearch의 스타일을 지정할 수 있습니다.

/src/css/custom.css
[data-theme='light'] .DocSearch {
  /* --docsearch-primary-color: var(--ifm-color-primary); */
  /* --docsearch-text-color: var(--ifm-font-color-base); */
  --docsearch-muted-color: var(--ifm-color-secondary-darkest);
  --docsearch-container-background: rgba(94, 100, 112, 0.7);
  /* Modal */
  --docsearch-modal-background: var(--ifm-color-secondary-lighter);
  /* Search box */
  --docsearch-searchbox-background: var(--ifm-color-secondary);
  --docsearch-searchbox-focus-background: var(--ifm-color-white);
  /* Hit */
  --docsearch-hit-color: var(--ifm-font-color-base);
  --docsearch-hit-active-color: var(--ifm-color-white);
  --docsearch-hit-background: var(--ifm-color-white);
  /* Footer */
  --docsearch-footer-background: var(--ifm-color-white);
}

[data-theme='dark'] .DocSearch {
  --docsearch-text-color: var(--ifm-font-color-base);
  --docsearch-muted-color: var(--ifm-color-secondary-darkest);
  --docsearch-container-background: rgba(47, 55, 69, 0.7);
  /* Modal */
  --docsearch-modal-background: var(--ifm-background-color);
  /* Search box */
  --docsearch-searchbox-background: var(--ifm-background-color);
  --docsearch-searchbox-focus-background: var(--ifm-color-black);
  /* Hit */
  --docsearch-hit-color: var(--ifm-font-color-base);
  --docsearch-hit-active-color: var(--ifm-color-white);
  --docsearch-hit-background: var(--ifm-color-emphasis-100);
  /* Footer */
  --docsearch-footer-background: var(--ifm-background-surface-color);
  --docsearch-key-gradient: linear-gradient(
    -26.5deg,
    var(--ifm-color-emphasis-200) 0%,
    var(--ifm-color-emphasis-100) 100%
  );
}

알골리아 검색 기능 세부 설정하기

Algolia DocSearch는 docusaurus.config.js 파일의 algolia 필드에 전달할 수 있는 여러 옵션을 지원합니다.

docusaurus.config.js
export default {
  themeConfig: {
    // ...
    algolia: {
      apiKey: 'YOUR_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      // 옵션...
    },
  },
};

알골리아 검색 컴포넌트 바꾸기

Algolia 검색 리액트 컴포넌트를 편집하려면 @docusaurus/theme-search-algolia의 SearchBar 컴포넌트를 스위즐링하세요:

npm
Yarn
pnpm
Bun

npm run swizzle @docusaurus/theme-search-algolia SearchBar

yarn swizzle @docusaurus/theme-search-algolia SearchBar

pnpm run swizzle @docusaurus/theme-search-algolia SearchBar

bun run swizzle @docusaurus/theme-search-algolia SearchBar

문제 해결

도큐사우루스 사용자가 Algolia DocSearch를 사용할 때 가장 자주 겪는 문제를 정리했습니다.

검색 결과가 표시되지 않음

검색 결과가 표시되지 않는 현상은 보통 인덱스 설정 문제와 관련이 있습니다.

설정에 문제가 있는지 어떻게 확인하나요?

도큐사우루스는 컨텍스트 검색 기능에서 Algolia 패싯을 사용해 다음과 같은 동적 쿼리를 만듭니다:

[
  "language:en",
  [
    "docusaurus_tag:default",
    "docusaurus_tag:docs-default-3.2.1",
    "docusaurus_tag:docs-community-current",
    "docusaurus_tag:docs-docs-tests-current"
  ]
]

아래 스크린샷처럼 Algolia UI에서 인덱스의 docusaurus_tag, language, lang, version, type 필드에 패싯 쿼리를 생성할 수 있어야 합니다:

적절한 패싯 필드가 설정된 Algolia 인덱스

또는 {contextualSearch: false}로 컨텍스트 검색을 비활성화하면(권장하지는 않습니다) 도큐사우루스가 패싯 쿼리를 사용하지 않으므로 검색 결과가 표시될 것입니다.

권장 설정 사용하기

특정 크롤러 설정을 권장하는 데에는 충분한 이유가 있습니다. 다른 설정을 사용하기로 선택하면 지원해 드릴 수 없습니다.

다음 단계에 따라 인덱스 설정 문제를 해결할 수 있습니다:

권장 크롤러 설정을 사용합니다
UI에서 인덱스를 삭제합니다
UI에서 새 크롤링을 실행합니다
인덱스가 적절한 패싯 필드(docusaurus_tag, language, lang, version, type)로 다시 생성되는지 확인합니다
컨텍스트 검색을 활성화한 상태에서도 검색 결과가 표시되는지 확인합니다

지원

알골리아 DocSearch 팀은 사이트의 검색 관련 문제를 파악하는데 도움을 줄 수 있습니다.

지원 페이지나 Discord를 통해 Algolia에 문의할 수 있습니다.

도큐사우루스 Discord에도 #algolia 채널이 있습니다.

👥 Typesense DocSearch 사용하기

Typesense DocSearch는 웹사이트를 Typesense 검색 클러스터에 색인한다는 점을 제외하면 Algolia DocSearch와 비슷하게 동작합니다.

Typesense는 오픈 소스 즉시 검색 엔진이며, 다음 방법 중 하나로 사용할 수 있습니다:

자체 서버에서 직접 호스팅하거나
관리형 Typesense Cloud 서비스를 사용합니다.

알골리아 DocSearch와 비슷하게 2개의 컴포넌트가 있습니다.

typesense-docsearch-scraper - 웹사이트를 스크래핑하고 데이터를 Typesense 클러스터에 색인합니다.
docusaurus-theme-search-typesense - 웹사이트에 추가하는 검색 창 UI 컴포넌트입니다.

typesense-docsearch-scraper 실행 방법과 도큐사우루스 사이트에 검색 창을 설치하는 방법을 단계별로 살펴보세요.

👥 로컬 검색 기능 사용하기

검색 색인 대상이 작고 사용자가 웹사이트를 방문할 때 사용자 브라우저에 내려받을 수 있는 경우에는 웹사이트를 위한 로컬 검색 플러그인을 사용할 수 있습니다.

커뮤니티에서 지원하는 로컬 검색 플러그인 목록을 확인할 수 있습니다.

👥 직접 작성한 검색 기능 사용하기

자체 검색을 사용하려면 @docusaurus/theme-classic의 SearchBar 컴포넌트를 스위즐링하세요

npm
Yarn
pnpm
Bun

npm run swizzle @docusaurus/theme-classic SearchBar

yarn swizzle @docusaurus/theme-classic SearchBar

pnpm run swizzle @docusaurus/theme-classic SearchBar

bun run swizzle @docusaurus/theme-classic SearchBar

프로젝트 폴더에 src/theme/SearchBar 파일이 생성됩니다. 개발 서버를 다시 시작하고 컴포넌트를 편집하면 이제 도큐사우루스가 직접 만든 SearchBar 컴포넌트를 사용하는 것을 확인할 수 있습니다.

참고: Algolia SearchBar를 스위즐링한 후 이를 바탕으로 자체 검색 컴포넌트를 만들 수도 있습니다.

🥇 알골리아 DocSearch 사용하기​

색인 설정​

알골리아 연결하기​

상황별 검색 기능​

Ask AI​

알골리아 검색 기능에 스타일 적용하기​

알골리아 검색 기능 세부 설정하기​

알골리아 검색 컴포넌트 바꾸기​

문제 해결​

검색 결과가 표시되지 않음​

지원​

👥 Typesense DocSearch 사용하기​

👥 로컬 검색 기능 사용하기​

👥 직접 작성한 검색 기능 사용하기​