VitePress Integration

Learn how to integrate DocSearch with VitePress documentation sites

DocSearch provides native support for VitePress through the @docsearch/react package. This guide shows you how to set up DocSearch in your VitePress documentation site.

Overview

VitePress has built-in support for Algolia DocSearch through its default theme configuration. You can enable DocSearch by adding configuration to your VitePress config file.

VitePress uses the same DocSearch integration that powers many documentation sites. Make sure you’ve applied for DocSearch to get your credentials.

Installation

No additional packages are required! VitePress includes DocSearch support out of the box. You just need to configure it.

Configuration

1. Get your credentials

   Before configuring DocSearch, you need:

   • appId - Your Algolia application ID
   • apiKey - Your search-only API key
   • indexName - Your index name

   Get these by applying to DocSearch or from your Algolia dashboard.

2. Configure VitePress

   Add the DocSearch configuration to your .vitepress/config.js (or .ts, .mjs) file:

   .vitepress/config.js

   export default {
     themeConfig: {
       search: {
         provider: 'algolia',
         options: {
           appId: 'YOUR_APP_ID',
           apiKey: 'YOUR_SEARCH_API_KEY',
           indexName: 'YOUR_INDEX_NAME'
         }
       }
     }
   }
   
3. Test your search

   Restart your VitePress dev server and press Ctrl+K (or Cmd+K on Mac) to open the search modal. You should see the DocSearch interface.

Configuration Options

Basic Configuration

The minimum required configuration:

.vitepress/config.js

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME'
      }
    }
  }
}

Search Parameters

Customize search behavior with Algolia search parameters:

.vitepress/config.js

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        searchParameters: {
          facetFilters: ['language:en', 'version:v1']
        }
      }
    }
  }
}

Placeholder Text

Customize the search box placeholder:

.vitepress/config.js

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        placeholder: 'Search documentation'
      }
    }
  }
}

Translations

Customize button and modal text:

.vitepress/config.js

export default {
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        translations: {
          button: {
            buttonText: 'Search',
            buttonAriaLabel: 'Search documentation'
          },
          modal: {
            searchBox: {
              resetButtonTitle: 'Clear query',
              resetButtonAriaLabel: 'Clear query',
              cancelButtonText: 'Cancel',
              cancelButtonAriaLabel: 'Cancel'
            },
            startScreen: {
              recentSearchesTitle: 'Recent',
              noRecentSearchesText: 'No recent searches',
              saveRecentSearchButtonTitle: 'Save to recent searches',
              removeRecentSearchButtonTitle: 'Remove from recent searches',
              favoriteSearchesTitle: 'Favorites',
              removeFavoriteSearchButtonTitle: 'Remove from favorites'
            },
            errorScreen: {
              titleText: 'Unable to fetch results',
              helpText: 'Check your network connection'
            },
            footer: {
              selectText: 'to select',
              navigateText: 'to navigate',
              closeText: 'to close',
              searchByText: 'Search by'
            },
            noResultsScreen: {
              noResultsText: 'No results for',
              suggestedQueryText: 'Try searching for',
              reportMissingResultsText: 'Missing results?',
              reportMissingResultsLinkText: 'Let us know'
            }
          }
        }
      }
    }
  }
}

Multi-Language Sites

For multi-language VitePress sites, configure search per locale:

.vitepress/config.js

export default {
  locales: {
    root: {
      label: 'English',
      lang: 'en',
      themeConfig: {
        search: {
          provider: 'algolia',
          options: {
            appId: 'YOUR_APP_ID',
            apiKey: 'YOUR_SEARCH_API_KEY',
            indexName: 'YOUR_INDEX_NAME',
            searchParameters: {
              facetFilters: ['language:en']
            },
            placeholder: 'Search documentation'
          }
        }
      }
    },
    fr: {
      label: 'Français',
      lang: 'fr',
      themeConfig: {
        search: {
          provider: 'algolia',
          options: {
            appId: 'YOUR_APP_ID',
            apiKey: 'YOUR_SEARCH_API_KEY',
            indexName: 'YOUR_INDEX_NAME',
            searchParameters: {
              facetFilters: ['language:fr']
            },
            placeholder: 'Rechercher dans la documentation'
          }
        }
      }
    }
  }
}

Custom Component Integration

If you need more control, you can directly use the @docsearch/react package in your custom VitePress theme.

1. Install DocSearch React

   npm

   npm install @docsearch/react
   
2. Create a custom component

   Create a Vue component that wraps DocSearch:

   .vitepress/theme/components/DocSearch.vue

   <script setup>
   import { onMounted } from 'vue'
   import docsearch from '@docsearch/js'
   import '@docsearch/css'
   
   onMounted(() => {
     docsearch({
       container: '#docsearch',
       appId: 'YOUR_APP_ID',
       apiKey: 'YOUR_SEARCH_API_KEY',
       indexName: 'YOUR_INDEX_NAME'
     })
   })
   </script>
   
   <template>
     <div id="docsearch"></div>
   </template>
   
3. Use the component

   Import and use your custom component in your VitePress theme:

   .vitepress/theme/index.js

   import DefaultTheme from 'vitepress/theme'
   import DocSearch from './components/DocSearch.vue'
   import './custom.css'
   
   export default {
     extends: DefaultTheme,
     enhanceApp({ app }) {
       app.component('DocSearch', DocSearch)
     }
   }
   

Ask AI Integration

Ask AI is available in DocSearch v4+. VitePress’s built-in integration may not support all Ask AI features. For full Ask AI support, use the custom component approach.

To enable Ask AI with a custom integration:

.vitepress/theme/components/DocSearch.vue

<script setup>
import { onMounted } from 'vue'
import docsearch from '@docsearch/js'
import '@docsearch/css'

onMounted(() => {
  docsearch({
    container: '#docsearch',
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_SEARCH_API_KEY',
    indexName: 'YOUR_INDEX_NAME',
    askAi: 'YOUR_ASSISTANT_ID'
  })
})
</script>

<template>
  <div id="docsearch"></div>
</template>

Crawler Configuration

VitePress sites require specific crawler configuration. Create a docsearch.config.json:

docsearch.config.json

{
  "index_name": "YOUR_INDEX_NAME",
  "start_urls": ["https://yourdocs.com/"],
  "selectors": {
    "lvl0": {
      "selector": ".sidebar .active",
      "attribute": "textContent"
    },
    "lvl1": ".content h1",
    "lvl2": ".content h2",
    "lvl3": ".content h3",
    "lvl4": ".content h4",
    "lvl5": ".content h5",
    "text": ".content p, .content li"
  }
}

Adjust selectors based on your custom VitePress theme. The default theme uses .content for main content.

Complete Example

Here’s a complete VitePress configuration with DocSearch:

.vitepress/config.js

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Documentation',
  description: 'My awesome documentation site',
  
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: 'Introduction',
          items: [
            { text: 'Getting Started', link: '/guide/getting-started' },
            { text: 'Installation', link: '/guide/installation' }
          ]
        }
      ]
    },
    
    search: {
      provider: 'algolia',
      options: {
        appId: 'YOUR_APP_ID',
        apiKey: 'YOUR_SEARCH_API_KEY',
        indexName: 'YOUR_INDEX_NAME',
        placeholder: 'Search docs',
        searchParameters: {
          facetFilters: ['language:en']
        }
      }
    },
    
    socialLinks: [
      { icon: 'github', link: 'https://github.com/yourusername/yourrepo' }
    ]
  }
})

Troubleshooting

Search not working

1. Check credentials: Verify your appId, apiKey, and indexName are correct
2. Index status: Ensure your index has been crawled and contains data
3. Network: Check browser console for network errors

No results showing

1. Crawler setup: Verify your crawler configuration matches your VitePress structure
2. Facet filters: Check if searchParameters.facetFilters are too restrictive
3. Index content: Visit Algolia dashboard to inspect indexed records

Styling issues

1. CSS conflicts: VitePress styles may conflict with DocSearch. Add custom CSS:

.vitepress/theme/custom.css

.DocSearch-Button {
  /* Override button styles */
}

.DocSearch-Modal {
  /* Override modal styles */
}

2. Import order: Ensure DocSearch CSS is imported after VitePress theme CSS

Next Steps

Styling DocSearch

Customize the appearance to match your VitePress theme

API Reference

Explore all configuration options

Crawler Setup

Configure the DocSearch crawler for VitePress

Custom Integration

Build a custom integration with full control