sphinx_typesense.templates

HTML and JavaScript injection for the sphinx-typesense search UI. This module handles injecting the Typesense DocSearch configuration and search container into Sphinx HTML pages.

Module Contents

HTML and JavaScript injection for sphinx-typesense search UI.

This module handles injecting the search configuration and container into Sphinx HTML pages, with support for multiple backends (Typesense and Pagefind).

The injection process:

  1. Determines the effective backend from configuration

  2. Adds search container div to page context

  3. Injects backend-specific JavaScript configuration

  4. Handles theme-specific search bar placement

Assets:
Typesense backend:

  • typesense-docsearch.css: DocSearch styling

  • typesense-docsearch.js: DocSearch library (from CDN)

  • typesense-init.js: Initialization script with config

Pagefind backend:

  • pagefind-ui.css: Pagefind UI styling

  • pagefind-init.js: Initialization script with config

Example

The module is used automatically via Sphinx event:

app.connect("html-page-context", inject_search_assets)
sphinx_typesense.templates.inject_search_assets(app, pagename, templatename, context, doctree)[source]

Inject search configuration into page context based on selected backend.

This function is connected to Sphinx’s html-page-context event and adds the search UI HTML and JavaScript configuration to each page. The configuration varies based on the selected backend (Typesense or Pagefind).

Parameters:

  • app (Sphinx) – The Sphinx application instance.

  • pagename (str) – Name of the current page being rendered.

  • templatename (str) – Name of the template being used.

  • context (dict[str, Any]) – Template context dictionary to modify.

  • doctree (Any) – The document tree (may be None for some pages).

Note

The search container and configuration are added to the context as ‘typesense_search_html’ which can be included in templates or injected via theme-specific methods.

sphinx_typesense.templates.get_search_container_html(app)[source]

Generate the search container HTML.

Parameters:

app (Sphinx) – The Sphinx application instance.

Returns:

HTML string for the search container div.

Return type:

str

sphinx_typesense.templates.get_config_script(app)[source]

Generate the JavaScript configuration script (deprecated).

This function is kept for backward compatibility. New code should use get_typesense_config_script() or get_pagefind_config_script() based on the selected backend.

Parameters:

app (Sphinx) – The Sphinx application instance.

Returns:

JavaScript script tag with TYPESENSE_CONFIG object.

Return type:

str

sphinx_typesense.templates.get_typesense_config_script(app)[source]

Generate JavaScript configuration for Typesense DocSearch.

Creates a script tag containing the TYPESENSE_CONFIG object with all necessary configuration for the DocSearch frontend to connect to the Typesense server.

Parameters:

app (Sphinx) – The Sphinx application instance.

Returns:

JavaScript script tag with window.TYPESENSE_CONFIG object.

Return type:

str

Note

Only the search API key is exposed in the frontend configuration, never the admin API key.

sphinx_typesense.templates.get_pagefind_config_script(app)[source]

Generate JavaScript configuration for Pagefind UI.

Creates a script tag containing the PAGEFIND_CONFIG object with configuration for the Pagefind UI frontend.

Parameters:

app (Sphinx) – The Sphinx application instance.

Returns:

JavaScript script tag with window.PAGEFIND_CONFIG object.

Return type:

str

sphinx_typesense.templates.add_search_meta_tags(app, context, backend_name=None)[source]

Add meta tags for search configuration.

Adds meta tags that can be used by the JavaScript to get configuration without inline scripts (for CSP compliance).

Parameters:

  • app (Sphinx) – The Sphinx application instance.

  • context (dict[str, Any]) – Template context dictionary to modify.

  • backend_name (str | None) – The backend name (‘typesense’ or ‘pagefind’). If None, determined from config.

Note

Meta tags are added to context[‘metatags’] if it exists, allowing the configuration to be read via JavaScript document.querySelector for CSP-compliant implementations.

Injection Process

The template injection follows these steps for each HTML page:

  1. Container HTML: Generate a div element with the configured container ID

  2. Config Script: Generate a script tag with window.TYPESENSE_CONFIG

  3. Meta Tags: Add meta tags for CSP-compliant JavaScript access

  4. Context Update: Add the combined HTML to the template context

Generated HTML

The typesense_search_html context variable contains:

<div id="typesense-search"></div>
<script>
  window.TYPESENSE_CONFIG = {
    "collectionName": "sphinx_docs",
    "host": "localhost",
    "port": "8108",
    "protocol": "http",
    "apiKey": "search_api_key_here",
    "placeholder": "Search documentation...",
    "numTypos": 2,
    "perPage": 10,
    "filterBy": "",
    "container": "#typesense-search"
  };
</script>

Meta Tags

For Content Security Policy (CSP) compliant implementations, configuration is also available via meta tags:

<meta name="typesense-collection" content="sphinx_docs">
<meta name="typesense-host" content="localhost">
<meta name="typesense-port" content="8108">
<meta name="typesense-protocol" content="http">
<meta name="typesense-api-key" content="search_api_key_here">
<meta name="typesense-placeholder" content="Search documentation...">
<meta name="typesense-num-typos" content="2">
<meta name="typesense-per-page" content="10">
<meta name="typesense-filter-by" content="">
<meta name="typesense-container" content="#typesense-search">

JavaScript can read these with:

const host = document.querySelector('meta[name="typesense-host"]')?.content;

Template Integration

To include the search UI in custom templates:

{# In your theme's layout template #}
{% if typesense_search_html %}
  {{ typesense_search_html | safe }}
{% endif %}

Static Assets

The extension adds the following static files to each page:

  • typesense-docsearch.css: DocSearch styling

  • typesense-docsearch.js: DocSearch library (priority 500)

  • typesense-init.js: Initialization script (priority 501)

These are registered in the main setup function via:

app.add_css_file("typesense-docsearch.css")
app.add_js_file("typesense-docsearch.js", priority=500)
app.add_js_file("typesense-init.js", priority=501)