Skip to main content
버전: 3.0.1

검색

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

정보

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

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

🥇 알골리아 DocSearch 사용하기​

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

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

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

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

참고

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

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

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

색인 설정​

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

팁

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

알골리아 연결하기​

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

@docusaurus/preset-classic을 사용하지 않을 때의 설치 단계
  1. 패키지를 설치합니다.
npm install --save @docusaurus/theme-search-algolia
  1. 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 run swizzle @docusaurus/theme-search-algolia SearchBar

지원​

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

You can contact them by email or on Discord.

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

👥 Typesense DocSearch 사용하기​

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

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

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

Read a step-by-step walk-through of how to run typesense-docsearch-scraper here and how to 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 컴포넌트를 사용하는 것을 확인할 수 있습니다.

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