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

검색

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

info

🥇 도큐사우루스는 알골리아 DocSearch에 대한 최고 수준의 지원을 제공합니다.

👥 다른 옵션은 커뮤니티에서 관리하고 있습니다. 버그는 해당 저장소에 보고해주세요.

🥇 알골리아 DocSearch 사용하기

도큐사우루스는 알골리아 DocSearch에 대한 공식 지원을 제공합니다.

서비스는 대부분의 경우에는 무료입니다. DocSearch 프로그램을 신청하기만 하면 됩니다.

DocSearch는 매일 24시간동안 여러분의 웹사이트 콘텐츠를 수집해서 알골리아 인덱스에 모든 콘텐츠를 추가합니다. 웹 사이트에서는 알골리아 API를 사용해 수집된 콘텐츠에 대한 검색을 실행할 수 있습니다.

여러분의 웹 사이트가 무료로 제공되는 문서 검색 기능에 적합하지 않거나 방화벽 뒤에 있거나 내부에서만 공개한 경우에는 문서 검색 크롤러를 직접 관리할 수 있습니다.

note

기본적으로 도큐사우루스 사전 설정은 알골리아 크롤러에서 사용할 수 있는 sitemap.xml 파일을 생성합니다.

색인 설정

적용 후 사이트의 DocSearch 설정은 다음 위치에 생성되어야 합니다.

https://github.com/algolia/docsearch-configs/blob/master/configs/<indexName>.json

설정 파일은 다음 방법으로 업데이트할 수 있습니다.

caution

도큐사우루스 2 웹사이트 설정과 유사한 설정을 사용하는 것을 권장합니다.

알골리아 연결하기

Docusaurus' own @docusaurus/preset-classic supports Algolia DocSearch integration. If you use the classic preset, no additional installation is needed.

Installation steps when not using @docusaurus/preset-classic
  1. Install the package:
npm install --save @docusaurus/theme-search-algolia
  1. Register the theme in docusaurus.config.js:
docusaurus.config.js
module.exports = {
title: 'My site',
// ...
themes: ['@docusaurus/theme-search-algolia'],
themeConfig: {
// ...
},
};

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

docusaurus.config.js
module.exports = {
// ...
themeConfig: {
// ...
algolia: {
// If Algolia did not provide you any appId, use 'BH4D9OD16A'
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: Algolia search parameters
searchParameters: {},

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

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

caution

알골리아가 검색 플러그인을 활성화한 상태로 사이트를 크롤링할 때까지 검색 기능이 안정적으로 작동하지 않습니다.

알골리아 플러그인을 처음 설치하고 제품으로 배포하기 전에 검색 기능이 작동하는지 확인하려면 DocSearch 팀에 테스트 환경 URL이나 배포 미리보기에서 크롤링을 트리거할 수 있도록 요청할 수 있습니다.

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

여러분이 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와 같이 상황별 필터링 기능이 동작합니다.

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

물론 /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

지원

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

이메일이나 디스코드로 연락할 수 있습니다.

도큐사우루스도 디스코드에서 #algolia 채널을 운영하고 있습니다.

👥 Typesense DocSearch 사용하기

Typesense DocSearch는 웹사이트가 Typesense 검색 클러스터에 색인되는 것을 제외하면 알골리아 DocSearch와 비슷하게 작동합니다.

Typesense는 아래와 같은 방법으로 활용할 수 있는 오픈소스 검색 엔진입니다.

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

단계별 사용 방법은 run typesense-docsearch-scraper here, install the Search Bar in your Docusaurus Site here 문서를 참고하세요.

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

커뮤니티에서 지원하는 로컬 검색 플러그인 목록을 확인해보세요.

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

npm run swizzle @docusaurus/theme-classic SearchBar

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

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