docusaurus-search-zensearch

ZenSearch integration for Docusaurus documentation sites. Replace the default search with AI-powered documentation search.

Features

• Fast, AI-powered documentation search
• Fuzzy matching and semantic search
• Keyboard navigation (Ctrl/Cmd + K)
• Dark mode support
• Customizable styling
• Analytics tracking
• Mobile-friendly

Installation

npm install docusaurus-search-zensearch
# or
yarn add docusaurus-search-zensearch
# or
pnpm add docusaurus-search-zensearch

Configuration

Add the plugin to your docusaurus.config.js:

module.exports = {
  // ...
  themes: [
    [
      'docusaurus-search-zensearch',
      {
        // Required: Your ZenSearch publishable API key
        apiKey: 'zsk_pk_xxx...',

        // Optional: Collection ID to search
        collectionId: 'your-collection-id',

        // Optional: Custom API base URL
        // baseUrl: 'https://api.zensearch.dev',

        // Optional: Search placeholder text
        placeholder: 'Search documentation...',

        // Optional: Maximum number of results
        maxResults: 10,

        // Optional: Minimum relevance score (0-1, default: 0.5)
        // Results below this score are filtered out
        minScore: 0.5,

        // Optional: Enable keyboard shortcut (default: true)
        enableKeyboardShortcut: true,

        // Optional: Custom shortcut key (default: 'k')
        keyboardShortcutKey: 'k',

        // Optional: Enable analytics (default: true)
        enableAnalytics: true,
      },
    ],
  ],
};

Getting Your API Key

1. Sign up at ZenSearch
2. Create a new collection for your documentation
3. Index your documentation site
4. Get your publishable API key from the dashboard

Theme Configuration

You can also configure the search bar in themeConfig:

module.exports = {
  themeConfig: {
    zensearch: {
      // Enable/disable the search bar (default: true)
      enabled: true,

      // Position in navbar: 'left' | 'right' (default: 'right')
      position: 'right',

      // Show on mobile (default: true)
      showOnMobile: true,
    },
  },
};

Customizing Styles

You can override the default styles using CSS variables or custom CSS:

/* src/css/custom.css */
:root {
  /* Customize highlight color */
  --ifm-color-primary-lightest: #e3f2fd;
  --ifm-color-primary-darkest: #1565c0;
}

/* Override search button styles */
.searchButton {
  background: var(--ifm-navbar-background-color);
}

/* Override modal styles */
.modal {
  backdrop-filter: blur(8px);
}

Swizzling

To fully customize the SearchBar component, you can swizzle it:

npm run swizzle docusaurus-search-zensearch SearchBar -- --eject

This will copy the SearchBar component to your project for full customization.

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Cmd/Ctrl + K | Open search | | ↑ / ↓ | Navigate results | | Enter | Select result | | Escape | Close search |

Analytics

When enableAnalytics is true, the plugin tracks:

• Search queries: What users are searching for
• Click-through: Which results users click
• Position: Where in the results the click occurred

This data helps improve search relevance over time.

Troubleshooting

Search not working

1. Verify your API key is correct
2. Check that your documentation has been indexed
3. Check browser console for errors

Keyboard shortcut not working

Some browsers or extensions may intercept Cmd/Ctrl + K. Try a different shortcut:

keyboardShortcutKey: '/',  // Use "/" instead

Styling issues in dark mode

Ensure you're using CSS variables that adapt to dark mode:

html[data-theme='dark'] .searchButton {
  background: var(--ifm-navbar-background-color);
}

Support

• Documentation
• GitHub Issues
• Discord Community

License

MIT