Contextual doc version search (Algolia/DocSearch)

[slorber]

🚀 Feature

A site can be versioned. In such case it's likely we want to use an Algolia DocSearch facet filter so that we don't end up with duplicate results:

    algolia: {
      apiKey: 'x',
      indexName: 'y',
      searchParameters: {
        facetFilters: [`version:${versions[0]}`],
      },
    },

This works, but also has some drawbacks: if you are currently browsing v1, and last version is v2, when you search, you will find v2 results.

We should make this facetting behavior contextual/dynamic, instead of being hardcoded in the site config, and if user is currently browsing v1, we should facet on v1, show him v1 related results.

---

Note: the solution must play well with docs multi-instance support. If you have:

• Android SDK in version v1, v2, v3
• iOS SDK in version v4, v5, v6

What should happen if:

• you type some Android related keyword while you are browsing iOS doc?
• you are not browsing any doc at all (ie you are on the homepage, the blog?)

[amimas]

Is this related to V2? I'm currently using V1 and it works the way you explained it should. Whichever version of documents I am on, the search results are from that version only.

[slorber]

@amimas according to what I see, yes contextual search works on v1, but not on v2.

I see this code on v1 responsible for contextual doc search:

For v2 we'll need something similar, but also take into account docs multi-instance, and maybe it's worth to add the possibility to search non-docs things (blog posts, pages), as it seems currently unsupported on v1.

[slorber]

Important to consider: if we persist a "preferred version" we probably should search in this version when searching on unversioned pages (see also #3543)

[amimas]

For v2 we'll need something similar, but also take into account docs multi-instance

Not sure what is "docs multi-instance" @slorber .

[slorber]

@amimas not well documented yet but you can understand the idea here: #3299

One Docusaurus site can host the doc for 2 sdks (like ios + android) that have different versions/release cycles.

[amimas]

Thanks for the reference @slorber .

Sounds like a neat feature. I am actually doing something like this using V1 already. I have separate Docusaurus V1 instances for different tools and they are all deployed at subfolder from the root of the domain. Each docusaurus instance has its own versioning and search index with algolia. As a result, when you are in a page doing a search, the search is already contextual based on the tool and the version being viewed. A landing page at the root is deployed using another generator that brings the whole site together.

Anyways, if we have "multi-instance" docs in V2, then yes, that should be in the consideration of contextual search.

[slorber]

Great, hope we'll be able to solve your usecase.
Although if you have large sites to assemble it may be better to keep them separated to avoid long build times.

There's already a PR here: #3543, but waiting for Algolia inputs to complete it.