feat(v2): introduce DocSearch v3 search

[francoischalifour]

Motivation

This PR integrates the new version of DocSearch, that better reflects what we think documentation search should be.

Closes #2808
Closes #2754

Have you read the Contributing Guidelines on pull requests?

Yes.

Test Plan

Try the new search experience by clicking on the search button, or hitting ⌘ + K (or Ctrl + K): https://deploy-preview-2815--docusaurus-2.netlify.app.

---

Hello Docusaurus team! The DocSearch folks at @algolia have been working on a brand new DocSearch frontend the past months: DocSearch 3.

Context

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.

Features

This new DocSearch version offers a brand new user experience with two main UI components: a search button and a search modal. This new pattern allows more search features than the previous dropdown.

User experience (UX)

Modal search

We replaced the dropdown list for a modal. A modal makes the search experience more immersive, allows to support more search-related features (see below) and integrates better on mobile.

We offer a search button that opens the modal, as well a the Cmd + K keyboard shortcut.

Search button

Search modal

Mobile experience

DocSearch 3 was thought with mobile in mind. We've come as closed as we could to a native mobile experience:

• Full-screen view.
• Close virtual keyboard on scroll. Native search patterns blur the input when you start scrolling to give users more space to discover the results displayed behind the keyboard. DocSearch supports this feature out of the box.
• Back to previous scroll position.
• Selection search.

Recent searches

Users often need to jump back to content that they just previously searched. It can be quite annoying to type again what you just typed. We introduced recent searches:

Favorite searches

When you're learning a new framework or a new concept, you often need to come back multiple times to the same content. Users can now build their own start screen by adding searches to their favorites:

Selection search

What if you didn't have to type a query to search for content? A pattern that we believe would prove itself useful is Selection Search. This allows users to find more content related to your selection via DocSearch.

Select content, hit the search button (or click it on desktop):

Search suggestions

Getting to a no results screen without indication can be frustrating. We now display search suggestions to jump back on main topics.

Offline detection

Not knowing why the search experience is loading endlessly or is not returning any results can be frustrating. We now detect when the search servers cannot answer and display data according to your network state.

We're investigating if offline search should be supported by DocSearch.

Dark mode

We support Docusaurus' dark mode:

Search button

Search modal

Color matching

The main colors are customizable via CSS variables for the DocSearch experience to match the Docusaurus websites.

Developer experience (DX)

React components

A recurring feedback from developers who implement DocSearch was the lack of React components. DocSearch has been rewritten in React and exposes React components now.

We'll base the vanilla JavaScript version on this React version with an alias to Preact.

Bundle size

Although this new version provides more features, the bundle is lightweight and compatible with lazy loading.

Lazy loading

Since we now export two components (search button and search modal) we can lazy load the modal to load the code only when needed.

This Docusaurus integration loads the modal code only when users are about the interact with the search: on the search button touch start on mobile and on hover on desktop.

What's next

We've been using this new DocSearch version on docsearch.algolia.com for a couple of weeks and a few users already expressed interest in this version.

Docusaurus is the first platform that we show this new version to. We consider this version as "beta" because it's a brand new direction that we've been reflecting on for over 3 years — we're open to your suggestions.

Once we roll it out to Docusaurus, we'll slowly roll it out to new DocSearch users.

[s-pace]

Thank you for this PR @francoischalifour.

We will propagate the new crawler configuration for the v3 once this is merged :)

[docusaurus-bot]

Deploy preview for docusaurus-2 ready!

Built with commit b42e7e5

https://deploy-preview-2815--docusaurus-2.netlify.app

[lex111]

It is very strange why there are so few results? https://v2.docusaurus.io/search?q=doc
It used to be >200 results.

[s-pace]

The crawl was on its way. Solved @lex111

[krillboi]

@francoischalifour
Question about the "Favourites" feature. Does this save the favourites by writing to cookies? We have a very strict no cookies policy on our site and it would of course be sad to not be able to upgrade to this fantastic search as a result.

[francoischalifour]

@krillboi Both Recent Searches and Favorite Searches use the localStorage API, not cookies. 🙂

[krillboi]

@francoischalifour Alright, I'm asking because of the infamous GDPR stuff, of which we try to avoid having a banner at all, but I'm not sure we can avoid having one when it saves information locally (both cookies and localstorage).

As a future request, perhaps having the ability to disable favourites/recent altogether could be an option :)

[Shipow]

Regarding the GDPR stuff I do believe the recent/favorites searches are acting like a shopping cart and no personal information are stored, we don't deal with identity of any kind. We'll obviously verify that but it seems that this category of use case doesn't require any banners/consentement. I'd be happy if you could double check that on your side too.

[swieczorek]

It would be great to have it merged, looking forward to it.

Good job 👍

[lex111]

First of all, I wanted to point out that this is a greatest improvement, I really like it, we will definitely include it in the upcoming Docusaurus release! But before that, we need to work on something to achieve an even better result.

1. New search box in navbar catches the eye -- it stands out from all other UI elements of navbar. We don't need to focus on this particular element that way.

I would make the background not so dark, rather the background from the current implementation is more suitable. In addition, I think it is necessary to reduce its height by analogy the current search input.

BTW keyboard elements doesn’t look well on my Linux computer, eg, the text of “CTRL” is poorly read (see first screnshoot above).

Therefore, other keyboard elements in SVG look much clearer than if they are stylized using CSS. Maybe it makes sense to switch to use SVG icons in the search box too?

In addition, in the dark mode, I believe that we also need to adopt the background from the current search.

New	Old

The shadow of the keyboard icons is pretty visible, maybe it reduce it?

2. On small screens (eg iPhone 5), we see that the search navbar is positioned incorrectly. Earlier, in the previous release we did only display the search icon on mobiles, you can look at refactor(v2): show search icon only on mobiles #2791 for more details.

In this implementation search, I think we need to do the same. (Although in my opinion it looks worse than in the current version. Maybe the search in oval form looks better than a round one. Or the new magnifier icon is not very strong -- I'm not sure).

Issue on small mobiles	Proposed solution

3. Instead of a hard-coded magenta color, is it better for us to use the primary color website to style a new search?

Current behavior	Proposed solution based on a website styling (by example of Docusaurus)

4. Minor bugs:

• The vertical scroll bar is displayed even if there is no scrollable content. Can we show it only when it is really needed?

---

Also see my notes for lines of code below.

[Shipow]

Thanks a lot, very helpful and fair feedback @lex111, we are currently setting up a browser stack env to test on more configs. I also personally just switched to my PC to give more love to the UI there, it has been developed and fine tweaked mainly on macOS so far (small team, not enough diversity ^^). Do you have a browser and os compatibility list you'd like to cover with Docusaurus?

[lex111]

There is a issue with not exactly accurate displaying the keyboard element of CTRL on all OS other than macOS, I suppose.

But it would be great to use SVG in navbar search, as it produces pretty clear font rendering.

Do you have a browser and os compatibility list you'd like to cover with Docusaurus?

We do not have much preference for this, we do not even support IE11, but just want to see smoothest and niceness UI.

[fishcharlie]

Why Command + K? I've never seen a search that uses that as the keyboard shortcut.

[yangshun]

cmd + k is quite common actually, it's used in Messenger, Slack, Discord, Telegram, but more of searching for users. To focus on the search bar, the more common practice is to use /.

[slorber]

thanks @francoischalifour

Can you add a little bit of doc in the Algolia plugin to explain how to sync the Docusaurus style to Algolia style?

Just a simple example, with a link to the github d2 website custom.css source file would likely be helpful for the users, as we won't do this sync automatically.

• rebase :)

[Shipow]

LGTM, great work ^^

[slorber]

Unfortunately I don't see the styles being applied correctly in the deploy preview

[slorber]

awesome, finally fixed this last weird linebreak issue 👍

we can merge now 🎊 thanks

[krillboi]

@krillboi has expressed the need to avoid using local storage: #2815 (comment)
Do we have an option that permits this? What should we say to users that want no local storage usage?

From @docsearch/react 1.0.0-alpha.23, you'll be able to bail out of Local Storage features (recent and favorite searches) with the option disableUserPersonalization that you can pass in the algolia field of your Docusaurus configuration.

@francoischalifour does this mean that the newly released Docusaurus 2.0.0-alpha.59 version supports this option?

[slorber]

Yes it should work

[krillboi]

Awesome!