Customize

You can configure this extension to match your theme by adding custom templates, and adding custom CSS.

Add custom templates

By default, the DocSearch Sphinx extension overrides these templates:

• searchbox.html (used by many themes, including Read the Docs, Alabaster, Sphinx’s built-in themes)

• sidebar/search.html (used by the Furo theme)

If you’re using any of the listed themes, DocSearch works without additional configuration.

If you’re using any other theme, you can add custom templates in your Sphinx configuration. The extension works best, if the theme uses a separate template for the search box.

To add a custom template, follow these steps:

1. Create a new directory in your Sphinx project, such as _templates/.

2. Create a custom template file with the same name as the template you want to override from your theme, such as _templates/searchbox.html:

   {# _templates/searchbox.html #}
   <div id="searchbox"></div>
   

   This replaces the theme’s searchbox.html template with an empty div element.

3. Update your Sphinx configuration:

   # conf.py
   template_path = ["_templates"] 
   docsearch_container = "#searchbox"
   

Add custom CSS

To modify the style of the DocSearch search box and modal dialog, you can add custom CSS files to your project:

1. Create a new directory in your Sphinx project, such as _static/.

2. Create a new CSS file with styles you want to change:

   /* _static/custom.css */
   :root {
     --docsearch-primary-color: #d83fe0;
   }
   .DocSearch-Button {
     border-radius: 0; 
   }
   

   You can change many styles of the DocSearch UI with CSS custom properties.

3. Update your Sphinx configuration:

   # conf.py
   html_static_path = ["_static"]
   html_css_files = ["custom.css"]