Search¶
Configure how readers search your documentation: Pagefind for fast client-side search with section filters and heading results, or Sphinx’s built-in search.
Pagefind¶
Pagefind provides fast, keyboard-driven search with no external services. Press ⌘K or Ctrl+K to open the search modal.
Pagefind is opt-in. Install the theme with the pagefind extra:
uv add "sphinx-lumina-theme[pagefind]"
pip install "sphinx-lumina-theme[pagefind]"
That’s all. With the default search_backend = "auto", Lumina uses Pagefind whenever it is installed and indexes your site at the end of each build. No Node.js is required.
To require Pagefind explicitly, set it in conf.py:
html_theme_options = {
"search_backend": "pagefind",
}
Tip
If search_backend is "pagefind" but the extra is not installed, the build warns and uses Sphinx’s built-in search instead.
Search within a section¶
Use Search in below the search field to narrow results to one section, or choose All docs to search the whole documentation build. Opening the dialog starts with All docs each time. When a section has no matches, Search all docs broadens the search without changing your query.
Scopes come from your doc sections configuration,
including multi-path and default sections. Without doc_sections, Lumina uses
the root toctree’s document titles and includes each entry’s descendants. A page
listed under several branches belongs to the first one. Pages outside those
branches remain available through All docs. The selector appears only when
at least two sections are indexed; no tags or additional options are required.
Results show navigation breadcrumbs and up to three matching headings beneath each page. Select a heading to jump directly to that passage. Use the arrow keys from the search field to move through page and heading links, then press Enter to open one. Tab reaches the scope selector and result links.
Search covers the current build, not other versions or separately hosted sites. Rebuild your docs after changing the navigation so the index reflects it.
API symbols¶
Functions, classes and other objects documented with Sphinx domains, such as
py:function or a third-party API domain, are matched by name and listed above
the page results, up to five at a time. Type a member name such as connect or a
qualified name such as EventEmitter.on, then select a result to jump to its
definition. Symbols follow the rules of Sphinx’s own search: objects with a
negative search priority and pages marked :nosearch: are left out. Lumina writes
them to _static/lumina-symbols.json at the end of each build, for both search
backends.
Matches on the page¶
When a reader opens a search result, the search terms are marked in the page
content in the accent color. Press Esc to clear them. This uses Sphinx’s
own sphinx_highlight.js, so it works the same with both backends, and a link
such as guides/search.html?highlight=pagefind opens with the term marked.
Built-in Sphinx Search¶
Without the pagefind extra, Lumina uses Sphinx’s built-in search. To use it even when Pagefind is installed, set:
html_theme_options = {
"search_backend": "sphinx",
}
The built-in search works without any additional setup. It searches all pages and does not provide section filters or heading results in the dialog. If Pagefind cannot load or a query fails, Lumina offers a link to this search page.
Note
Search during development: Pagefind indexes your content during full builds. During live preview with sphinx-autobuild, search may not be available. Use ⌘F / Ctrl+F for in-page search instead.