refactor(v2): use new way to get versions for search page #3604
Conversation
lex111
added
the
pr: polish
| @@ -33,9 +35,10 @@ function Search() { | |||
| themeConfig: {algolia: {appId = 'BH4D9OD16A', apiKey, indexName} = {}}, | |||
| } = {}, | |||
| } = useDocusaurusContext(); | |||
| const {versions} = useDocsData(DEFAULT_PLUGIN_ID); | |||
There was a problem hiding this comment.
Not sure about that.
There was a problem hiding this comment.
Almost good, but could fail for some users if they use docs plugin with a custom id.
If user use twice the docs plugin (like ios + android having different versioning schemes), we should rather:
- retrieve all versions, of the 2 plugin instances (
useAllDocsData()is a map pluginId->pluginInstanceData) - show one select per plugin instance
For unversioned docs instances (like community in our site) it's probably not worth it to display the select, but it is useful to show 1 dropdown for iOS and one dropdown for Android, as they don't necessarily have the same versions.
Also, the facet filtering in the query should be adapted to match this multi-instance docs setup that use a different "tag" for ios v1 and android v1, as they are separate docs.
I think this line:
.addFacetRefinement('version', searchVersion)
Should become something like:
.addFacetRefinement('docusaurus_tag',' 'docs-community-current')
All this may seem a bit complicated for little ROI.
I'm not sure it's really worth letting the user do a query such as "docs from iOS v1 OR docs from android v1.1".
Unless you feel like solving this problem, what I suggest temporarily is to assume there's a single version.
Unfortunately, we can't guarantee the user won't provide a pluginId, even if there is a single docs instance, so reading the default plugin id data is not safe by default.
Something like that would be safer:
function useSearchVersions() {
const allDocsData = useAllDocsData();
const pluginIds = Object.keys(allDocsData).length;
if (pluginIds.length === 0) {
return [];
} else {
const pluginData =
allDocsData[DEFAULT_PLUGIN_ID] ?? allDocsData[pluginIds[0]];
return pluginData.versions;
}
}
|
Deploy preview for docusaurus-2 ready! Built with commit b8bc278 |
|
Hi @lex111 I updated your PR with a better docs multi-instance support, and rewired the Algolia facetting to the new tag attribute. For docs single-instance, and sites with only 1 versioned doc instance, it should have no impact at all. For sites with 2 versioned docs instances (quite rare), it will show 2 select menus, with the respective versions for each instance. For our site, it does not make sense to show a dropdown for the community docs instance, as it's unversioned, but you can force display it if needed by removing the
Probably not perfect UX yet, and there are other things we could improve (like the ability to only search in blog or in a specific doc plugin instance) but it should not change anything for 99% of users so I think it's good enough. |
| return Object.entries(allDocsData).reduce((acc, [pluginId, pluginData]) => { | ||
| return {...acc, [pluginId]: pluginData.versions[0].name}; | ||
| }, {}); | ||
| }); |
There was a problem hiding this comment.
instead of just a version string, we now need a version string per plugin instance, so it's now a map
| docsSearchVersionsHelpers.allDocsData, | ||
| ) | ||
| // Do not show a version select for unversioned docs plugin instances | ||
| .filter(([, docsData]) => docsData.versions.length > 1); |
There was a problem hiding this comment.
ensure our "community" docs instance do not lead to a select menu being displayed, as there will never be more than 1 value in this select it's useless
| `docs-${pluginId}-${searchVersion}`, | ||
| ); | ||
| }, | ||
| ); |
There was a problem hiding this comment.
query is like: default OR docs-alpha66 OR docs-community-current, ie we search in pages, blogs, and the selected docs versions .
It's an improvement compared to previous search page as we can now search in pages and blog, which was not possible by using the previous facet filter logic (only searching in docs)
see:
| )}> | ||
| {versionedPluginEntries.map(([pluginId, docsData]) => { | ||
| const labelPrefix = | ||
| versionedPluginEntries.length > 1 ? `${pluginId}: ` : ''; |
There was a problem hiding this comment.
This "label prefix" is not perfect, unfortunately, I'm not sure we have a "label" for the docs version instance, so it's not easy to create a great UX.
I think multi-instance versioning is rare enough so that we can figure this out later, but if you have ideas...
|
@slorber awwwesome! Thank you very much for this! |
|
great you like this :) let's merge then |
Motivation
Using
useDocshook instead of deprecateduseVersioning, also after that (as bonus) we can search by latest (current) version.Have you read the Contributing Guidelines on pull requests?
Yes
Test Plan
Preview.
Related PRs
(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)