Skip to main content
The Orama Docusaurus plugin provides a powerful search experience for Docusaurus v3 sites, with support for both local (OSS) and cloud-based search.

​
Installation

Install the plugin using your preferred package manager: 
npm install @orama/plugin-docusaurus-v3
For Docusaurus v2, use the legacy @orama/plugin-docusaurus package instead.

​
Configuration

Add the plugin to your docusaurus.config.js file:
docusaurus.config.js
module.exports = {
  // ... other config
  plugins: [
    [
      '@orama/plugin-docusaurus-v3',
      {
        // Plugin options here
      }
    ]
  ],
  // ... other config
}

​
Local Search (OSS Mode)

For local search without cloud dependencies, use the basic configuration:
docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@orama/plugin-docusaurus-v3',
      {
        searchbox: {
          placeholder: 'Search documentation...'
        },
        searchButton: {
          label: 'Search'
        }
      }
    ]
  ]
}
This configuration:
  • Indexes all docs, blog posts, and pages during build
  • Creates a compressed search index (.json.gz format)
  • Provides instant client-side search
  • Works completely offline
For cloud-powered search with Orama Cloud, add cloud configuration:
docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@orama/plugin-docusaurus-v3',
      {
        cloud: {
          // For Orama Cloud v1 (legacy)
          indexId: 'your-index-id',
          apiKey: 'your-public-api-key',
          
          // For Orama Cloud v2 (Collections)
          collectionId: 'your-collection-id',
          apiKey: 'your-public-api-key',
          
          // Optional: deployment strategy
          deploy: 'default' // or 'snapshot-only'
        },
        searchbox: {
          placeholder: 'Search documentation...'
        }
      }
    ]
  ]
}

​
Deploy Types

​
deploy
string
default:"default"
Controls how the index is deployed to Orama Cloud:
  • default: Resets and deploys the index automatically after build
  • snapshot-only: Only creates a snapshot without deploying

​
Configuration Options

​
Cloud Configuration

​
cloud.indexId
string
Your Orama Cloud index ID (legacy v1). Required if not using collectionId.
​
cloud.collectionId
string
Your Orama Cloud collection ID (v2). Required if not using indexId.
​
cloud.apiKey
string
required
Your Orama Cloud public API key for search operations.
​
cloud.deploy
'default' | 'snapshot-only'
default:"default"
Deployment strategy for the search index.

​
Search UI Configuration

​
searchbox
object
Configuration for the search input component. Accepts any options from the Orama Searchbox component.
searchbox: {
  placeholder: 'Search...',
  themeConfig: {
    light: 'system',
    dark: 'system'
  }
}
​
searchButton
object
Configuration for the search button that triggers the search modal.
searchButton: {
  label: 'Search',
  buttonIcon: '🔍'
}

​
Analytics Configuration

​
plugins.analytics
object
Enable analytics tracking for search queries.
plugins: {
  analytics: {
    enabled: true,
    apiKey: 'your-analytics-api-key',
    indexId: 'your-index-id'
  }
}

​
What Gets Indexed

The plugin automatically indexes content from:
All documentation pages from @docusaurus/plugin-content-docs, including:
  • Page titles
  • Headings (h1-h6)
  • Content sections
  • Version information
  • Category metadata

​
Search Index Structure

Each indexed document includes: 
interface OramaDoc {
  title: string        // Section or page title
  content: string      // Extracted text content
  path: string         // URL path to the content
  section: string      // Parent page title
  category: string     // Content type (docs/blogs/pages)
  version: string      // Doc version (if applicable)
}

​
Advanced Usage

​
Custom Search Configuration

Customize the search behavior with advanced options:
docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@orama/plugin-docusaurus-v3',
      {
        searchbox: {
          placeholder: 'Search documentation...',
          // Facets for filtering results
          facetFilters: [
            {
              field: 'category',
              label: 'Category'
            },
            {
              field: 'version',
              label: 'Version'
            }
          ],
          // Customize result display
          resultsMap: {
            title: 'title',
            description: 'content',
            section: 'section'
          },
          // Set default limit
          limit: 10
        }
      }
    ]
  ]
}

​
Environment Variables

For security, use environment variables for sensitive data:
docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@orama/plugin-docusaurus-v3',
      {
        cloud: {
          indexId: process.env.ORAMA_INDEX_ID,
          apiKey: process.env.ORAMA_PUBLIC_API_KEY,
          collectionId: process.env.ORAMA_COLLECTION_ID
        }
      }
    ]
  ]
}
Only use public API keys in client-side configuration. Never expose private API keys in your Docusaurus config.

​
Build Process

The plugin hooks into the Docusaurus build lifecycle:
  1. Content Loading: Extracts content from all docs, blogs, and pages
  2. Markdown Parsing: Converts markdown to HTML and extracts sections
  3. Index Creation: Builds the search index with all extracted content
  4. Compression: Creates a gzipped index file for optimal performance
  5. Deployment: Optionally syncs the index to Orama Cloud

​
Build Output

For OSS mode, the plugin generates: 
build/
  └── orama-search-index-current.json.gz

​
Theme Integration

The plugin automatically integrates with the Docusaurus theme:
  • Replaces the default search bar
  • Provides custom styling that matches your theme
  • Supports light and dark mode
  • Responsive design for mobile and desktop

​
Local Development

When developing locally with the plugin: 
pnpm install
pnpm start
The search functionality is only fully available after running a production build: 
pnpm build
pnpm serve

​
Troubleshooting

Ensure the search index file is being generated in your build output. Check the build/ directory for orama-search-index-current.json.gz.
Verify your API key and index ID are correct. Check that your API key has the necessary permissions for deploying indexes.
Make sure your content has actual text to index. Check that your markdown files contain searchable content beyond just frontmatter.

​
Package Information

​
Requirements

  • Docusaurus v3.x
  • Node.js >= 16
  • Peer dependencies:
    • @docusaurus/plugin-content-docs ^3
    • @docusaurus/theme-common ^3
    • @docusaurus/utils ^3

​
Next Steps

Search Guide

Learn more about Orama search features

Analytics Plugin

Track and analyze search behavior

Core Database

Learn about Orama database configuration

Full Documentation

View the complete Docusaurus guide

Build docs developers (and LLMs) love

Get started for freeTalk to us