Add Section Breadcrumbs to DocSearch Results

[khalidabuhakmeh]

What version of starlight are you using?

5.10.1

What is your idea?

We have documentation that uses similar titles across different sections. Is it possible to show the breadcrumbs leading to the content?

Why is this feature necessary?

Search phrases can show up across documentation, making it visually difficult to discern the correct choice from the results.

Do you have examples of this feature in other projects?

No response

Participation

• I am willing to submit a pull request for this feature.

[delucis]

Thanks for the suggestion @khalidabuhakmeh!

From your screenshot, it looks like you’re actually using Pagefind, which is Starlight’s default search provider (rather than Algolia DocSearch).

Pagefind doesn’t have a breadcrumb feature as far as I can tell looking through their docs, but they do allow for attaching custom metadata to pages, which might work as an alternative? Although these don’t work quite the same way — they are displayed more as “tags” below search results. For example, here’s what it looked like in a quick test:

Visually, you can work around that with the CSS order property, although this isn’t ideal from an accessibility POV as it introduces a difference between visual order and DOM order.

AFAICT, the main draw back to this approach is that custom metadata is displayed as a key–value pair “Key: Value”, so you can’t use it to just display e.g. “Tutorials” above pages in a tutorials section. You’d need to use something like “Section: Tutorials” or “Topic: Tutorials”.

[delucis]

If you’re curious how I tested this out: I used Starlight’s route middleware feature to add a meta tag to the head of each page in the docs:

import { defineRouteMiddleware } from '@astrojs/starlight/route-data';

export const onRequest = defineRouteMiddleware((context) => {
	const { starlightRoute } = context.locals;
	const topic = 'Example';
	starlightRoute.head.push({ tag: 'meta', attrs: { 'data-pagefind-meta': `Topic:${topic}` } });
});

In this test example I’m just applying a static “Example” topic to each page, but you can read e.g. starlightRoute.entry.filePath to apply this dynamically based on path or starlightRoute.entry.data to do it based on Markdown page frontmatter.

[khalidabuhakmeh]

Thanks. I did get confused. I'll give this a shot and report back.

[khalidabuhakmeh]

That works great. Thank you so much.