버전: 3.5.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: {
      // The application ID provided by Algolia
      appId: 'YOUR_APP_ID',

      // Public API key: it is safe to commit it
      apiKey: 'YOUR_SEARCH_API_KEY',

      indexName: 'YOUR_INDEX_NAME',

      // Optional: see doc section below
      contextualSearch: true,

      // Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them.
      externalUrlRegex: 'external\.com|domain\.com',

      // Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs
      replaceSearchResultPathname: {
        from: '/docs/', // or as RegExp: /\/docs\//
        to: '/',
      },

      // Optional: Algolia search parameters
      searchParameters: {},

      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',

      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
      insights: false,

      //... other Algolia params
    },
  },
};

정보

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 패싯 문서를 참고하세요.

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

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

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

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

그래도 /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를 사용할 때 가장 자주 겪는 문제를 정리했습니다.

검색 결과가 표시되지 않음

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

How to check if I have an config problem?

도큐사우루스는 컨텍스트 검색 기능에서 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 사용하기​

색인 설정​

알골리아 연결하기​

상황별 검색 기능​

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

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

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

문제 해결​

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

지원​

👥 Typesense DocSearch 사용하기​

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

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