What is Sphinx built-in search, and how to use it in themes?#

Sphinx is a powerful documentation generator with features that enhance content usability. Its built-in search offers a simple way to find information within your documentation. This guide will help you implement and customize Sphinx’s search in your themes for a better user experience for documentation readers.

Note

Applies to Sphinx 7.2.5 and above.

Built-in search capabilities#

Sphinx’s built-in search comes out of the box. It lacks advanced features but is still worth supporting in Sphinx themes. Among the main built-in search capabilities are:

  • Basic full-text search. It doesn’t support wildcards (? or *) and operators (OR, NOT, …).

  • Multiple words are ANDed. Searching multiple words shows matches that contain all words.

  • Works from a single letter. Even single-letter words can be searched.

  • Browser-only. It works entirely in the browser with a few JavaScript and doesn’t require any backend.

  • The search result page can show the surroundings of the occurrences found.

    Search result page can show the surroundings of the occurrences found

  • Highlight found occurrences on the result page and the page itself when open from the result page.

    Highlight found occurrences on the result page

  • Search across all pages, but individual pages can be hidden with the meta field :nosearch: at the beginning of the document.

    :nosearch:

Sphinx is cool
==============

    ---
nosearch:
---

# Sphinx is cool

Adding built-in search to Sphinx theme#

The process of bringing built-in search capability to your custom Sphinx theme involves a few easy steps, from customizing your HTML templates to styling the search results effectively.

1. Add content root data-content_root to <html>#

The main template layout.html must set data attribute content_root to the <html> element.

<html
  {% if language is not none %} lang="{{ language }}"{% endif %} 
  data-content_root="{{ content_root }}"
>

(Please note the underscore instead of hyphen as usual for data attributes. It’s proof backend Python developers chose the name :-))

The searchtools.js used the path when requesting a preview on the search page.

2. Add role="main" to body#

To work, the built-in search script assumes that the document or body block will be marked with role="main" in HTML. E.g.:

<article role="main">{% block body %}{% endblock %}</article>

3. Style search results#

Matching words are wrapped to <span class="highlighted"> by the sphinx_highlight.js script.

Search results are rendered as <ul> within #search-results by the searchtools.js script.

Example styles:

.highlighted {
  @apply rounded border border-dotted border-gray-300 bg-yellow-200;
}

/* Search page results */
#search-results ul {
  /* Display as vertical grid */
  @apply grid list-none grid-cols-1 gap-4 p-0;

  li a {
    @apply text-xl;
  }
}

Sphinx built-in search result example

5 Customize search.html template#

The search.html is a search result page template. The Basic theme contains a search form and results styled as an unordered list.

When you want to customize a search result page or author a Sphinx theme not based on Basic, don’t forget to

  • Include the JavaScript files listed below (odkaz).

  • Have a container for search results to be injected by scripts with id="search-results".

{# Template for the search page. #}
{%- extends "layout.html" %}
{% set title = _('Search') %}

{%- block before_body %}
  {{ super() }}
  <script src="{{ pathto('_static/searchtools.js', 1) }}"></script>
  <script src="{{ pathto('_static/language_data.js', 1) }}"></script>
  <script src="{{ pathto('searchindex.js', 1) }}" defer="defer"></script>
  <meta name="robots" content="noindex" />
{% endblock %}

{% block body %}
  <h1 id="search-documentation">{{ _('Search') }}</h1>

  <noscript>
    <div class="admonition warning">
      <p>
        {% trans %}
          Please activate JavaScript to enable the search functionality.
        {% endtrans %}
      </p>
    </div>
  </noscript>

  <p>
    {% trans %}
      Searching for multiple words only shows matches that contain all words.
    {% endtrans %}
  </p>

  <div id="search-results"></div>
{% endblock %}

Search-as-you-type example#

Clever mind Kayce Basques took Sphinx’s built-in search customization to the next level. He created and shared a cool search-as-you-type right into the Sphinx theme.

Pssst, Kayce also writes https://technicalwriting.dev blog.

Comments

comments powered by Disqus