Allow to enable server side search for MkDocs

[stsewd]

This adds a feature flag to allow us to disable server side search in general and one to test enabling server side search for MkDocs projects.

TODO: regenerate the static assets and tested it locally.

Needs readthedocs/readthedocs-sphinx-ext#85
Closes #1088

[stsewd]

Also, we should document server side search as a feature of RTD, and linking to https://docs.readthedocs.io/en/stable/guides/searching-with-readthedocs.html

[stsewd]

One downside is that users need to trigger a build after activating the flag to disable server side search. And also if users want to test server side search for mkdocs they need to trigger a build (this shouldn't be necessary when we ship this feature globally)

[stsewd]

To avoid these things we could start injecting a custom js per project rather than globally (_/js/rtd-embed.js)

[stsewd]

And here is a comparison of our server side search vs mkdocs search

#6937 (comment)

[ericholscher]

One downside is that users need to trigger a build after activating the flag to disable server side search. And also if users want to test server side search for mkdocs they need to trigger a build (this shouldn't be necessary when we ship this feature globally)

Can we not disable it on the server? We should be able to send it down with the footer data. Also with the Sphinx search, if the RTD search fails we fallback to mkdocs, so we should likely have similar, which would make it not an issue.

[stsewd]

@ericholscher so, I just tested this... but there is a race condition between fetching the footer api and initializing the search. Initializing search is faster. So, we could trigger the search after the footer is fetched (I don't think we want this) or call the api again before searching to fetch the feature flags (probable the same as the option 1, is going to make things slow).

Let me know if you think of a better way or if I should revert to the previous implementation.

[ericholscher]

@stsewd I think the race condition is fine -- I don't think too many people will hit the search before the footer loads. I guess the issue is people landing on the search page itself?

[ericholscher]

@stsewd also, have you done a bit of QA on the current production mkdocs results?

[stsewd]

@stsewd I think the race condition is fine -- I don't think too many people will hit the search before the footer loads. I guess the issue is people landing on the search page itself?

In my local testing the race condition was always present, so the feature flag was always ignored.

@stsewd also, have you done a bit of QA on the current production mkdocs results?

Yeah, those are from the screenshots #6937 (comment)

[ericholscher]

This still needs a bit more thought before we ship it. We should find a solution that works similarly for both sphinx & mkdocs, and use it in both places. It seems we haven't had issues w/ the ability to disable Sphinx search, so we should likely do the same thing as there?

[stsewd]

It seems we haven't had issues w/ the ability to disable Sphinx search, so we should likely do the same thing as there?

To disable sphinx search we require users to define the data.features.docsearch_disabled attribute themselves, so it works after a rebuild as well.

[ericholscher]

@stsewd I'm fine with it matching what we're currently doing on the Sphinx side. I'm 👍 on shipping this behind a feature flag once we do that. Sorry for the confusion here.

[ericholscher]

I feel like we're struggling with this on readthedocs/readthedocs-sphinx-ext#88 as well. We end up with weird race conditions on the search UX because we can't disable the default search for the tool. I'm wondering if there is a better way to handle this, since this seems brittle and likely to cause weird behavior. I don't have a great idea on how to fix it though :/

[stsewd]

So, Mkdocs doesn't highlight the span tag, but it does the mark tag. I got this with just a replace in js.

I can leave that... Or make the server accept an additional param called tag, options would be span and mark for now.

Let me know which one sound good, If we go for 2 can do that in another PR of course

[ericholscher]

I think a simple JS replace is fine. Since this is behind a feature flag, I'm 👍 on shipping it next week.

[stsewd]

@ericholscher readthedocs/readthedocs-sphinx-ext#85 needs to be merged in order to be able to deactivate search in sphinx projects.