Docusaurus

TIP

If you're looking for Canary Cloud, please refer to this page instead.

Docusaurus is static site generator using React.

Since Docusaurus do not have default search index, we provide @getcanary/docusaurus-theme-search-pagefind to generate Pagefind index at build time.

Why use Pagefind?

Main problem of local search index is that the size of the index grows as you add more content, and users must load the whole index upfront to do the search.

Pagefind solved this problem by splitting the index into multiple fragments and load fragments on demand. Also note that docusaurus-lunr-search, which is quite popular, uses lunr.js that hasn't been updated for the last 4 years.

One step to integrate

npm install @getcanary/web
npm install @getcanary/docusaurus-theme-search-pagefind

docusaurus.config.js

/** @type {import('@docusaurus/types').Config} */
const config = {
  ...
  themes: [
    // Remove any existing plugins or themes that are related to search
    require.resolve("@getcanary/docusaurus-theme-search-pagefind"), 
  ],
};

TIP

According to Docusaurus docs,

...the themes and plugins entries are interchangeable when installing and configuring a plugin.

Configuration

Basic

You can change colors and pagefind ranking by adding the following configuration. All options are optional.

docusaurus.config.js

/** @type {import('@docusaurus/types').Config} */
const config = {
  ...
  themes: [
    [
      require.resolve("@getcanary/docusaurus-theme-search-pagefind"),
      { 
        // https://getcanary.dev/docs/common/customization/styling#css-variables
        styles: { 
          "--canary-color-primary-c": 0.1, 
          "--canary-color-primary-h": 270, 
        }, 
        // https://pagefind.app/docs/ranking
        pagefind: { 
          ranking: { 
            pageLength: 0.9, 
            termFrequency: 1.0, 
            termSimilarity: 1.0, 
            termSaturation: 1.5, 
          } 
        } 
        disable: false, 
        indexOnly: false, 
        includeRoutes: ["**/*"], 
        excludeRoutes: ['/api/**'], 
        // https://getcanary.dev/docs/local/playground
        group: false, 
        tabs: [], 
      },
    ],
  ],
};

Advanced

When you add @getcanary/docusaurus-theme-search-pagefind to the themes list, it will override the default search component to use Canary's. To customize this search-bar further, you can eject it and modify the code.

npm run swizzle @getcanary/docusaurus-theme-search-pagefind SearchBar -- --eject

src/theme/SearchBar.js

export default function SearchBar() {
  ...
  return (
    <canary-root framework="docusaurus">
      {/* ... */}
    </canary-root>
  );
}

Specifying framework="docusaurus" is required to detect light/dark mode changes.

Note that since Canary's main focus is to provide composable primitives, ejected components will be very simple and easy to customize.

For information on how to compose components to build your own search-bar UI, please refer to the Built-in Components and Custom Components guides.