[Documentation] Add more context to documentation search results
- Dominant language
- TypeScript
- Stars
- 6.4k
- Forks
- 911
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 69
Description
**Problem Statement**
Currently, the EUI documentation search results can be confusing when multiple pages have similar or identical titles. For example, searching for "Sizing" returns results from different sections (Components, Utilities, etc.) without clear context about which page each result belongs to.
A user has provided the following feedback about the documentation search functionality:
> Sometimes, when I search in the search bar (much :elasticheart: for it, by the way), the results are relevant, but for some entries, I’d like to get more context. For example, when I look for “size”, I get two almost identical results titled “Sizing”. However, one of them is in the context of data visualization, while the other is for the theme tokens (which is what I intended from the beginning).
>
> Can we add more context to those search results?
**Proposed Solution**
If you look at the [demo site](https://praveenn77.github.io/docusaurus-lunr-search-demo/docs/tutorial-basics/deploy-your-site) for docusaurus-lunr-search-npm -- it displays additional context for results in a number of places.
I believe these are the templates for those suggestions: https://github.com/praveenn77/docusaurus-lunr-search/blob/86e24fd75e96a4ad15968880ff8ef27a801684d5/src/theme/SearchBar/templates.js
They correspond visually to the following classnames;
Which you can then match to field in the template [here](https://github.com/praveenn77/docusaurus-lunr-search/blob/86e24fd75e96a4ad15968880ff8ef27a801684d5/src/theme/SearchBar/templates.js#L7-L32):
- category-header: category
- subcategory-column-text: subcategory
- title: title
- version: version
Knowing that, it would appear to me that we could attempt to influence the "category" field to show something other than "Sizing", which is the page title.
If we look at what we currently do today (screenshot below), it appears that we populate these fields from:
- category: page title
- subcategory: heading
- title: heading
- version: not populate
### Option 1
If we we are able to, it would be ideal to populate fields in the following way:
- category: site section
- subcategory: page title
- title: heading
We'd have to look closer at [SearchBar](https://github.com/praveenn77/docusaurus-lunr-search/blob/main/src/theme/SearchBar/lunar-search.js#L31 to determine how this logic works to see if it's possible without any customization.
It appears to me that the "category" and "subcategory" correspond to `lvl0` and `lvl1` [here](https://github.com/praveenn77/docusaurus-lunr-search/blob/main/src/theme/SearchBar/lunar-search.js#L33-L36) ... so it could just be a matter of adjust the values populated there. We already [do this in our patch](https://github.com/elastic/eui/blob/main/.yarn/patches/docusaurus-lunr-search-npm-3.6.1-9688befeb3.patch#L73).
### Option 2 (but not ideal)
Alternatively, we could repurpose the "version" field to show the site section or breadcrumbs
- category: page title
- subcategory: heading
- title: heading
- version: site section or breadcrumbs
### Option 3
We already [patch](https://github.com/elastic/eui/blob/main/.yarn/patches/docusaurus-lunr-search-npm-3.6.1-9688befeb3.patch) the [SearchBar](https://github.com/praveenn77/docusaurus-lunr-search/blob/main/src/theme/SearchBar/lunar-search.js#L31). We could just write whatever logic we want into this.
**Use Case**
Docs search, obviously
**Value / Impact**
It's a papercut, but search is one of the most important / most used aspects of docs. It's worth improving.
**Urgency**
Not urgent.
**Do alternatives or workarounds exist?**
Users can still click through multiple results to find what they need.
**Related code or customizations**
N/A
**Additional context (Optional)**
N/A
**Designs or Specs (Optional)**
Contributor guide
Assessment
This issue has not been assessed yet.