elastic / elastic/eui

[Documentation] Add more context to documentation search results

Open
#8,974 5 comments 1 reaction 1 assignee Assigned to @Copilot View on GitHub
documentation
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.

Image

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;

Image

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

Image

### 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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.