Search¶

Configure how readers search your documentation — Pagefind for fast client-side search, or Sphinx’s built-in search as a fallback.

2 min read

Pagefind (default)¶

Pagefind provides fast, keyboard-driven search with no external services. Press ⌘K or Ctrl+K to open the search modal.

Lumina runs Pagefind automatically at the end of each build — no manual setup required. You just need Node.js installed so that npx is available.

Build your docs and search is ready:

uv (recommended)

uv run sphinx-build docs docs/_build/html

pip

sphinx-build docs docs/_build/html

Tip

If npx is not found, the build completes normally but search won’t be indexed. Install Node.js to enable Pagefind, or switch to Sphinx’s built-in search below.

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.

Built-in Sphinx Search¶

If you prefer not to use Pagefind, switch to Sphinx’s built-in search:

conf.py¶

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.