Revert removal of search highlighting on documentation page

[agjohnson]

The underlying PR #6087 removed the URL params necessary to add highlighting to the linked documentation page, a feature that is very helpful to users. There wasn't much context in the PR about why the change was required or why the solution we made was the correct one.

I would like to revisit this as I'm already missing the highlighting and there are probably better ways to address problems that we were hitting without wholesale removal of a feature that users are probably expecting.

What are the problems with highlighting and why did we come to the solution that we did?

I normally find myself wanting to remove the &hightlight=... from the URL when linking to customers, but more applicable UXs in that case are:

• Have a share button
• Use JS to remove highlight from the URL bar

If the visual additions are the problem, wholesale removal of the feature is definitely the wrong direction to go, as users have no way to opt-in. Opt-out could include any of the following:

• On keypress ESC, highlight classes are removed from elements
• We can show a "Showing X results" bar at the top of the page with a close button that removes highlighting -- this works across all themes

Is the problem is that search queries that are multiple words don't highlight correctly? What percentage of search queries are more than 2 or 3 words? Search queries that are this long seem like an edge case, but we still have more options:

• Fix the sphinx highlighter to match all words
• Removing highlighting only for queries that are more than 2 or 3 words long

[no-response]

This issue has been automatically closed because there has been no response to our request for more information from the original author. With only the information that is currently in the issue, we don't have enough information to take action. Please reach out if you have or find the answers we need so that we can investigate further. Thanks!

[agjohnson]

Dammit bot, shut up.

[mgeier]

Yes, please bring this feature back!

I was surprised that it is suddenly missing.

It is really confusing that it works when building locally and it stops working when built on RTD.

[mgeier]

I've created readthedocs/sphinx_rtd_theme#876 to show a way to get a "Hide Search Matches" link in the RTD theme (like other themes have already). With that, I think there is no reason to disable the search highlighting altogether.

[ericholscher]

I'm 👍 on the theme change, at least. We talked about this and agree we should revert to the Sphinx original functionality and see if we can tweak it to just be better instead of remove it.

[agjohnson]

Going to reopen this, search as you type still does not highlight. The fix in #6914 reverts back to the old search highlight that was removed. I'd rather find a solution that is somewhere in between -- neither user experience is great.

[mgeier]

Use JS to remove highlight from the URL bar

I've just suggested this in sphinx-doc/sphinx#9551.

[agjohnson]

I was going to suggest push state for this, that would be a good middle ground to at least resolve the issue with linking pages with the param.

There is still the issue that Sphinx's default highlighting makes for poor UX on a lot of search queries though:

I'm not sure if we can override this behavior easily, or if that even makes sense -- most likely this is better as an upstream patch at Sphinx though. I know this has been the main hurdle to enabling the highlighting on RTD again though.

[humitos]

I'm closing this issue in favor of readthedocs/addons#36 since it will be implemented in the addons repository if anything.