Docusaurus에서 검색 기능 구현하기

작성일 : 2025.01.10

문서 사이트를 운영하다 보면 검색 기능은 선택이 아닌 필수입니다. 방문자들이 원하는 정보를 빠르게 찾을 수 있도록 돕는 것은 좋은 문서의 핵심이기 때문입니다. 이 글에서는 Docusaurus 기반 사이트에 검색 기능을 추가하는 방법을 자세히 알아보겠습니다.

검색 엔진 선택하기

Docusaurus에서는 크게 두 가지 방식으로 검색 기능을 구현할 수 있습니다. 로컬 검색과 Algolia DocSearch입니다. 각각의 장단점을 살펴보고 여러분의 프로젝트에 적합한 방식을 선택하시기 바랍니다.

로컬 검색 구현하기

로컬 검색은 별도의 외부 서비스 없이 구현할 수 있는 가장 간단한 방법입니다. Docusaurus의 공식 테마를 사용하면 됩니다.

먼저 필요한 패키지를 설치합니다:

npm install --save @docusaurus/theme-search-local
# 또는
yarn add @docusaurus/theme-search-local

그런 다음 docusaurus.config.js 파일에 다음 설정을 추가합니다:

module.exports = {
  themes: [
    [
      "@docusaurus/theme-search-local",
      {
        hashed: true,
        language: ["en", "ko"],  // 한국어 검색 지원
        indexDocs: true,
        indexBlog: true,
        indexPages: false
      },
    ],
  ],
};

로컬 검색의 장점은 설정이 간단하고 외부 의존성이 없다는 것입니다. 하지만 데이터가 많아지면 검색 성능이 저하될 수 있다는 단점이 있습니다.

Algolia DocSearch 설정하기

더 강력한 검색 기능이 필요하다면 Algolia DocSearch를 추천드립니다. 무료로 사용할 수 있으며, 뛰어난 검색 성능을 제공합니다.

설정 과정은 다음과 같습니다:

Algolia DocSearch 프로그램에 여러분의 사이트를 등록합니다.
승인 후 받은 크레덴셜을 사용해 설정을 추가합니다:

module.exports = {
  themeConfig: {
    algolia: {
      appId: '여러분의_APPLICATION_ID',
      apiKey: '여러분의_API_KEY',
      indexName: '여러분의_INDEX_NAME',
      contextualSearch: true,
      searchParameters: {
        facetFilters: ['language:ko']
      },
    },
  },
};

검색 최적화하기

검색 기능을 추가했다면, 이제 검색 결과의 품질을 높일 차례입니다. 다음과 같은 방법들을 활용할 수 있습니다.

메타데이터 최적화

각 문서 파일의 시작 부분에 메타데이터를 추가하여 검색 결과의 정확도를 높일 수 있습니다:

---
title: 문서 제목
description: 문서에 대한 간단한 설명
keywords: [키워드1, 키워드2, 키워드3]
---

전역 설정 최적화

docusaurus.config.js 파일에서 전역 메타데이터를 설정하여 검색 성능을 더욱 개선할 수 있습니다:

module.exports = {
  themeConfig: {
    metadata: [{
      name: 'keywords',
      content: '사이트 주요 키워드들',
    }],
    navbar: {
      hideOnScroll: true,
    },
  },
};

주의사항과 팁

검색 기능을 구현할 때 몇 가지 주의할 점이 있습니다:

빌드 시점 인덱싱: 검색 인덱스는 사이트를 빌드할 때 생성됩니다. 문서를 수정했다면 반드시 다시 빌드해야 검색 결과에 반영됩니다.
다국어 지원: 한국어 검색을 지원하려면 반드시 설정에서 language 옵션에 'ko'를 추가해야 합니다.
성능 고려: 문서의 양이 많다면 Algolia DocSearch를 사용하는 것이 성능 면에서 유리합니다.

마무리

검색 기능은 문서 사이트의 사용성을 크게 향상시킬 수 있는 중요한 요소입니다. 여러분의 프로젝트 규모와 요구사항에 맞는 검색 솔루션을 선택하여 구현하시기 바랍니다. 로컬 검색으로 시작하여 필요에 따라 Algolia로 마이그레이션하는 것도 좋은 전략이 될 수 있습니다.

검색 엔진 선택하기​

로컬 검색 구현하기​

Algolia DocSearch 설정하기​

검색 최적화하기​

메타데이터 최적화​

전역 설정 최적화​

주의사항과 팁​

마무리​