메인 컨텐츠로 이동
Version: 2.0.0-beta.5 🚧

검색

도큐사우루스 @docusaurus/preset-classic에서는 기본으로 검색 기능 통합을 지원합니다.

사용할 수 있는 옵션은 두 가지입니다. 알골리아 문서 검색(Algolia DocSearch)을 사용하거나 직접 만든 SearchBar 컴포넌트를 적용할 수 있습니다.

알골리아 문서 검색 사용하기#

알골리아 문서 검색은 여러분의 웹 사이트 콘텐츠를 24시간마다 수집하고 알골리아 인덱스에 모든 콘텐츠를 추가합니다. 웹 사이트에서는 알골리아 API를 사용해 수집된 콘텐츠에 대한 검색을 실행할 수 있습니다. 문서 검색 기능을 사용하기 위해서는 여러분의 웹 사이트가 온라인에 공개되어 있어야 한다는 것을 잊지 마세요(예를 들어 방화벽에서 알골리아의 접근을 차단할 수 있습니다). 문서 검색 기능은 무료로 사용할 수 있습니다.

여러분의 웹 사이트가 무료로 제공되는 문서 검색 기능에 적합하지 않거나 방화벽 뒤에 있는 경우에는 문서 검색 크롤러를 직접 관리할 수 있습니다. 알골리아에서는 적절한 설정을 위해 도큐사우루스 2 설정 파일을 지원합니다.

알골리아 연결하기#

여러분의 문서를 알골리아와 연결하기 위해서는 먼저 웹 사이트에 패키지를 추가해야 합니다.

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

그리고 themeConfig에 algolia 필드를 추가합니다. Apply for DocSearch에 접속해서 여러분을 위한 알골리아 index 값과 API 키를 발급받을 수 있습니다.

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    algolia: {      apiKey: 'YOUR_API_KEY',      indexName: 'YOUR_INDEX_NAME',
      // Optional: see doc section below      contextualSearch: true,
      // Optional: see doc section below      appId: 'YOUR_APP_ID',
      // Optional: Algolia search parameters      searchParameters: {},
      //... other Algolia params    },  },};
info

searchParameters 옵션은 도큐사우루스 v1에서 사용하던 algoliaOptions 옵션과 같습니다.

상황별 검색 기능#

상황별 검색 기능은 여러 개 버전을 가진 도큐사우루스 사이트를 운영할 때 유용합니다.

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

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

  • /docs/v1/myDoc 문서를 보고 있다면 v1 문서에 대한 검색 결과만 처리합니다(버전과 무관한 문서는 포함해서).
  • /docs/v2/myDoc 문서를 보고 있다면 v2 문서에 대한 검색 결과만 처리합니다(버전과 무관한 문서는 포함해서).
docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    algolia: {      contextualSearch: true,    },  },};
caution

contextualSearch: true 값을 설정하면 algolia.searchParameters.facetFilters와 같이 상황별 필터링 기능이 동작합니다.

사용자 지정 Application ID#

문서 검색 크롤러를 수작업으로 실행하는 경우에는 사용자 지정 Application ID로 appId 설정 키가 필요합니다. 해당 값을 설정하지 않으면 appId는 알골리아 문서 검색에서 제공하는 무료 버전으로 대체됩니다.

docusaurus.config.js
module.exports = {  // ...  themeConfig: {    // ...    algolia: {      appId: 'YOUR_APP_ID',    },  },};

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

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

물론 /src/css/custom.css 파일을 수정해 도큐사우루스의 인피마 CSS 변수를 문서 검색을 위한 스타일로 적용할 수 있습니다.

/src/css/custom.css
html[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);}
html[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%  );}

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

알골리아 문서 검색은 docusaurus.config.js 파일 algolia 필드에 설정할 수 있는 몇 가지 옵션을 지원합니다.

docusaurus.config.js
module.exports = {  themeConfig: {    // ...    algolia: {      apiKey: 'YOUR_API_KEY',      indexName: 'YOUR_INDEX_NAME',      // Options...    },  },};

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

알골리아 검색에서 사용하는 리액트 컴포넌트를 바꾸고 싶다면 @docusaurus/theme-search-algolia에서 SearchBar 컴포넌트를 바꾸어줄 수 있습니다.

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

다른 검색 기능 사용하기#

여러분이 만든 검색 기능을 사용하고 싶다면 @docusaurus/theme-classic에서 SearchBar 컴포넌트를 바꾸어줄 수 있습니다.

npm run swizzle @docusaurus/theme-classic SearchBar

명령을 실행하면 프로젝트 디렉터리 아래에 src/themes/SearchBar 파일을 만들어줍니다. 개발 서버를 재시작하고 컴포넌트를 수정해주면 도큐사우루스에서는 여러분이 만든 SearchBar 컴포넌트를 사용하게 됩니다.

참고: 알골리아 검색 컴포넌트 바꾸기를 적용한 후 여러분이 만든 검색 기능을 사용할 수도 있습니다.