sphinx-typesense

A Sphinx extension for integrating powerful search into documentation sites with support for both Typesense and Pagefind backends.

Replace Sphinx's built-in search with fast, typo-tolerant search that scales from small projects to large documentation portals.

Features

• Dual Backend Support - Choose between Typesense (server-based) or Pagefind (static, no server required)
• Fast Search - Sub-50ms search responses with either backend
• Typo Tolerance - Built-in typo correction (configurable 0-2 typos)
• Build-time Indexing - Automatic content extraction during Sphinx builds
• DocSearch Compatible - Uses the DocSearch hierarchical schema for familiar UX
• Multiple Theme Support - Works with RTD, Furo, Alabaster, PyData, Book, and Shibuya themes
• Self-hosted or Cloud - Typesense supports both Server and Cloud deployments

Installation

pip install sphinx-typesense

Or with uv:

uv add sphinx-typesense

Quick Start

Add to your Sphinx conf.py:

extensions = ["sphinx_typesense"]

# Backend selection: "auto", "typesense", or "pagefind"
typesense_backend = "auto"  # Uses Typesense if configured, falls back to Pagefind

Pagefind (Static, No Server)

For static sites without a server, Pagefind works out of the box:

typesense_backend = "pagefind"

Typesense (Server-based)

For server-based search with advanced features:

import os

typesense_backend = "typesense"
typesense_host = "localhost"
typesense_port = "8108"
typesense_protocol = "http"
typesense_api_key = os.environ.get("TYPESENSE_API_KEY", "")
typesense_search_api_key = os.environ.get("TYPESENSE_SEARCH_API_KEY", "")

Build your documentation and the search index will be automatically created:

sphinx-build -b html docs docs/_build/html

Documentation

Full documentation is available at typesense.scriptr.dev.

• Installation Guide
• Configuration Reference
• Theme Support
• API Reference

License

MIT License - see LICENSE for details.