Clear ?highlight= query parameter from the URL

[asmeurer]

Is your feature request related to a problem? Please describe.

The ?highlight=... query parameter that is added to the URL when performing a search is very annoying. To be clear, the highlighting itself is nice, but it's annoying that it's in the URL, because that means if you copy the URL, the highlight parameter comes along with it. But this is almost never what I want. Consider the following very common workflow:

1. Someone asks a question on some forum, and I know the answer is exists in some (Sphinx) document.
2. I go to the relevant site in question and search for something that will take me to the relevant page.
3. I click through to the page and copy the URL and paste it as an answer to the person.

After doing the above, the URL link as given will include the highlighting from the search. But that highlighting is actually irrelevant to the person reading the URL. It was only there for the original search term I used to find the given page.

For example, I might end up with a URL like this https://docs.sympy.org/latest/modules/simplify/simplify.html?highlight=nsimplify#sympy.simplify.simplify.nsimplify. Note that if I'm not paying close attention I might not even notice the highlighting. Here the search term happens to match the function name, but it could be anything, even something completely irrelevant. Suppose for instance I searched for one function but later decided to copy the link for another.

Of course, if you are aware of this, and also remember to do it, you can fix it by manually removing the ?highlight= query parameter from the URL. Some Sphinx themes such as Furo and now pydata sphinx theme include buttons that you can click to do this for you ("hide search matches" under the search bar in Furo), but it's still an extra step you have to do every time, and you have to actually remember to do it.

To contrast, I can't think of an instance when I have ever intentionally wanted to share a URL with text highlighting included. And even if I did, there is the text fragment anchor for that (see #10201), and anyway I don't see why I would want to share a URL that highlights the text specifically from a search term.

I've actually seen Google search results in the past that included a random ?highlight= in them, presumably because Google learned about the link from someone copy-pasting a page from a search result.

Describe the solution you'd like

I would suggest automatically clearing the ?highlight= query parameter from the URL. The highlighting should stay there (it would obviously go away after doing a refresh, but I think that's fine). To minimize disruption, I would suggest only clearing the query parameter after submitting a search. Manually loading a URL with a ?highlight= parameter should leave the URL intact as it is. That way people can continue to manually use the highlight parameter to highlight text, in case anyone is actually doing that.

I'm not really a Javascript developer so I don't know for certain whether this is possible, but I'm assuming it is because I've seen similar behaviors with other types of things on other websites.

Describe alternatives you've considered

Right now the best alternative is the "hide search terms" button on some themes, but this is theme specific, and requires a specific action from the user. It also both clears the parameter and the highlighting, whereas my suggested solution would only clear the parameter and keep the highlighting (until a refresh).

Additional context

This was discussed at pydata/pydata-sphinx-theme#925 but it was suggested to open an issue here.

[jdillard]

FWIW I've sent links with the highlighting on purpose (for contextual reasons).

It seems maybe a config option to turn off the highlighting value in the URLs generated in the search results would be best, with the default set to the current state. If theme's want they could still add the option for the user to clear the highlight.

That said, I don't know if it's worth the complexity (death of a thousand config options) and should be pushed out for the theme's to implement.

[asmeurer]

FWIW I've sent links with the highlighting on purpose (for contextual reasons).

But were the highlights specifically something that was a result of a search? With my suggestion, you would still be able to manually append ?highlight= to the end of a URL. It only wouldn't be added by default from a search (whether there should be some other UI for adding it is another question).

To me, when I search for something, it's just because I want to find some page. The highlighting is nice to indicate where the thing is, but it's not something I intend to share. The highlighting is really serving a dual purpose if it's also being used to share highlights of text

Also, note that you can use text fragment anchors to share a URL with some text highlighted.

It seems maybe a config option to turn off the highlighting value in the URLs generated in the search results would be best, with the default set to the current state. If theme's want they could still add the option for the user to clear the highlight.

That said, I don't know if it's worth the complexity (death of a thousand config options) and should be pushed out for the theme's to implement.

I don't know what the Sphinx policy is on config options. There already are a lot of them. I personally would prefer for this to be changed universally rather than each requiring each individual project to set a config value.

[ezio-melotti]

See also:

• Implement new search shortcuts. #9337 -- which introduced an ESC shortcut that removes both the ?highlight= and the actual highlights in the page
• "Hide Search Matches" removes "highlight" parameter from URL #9551

[asmeurer]

I had no idea about the escape shortcut. That's nice to know. So my suggestion boils down to automatically doing what the ESC shortcut does on search (clear the ?highlight= query but don't remove the highlighting).

[mgeier]

I would like to second @jdillard, because I also think sending a link with highlighting can be useful, e.g.:

https://www.sphinx-doc.org/en/master/usage/theming.html?highlight=navigation_with_keys#builtin-themes

Without highlighting (and without doing a separate search within the page, which is cumbersome, especially on mobile), the relevant section is quite hard to spot.

But were the highlights specifically something that was a result of a search?

Yes.

Here the search term happens to match the function name, but it could be anything, even something completely irrelevant.

But it could also be something completely relevant, like in my example link above.

Some Sphinx themes such as Furo and now pydata sphinx theme include buttons that you can click to do this for you ("hide search matches" under the search bar in Furo), but it's still an extra step you have to do every time, and you have to actually remember to do it.

I think the real problem is that some themes still don't have such a link (e.g. sphinx_rtd_theme, see readthedocs/sphinx_rtd_theme#816 and readthedocs/sphinx_rtd_theme#876), and most themes that have such a link, don't make it stand out enough.

But that's a problem that has to be solved by the themes, not by Sphinx itself (but granted, it could lead by a better example).

In my own insipid theme, I deliberately tried to make that link clearly visible, see e.g. https://insipid-sphinx-theme.readthedocs.io/usage.html?highlight=alternative%20usage#installation-and-usage

To contrast, I can't think of an instance when I have ever intentionally wanted to share a URL with text highlighting included. And even if I did, there is the text fragment anchor for that (see #10201), and anyway I don't see why I would want to share a URL that highlights the text specifically from a search term.

The search term might be actually the thing the recipient of the link is interested in.
And there might not be a text fragment for just that thing, the relevant section might even be below the visible part of the section, as shown in my example links above.

I agree that sometimes the highlighting isn't necessary (and it should indeed be simple to remove!), but other times it is really useful, and it would be unfortunate if this helpful feature were to be removed.

I've seen similar behaviors with other types of things on other websites.

It would actually be interesting how other websites are doing this. @asmeurer Can you show a few examples?

With my suggestion, you would still be able to manually append ?highlight= to the end of a URL.

This is extremely cumbersome and it is basically impossible to discover.

In comparison, hitting the "Esc" key is very simple, and even if that feature is not known to the visitor, clicking the "hide search matches" link is also very simple.

(whether there should be some other UI for adding it is another question)

I doubt that such an UI would be easy to use, but I'm curious how such a thing would look like. In combination with such a UI @asmeurer's suggestion might be feasible.

[AA-Turner]

#10854 changes the default to localstorage, whilst keeping the ?highlight=... functionality working.

I haven't seen docs highlight functionality elsewhere, to me it seems Sphinx is the outlier here. Highlight support / UI prototyping can also happen in themes or extensions, and can then be considered for the core. (Ideally we'd move the highlighting logic to an extension itself, as it is a lot of JS to maintain in core, but I don't have permissions to add repos in the sphinx-doc org -- @shimizukawa do you know if you're able to grant me those permissions?)

A

[asmeurer]

Wow thanks a lot for changing this. Sphinx 5.2.0 is a huge improvement in many ways.