Update search to DocSearch v3

[shortcuts]

Hello Bootstrap team!

After @mdo requested a DocSearch for the icons website, we thought it was time to bring the Bootstrap search documentation to the next level.

This PR integrates the new version of DocSearch, that better reflects what we think documentation search should be.
It has the advantage to bring results from the documentation but also the icon library where we use a dedicated template to display the icons directly in the search making it straightforward to identify the right one.

Description

Reducing users' efforts to get them started integrating your product is key to adoption. We created DocSearch in 2015 as a community effort to solve this problem.

We've had time to try different approaches since then and would like to propose you a new documentation search experience.

This new experience has been well received and is now live on the Docusaurus v2 integrations, TailwindCSS, React Native, and we working closely with some others major OSS projects.

Preview

Web	Mobile

Changes

You can read about all the new features in the Docusaurus PR (facebook/docusaurus#2815), but here's a summary:

• We replaced the dropdown list for a modal
• You can open the search modal with Ctrl+K, ⌘+K or /
• No hard refresh
• The experience works on mobile and is close to a native mobile experience
• Recent searches
• Favorite searches
• Selection search
• Search suggestions
• Offline detection

The bundle size decreased and we now provide React components which can be lazy loaded.

What's next

This new DocSearch version has been used in production for a couple of months now.

This version is marked as alpha for now because the underlying libraries that we use (e.g., autocomplete-core) are still being worked on at @algolia to make sure that it handles more cases than DocSearch and usual autocomplete search experiences. We plan to go stable in the coming weeks but no major changes will happen to DocSearch.

Let us know what you think!

Possible improvement

Navbar vs Subnav

The SearchBox is currently located in the subnav which is the sticky element.

With this multi-index search, it would make more sense to merge the navs together and make the navbar the sticky one. This feature will allow you to implement your search experience from any pages.

What's this PR doesn't include:

• It only indexes https://v5.getbootstrap.com/ and https://icons.getbootstrap.com/
  • It is possible to merge the versions where the icons are available under the same config
  • It is possible to setup a contextual search where you give more relevance to the content based on the page you are on. (e.g display icons first when you are on the icon page)

Links

• Live version of this PR
• Config file

[XhmikosR]

Thanks for the PR, but I see many unrelated stuff.

1. I don't think it makes sense to have icons code here. We definitely don't need it
2. v5.getbootstrap.com will become getbootstrap.com when we hit stable
3. we were using a variable to identify the docs version your index would use. I still find this way cleaner and I'd like to use it
4. we don't currently load your CSS on purpose and I'd rather keep it that way
5. the same goes for unpkg; I'd rather not use it
6. you have unrelated stuff committed here

I think at this point we are better off dropping this PR and we open an issue when docsearch 1.0.0 is stable.

[Haroenv]

Suggested change

	.replace(/https:\/\/icons.getbootstrap.com\/icons\//g, '')
	.replace(/https:\/\/icons\.getbootstrap\.com\/icons\//g, '')

[Haroenv]

based on the lint error, I think destructuring might not be allowed in this file

[Haroenv]

the url replacing code likely needs to be put back in the v3

[XhmikosR]

@s-pace if there is something needed from our side let me know. Please see my above points :)

[Shipow]

Hi @XhmikosR ,

I feel we might have rushed the PR and the description didn't really help since there are so many things that would need us to discuss but we focused on presenting the new version of DocSearch. What we had in mind is more trying to open the conversation around a POC. This would help us align the stuff we learned about documentation search with your deep knowledge of the community usage.

This proposition was indeed more about providing a search for the icons but I believe there is an opportunity to create a better unified experience with Bootstrap V5 and the new version of DocSearch without disrupting the current search of all anterior versions (so the usage and browser support).

Feel free to join our Discord server to chat about the possibilities that this new version offers, or to jump into my Twitter DMs.

[XhmikosR]

@Shipow All good, it wasn't clear indeed that this was a PoC.

That being said, I still don't see why we'd like to combine the icons project with the main one; they are 2 separate projects.

Also,

1. We are very picky as to what we add in our docs; I'd rather use jsDelivr which we already use since unpkg results in extra redirects. Also, we don't add docsearch in pages that don't need it like the homepage
2. I personally don't like the new icons look (call me old-fashioned), so if we could get away with our current solution, I'd prefer it
3. I can't verify your claims about size with the tools I use; https://packagephobia.com/result?p=docsearch.js%403.0.0-beta.0 and https://bundlephobia.com/result?p=docsearch.js fail for 3.0.0-beta.0. That being said, I did check the PR preview and indeed the JS bundle size is reduced (~44 Kb to ~35 Kb)
4. Some of the new features are more than welcome of course :)

But like I said, I still don't see why we would want to merge 2 different projects. If/when docsearch 3 is stable enough and we have the time to make the switch, happy to do it then.

[Shipow]

@XhmikosR I'll try to resume the logic that made us think that it is a good improvement to enable search across multiple projects.

An important limitation in the current setup is for users who want to search the docs but cannot access it from the homepage. The current positioning of the search is less accessible because it restricted to the documentation and positioned in it's subnav. We designed DocSearch V3 to live in the top nav, it can now understand the page context, prioritize and filter results from different sources, when Mark requested a search for icons it seemed fair to assume that the search could find a better place at top level.

Users would benefit from direct access to all resource of the ecosystem. It's a huge accelerator.
With the tag system it's possible to:

• restrain the source to the current context
• display the related source when there are no results
• enable all the sources on the homepage and content page.

I think the Icon project has a brilliant future, it might really be handy to access them from the docs (eventually only if user starts the query by icon).

Let's make Bootstrap users benefit from the new features and everything else we learned since the implementation of the current version. Again, happy to discuss more about that, being here or in a call