sphinx-doc / sphinx-doc/sphinx

Word exclusion breaks search

Open
#13,892 4 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

The source code of the client side search supports word exclusions. I stumbled over it while searching for a better search for my documentation. According to the source code (sphinx/themes/basic/static/searchtools.js:318)
if (word[0] === "-") excludedTerms.add(word.substr(1)); all search words with a leading hyphen should be excluded from the search.

Sounds great at first, but when you try it, it doesn't work. That's because this code section is unreachable as long as the default splitQuery will discard hyphens entirely. Interestingly, there is a note in the source code that this splitQuery can be overwritten from outside (sphinx/themes/basic/static/searchtools.js:174):

 * Default splitQuery function. Can be overridden in ``sphinx.search`` with a
 * custom function per language.

This means you can actually redefine the word splitting in your conf.py. If you follow the how to reproduce, you will see that after tweaking the splitQuery function, the Search.performTermsSearch function will actually get the excluded words (if you use the browser debugger 😅).

Great! But now comes the bug. If you exclude one word from the search, the entire search will abort after finding one page with the excluded word. I would expect that the search will just filter out any exclusions, but it actually just does a hard break (sphinx/themes/basic/static/searchtools.js:648). Thereby, it will miss most of the relevant search results which renders the exclusion mechanism useless.

How to Reproduce

Add this to the conf.py to overwrite the splitQuery in the searchtools.js:

from sphinx.search import SearchLanguage

SearchLanguage.js_splitter_code="""
var splitQuery = (query) =>
    query
      .split(" ")
      .filter((term) => term);
"""

This new splitQuery will split search terms by whitespace. (Yes this is not optimal but sufficient for this bug report)

  • Now build your documentation with at least 2 pages (I used the official sphinx docs).
  • Search for a common term (e.g. "test"):
Image
  • Exclude a word that is displayed in one of the previous search results (e.g. "Changelog"):
Image

The search "loading ..." will stay and no or at least too few results will be shown.

Environment Information
Platform:              win32; (Windows-10-10.0.19045-SP0)
Python version:        3.13.7 (tags/v3.13.7:bcee1c3, Aug 14 2025, 14:15:11) [MSC v.1944 64 bit (AMD64)])
Python implementation: CPython
Sphinx version:        8.3.0+/eaebbec4d
Docutils version:      0.22
Jinja2 version:        3.1.6
Pygments version:      2.19.2
Sphinx extensions

Additional context

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in sphinx/themes/basic/static/searchtools.js at splitQuery, Search.performTermsSearch, and the exclusion handling around lines 318 and 648. Reproduce the issue with the conf.py SearchLanguage.js_splitter_code override and a multi-page documentation build. Done means excluding a word filters matching pages without aborting the search, so the remaining results finish loading.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, python
Domain
search
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.