Add #searchbox to sidebar for "Hide Search Matches" link #925
Conversation
part of the base sphinx theme, creates a link to remove ?highlight=... from the URL added to sidebar
There was a problem hiding this comment.
you need to add the new searchbox.html in the list here as well: https://github.com/pydata/pydata-sphinx-theme/blob/main/docs/user_guide/layout.rst#L437
|
Added to the layout list. TDD (Twitter Driven Development) FTW! Thanks @asmeurer for the pointer. |
|
As long as we're thinking about this, is it possible to just remove the search term from the URL entirely? I personally see no value in having it there. |
|
re: disable the search entirely, I'm not sure if that's possible in Sphinx or not - maybe we can track that in a follow-up issue? Unless there is quick agreement that this is possible and people want it, it might require more discussion and investigation. |
If you try the build from this PR and check this page: https://pydata-sphinx-theme--925.org.readthedocs.build/en/925/examples/example_pandas.html?highlight=quick+start, clicking on the button not only make the target disapear from the page but also change the URL. @asmeurer is it what you requested ? |
|
No I mean never have it there at all (but still highlight the matches). The only point of having it in the URL is to keep it intact when copy pasting it, but generally when you copy the URL of a page you don't want the highlights dragged along. My knowledge of JavaScript isn't great, but isn't it possible to remove the query parameter from the URL but keep the highlights? Obviously it wouldn't survive a refresh, but I think that's fine. |
|
ok then that's a problem that needs to be handled from Sphinx side as we rely on it for the whole search system. I think it would not be wised to mess with it in our theme and risking incompatibilities with other sphinx extensions that also rely on this mechanic. I'll merge this PR and let you move the issue to the sphiinx repository: https://github.com/sphinx-doc/sphinx |
|
Just a note that it seems what @asmeurer suggests might be possible without changing the behavior of sphinx or the page itself: https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState That seems to suggest you can only remove the |
|
Sure but again are we sure nothing is using it ? As we can't guarantee it I think it's safer to let it as it is from our side and leave it to the advanced developer to add this small JS patch if they want |
The suggested change wouldn't break existing URLs with the highlight query parameter. It would only remove it from the URL bar so it doesn't persist into copied URLs. I've seen Google search results with the
The number of people who are annoyed by this and the number of people who know enough Javascript to fix it are a very small intersection (include me as one of the people who doesn't know how to do it). If you're worried about this, a better option is to implement it but make it configurable. Note that I'm not necessarily saying this needs to be fixed in the theme. Maybe it makes more sense to fix it upstream in Sphinx. I only mentioned it here because it seemed like a relevant place to bring up the discussion. |
|
As mention earlier I think you should open an issue on sphinx directly and reference this PR, they will know better than us the consequences of such a change |
|
I opened an upstream issue in Sphinx here sphinx-doc/sphinx#10833. |
The
#searchboxelement is part of the base sphinx theme, and creates a link to remove?highlight=... from the URL. Usually this is part of the search box in the sidebar, but this theme doesn't use sidebar search, so the "Hide Search Matches" link doesn't have anywhere to go.added to right sidebar, but I'm not 100% sure that's the best place for it:
It's more obvious where this should go in themes that have a sidebar search box, like Furo:
Alternative: custom UI / javascript to remove
?highlight=...from the URL rather than inheriting. It should not be complex to reimplement if this approach doesn't suit the theme.