Pagefind Result Filtering/Categories

[lorenzolewis]

What version of starlight are you using?

0.28.2

What is your idea?

With the default Pagefind search implementation we have in Starlight we don't have any ability to group or categorize search results. We can see a similar view of this on the Astro Docs implementation backed by Algolia to curate groups of results:

Pagefind uses this on their own site to allow a user to select which category to view results in:

Implementation

My idea would be to extend the work started in #2371 and to add an additional, optional property to the pagefind object called filter that can accept a string or array of strings (in the case where a page should appear in multiple results). It may even be possible to allow a developer to define an enum to ensure that they don't have any typos with filters.

Then that could be passed into the HTML in the same manner when building a page as the rest of the Pagefind configuration options are.

Concerns & Questions

A concern with this approach is that it can be very manual. If we continue with the Guides and References example above, we could imagine all guides being placed in src/content/docs/guides and all references in src/content/docs/api. By only exposing an additional front matter property, this does not give users any way to automate this grouping based exclusively on the location of a file. As far as I'm aware, there is not a way to pass a function to the user schema that would pass the filename or ID of an entry and allow a developer to dynamically parse it to derive a category based on filename. How could we make this property to be dynamically generated by users based on the filesystem if desired?

Additionally, if we copy the UI of Astro Docs now, it does not provide readers with any control to collapse or filter the results themselves, instead it is only used as a way to group sections and results. I personally feel we could stick with the current Astro Docs UI and if a user wanted to do anything beyond that or introduce more interactivity then they can override the search component.

Why is this feature necessary?

When having large documentation sites it can be useful to group results. For example, you may have a Guides group and References group. Since guides could be a more approachable entry-point for readers then the site authors may wish to have any results from Guides to be included at the top.

Another example could be for a site that maintains multiple packages. Site authors could use these filters to show results in sections per package to make the results more easy to digest for readers.

Do you have examples of this feature in other projects?

Astro Docs (Algolia): https://docs.astro.build/
Pagefind Docs: https://pagefind.app

Participation

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

[lorenzolewis]

For the concern about allowing a user-created function to used to define pagefind.filter, I'm curious if the new Loader API in Astro 5 could somehow unlock this for us? In theory a user could define a custom loader that matches the required schema needed by Starlight and it's fields, although I have no idea how that interface would look like in practice.

[MacStasy]

Can we also add https://pagefind.app/docs/ui/#show-empty-filters as an option to filters then?
I currently am playing around with the pagefind filters in Starlight and in my experience the default behavior of showing empty filters can be overwhelming for the user when there are a lot of filters in pagefind.