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

검색

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

info

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

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

🥇 알골리아 DocSearch 사용하기

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

The service is free for any open-source project: just make sure to read the checklist and apply to the DocSearch program.

DocSearch crawls your website once a week (the schedule is configurable from the web interface) and aggregates all the content in an Algolia index. 웹 사이트에서는 알골리아 API를 사용해 수집된 콘텐츠에 대한 검색을 실행할 수 있습니다.

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

note

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

From the old docsearch?

You can read more about migration from the legacy DocSearch infra in our blog post or the DocSearch migration docs.

색인 설정

After your application has been approved and deployed, you will receive an email with all the details for you to add DocSearch to your project. Editing and managing your crawls can be done via the web interface. Indices are readily available after deployment, so manual configuration usually isn't necessary.

tip

It is highly recommended to use a config similar to the Docusaurus 2 website config.

알골리아 연결하기

도큐사우루스 @docusaurus/preset-classic에서는 기본으로 알골리아 DocSearch 통합을 지원합니다. classic preset을 사용한다면 추가적인 설치가 필요하지 않습니다.

@docusaurus/preset-classic을 사용하지 않을 때 설치 단계입니다.
  1. 패키지를 설치합니다.
npm install --save @docusaurus/theme-search-algolia
  1. 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: {
// 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. 여러 문서 사이트를 크롤링하고 window.location.href를 사용하여 해당 사이트로 이동하려는 경우에 유용한 알골리아 설정입니다.
externalUrlRegex: 'external\\.com|domain\\.com',

// 옵션: 알골리아 검색 파라미터
searchParameters: {},

//... 다른 알골리아 파라미터
},
},
};
info

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

caution

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

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

Contextual search is enabled by default.

It ensures that search results are relevant to the current language and version.

docusaurus.config.js
module.exports = {
// ...
themeConfig: {
// ...
algolia: {
contextualSearch: true,
},
},
};

Let's consider you have 2 docs versions (v1 and v2) and 2 languages (en and fr).

When browsing v2 docs, it would be odd to return search results for the v1 documentation. v1과 v2 문서 내용은 어느 정도 비슷할 수 있습니다. 때문에 같은 질의에 대해 중복된 검색 결과가 나올 수 있습니다(버전 당 하나의 결과가 나오는 것이지요).

Similarly, when browsing the French site, it would be odd to return search results for the English docs.

To solve this problem, the contextual search feature understands that you are browsing a specific docs version and language, and will create the search query filters dynamically.

  • on /en/docs/v1/myDoc, search results will only include English results for the v1 docs (+ other unversioned pages)
  • on /fr/docs/v2/myDoc, search results will only include French results for the v2 docs (+ other unversioned pages)
info

When using contextualSearch: true (default), the contextual facet filters will be merged with the ones provided with algolia.searchParameters.facetFilters .

For specific needs, you can disable contextualSearch and define your own facetFilters:

docusaurus.config.js
module.exports = {
// ...
themeConfig: {
// ...
algolia: {
contextualSearch: false,
facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
},
},
};

Refer to the relevant Algolia faceting documentation.

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

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

This will create an src/themes/SearchBar file in your project folder. 개발 서버를 재시작하고 컴포넌트를 수정해주면 도큐사우루스에서는 여러분이 만든 SearchBar 컴포넌트를 사용하게 됩니다.

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