sphinx-doc / sphinx-doc/sphinx
Word exclusion breaks search
Nobody has claimed this yet.
- 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"):
- Exclude a word that is displayed in one of the previous search results (e.g. "Changelog"):
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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