DocSearch component supports custom link for results footer component

[kodster28]

What version of starlight are you using?

0.29.3

What is your idea?

Expose an additional configuration options for the docsearch component that allows you to add in a custom link for the props.href piece of the resultsFooterComponent.

Maybe also for the getMissingResultsUrl... but that might be harder, at least evidenced by facebook/docusaurus#10737

Why is this feature necessary?

When you have a large set of docs (like Cloudflare), sometimes the on-page search for Algolia isn't the most helpful.

You search for something and -- upon getting too many results back -- need to get offloaded to a full search engine results page to filter through all the various docs.

As long as that was surfaced where we could specify the path, would be totally fine if the limit to customization was /userpath/?q=<...>.

Bit of color in facebook/docusaurus#10737 as well

Do you have examples of this feature in other projects?

• Algolia docsearch docs
• We used to have this linkage in our Cloudflare docs, but now just have an orphaned full SERP that folks get to via bookmark.

Participation

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

[kodster28]

cc: @KianNH, for viz

[delucis]

Hey @kodster28! Thanks for spinning up the discussion.

This is a bit tricky due to exactly the same limitation Seb Lorber mentions in facebook/docusaurus#10737 (comment) — values in the astro.config.mjs need to be serialized to be used in rendering or client-side JS.

We actually faced the same issue for Astro’s Docs and ended up not using the official Starlight + DocSearch plugin in favour of a custom component instead, but that’s definitely not ideal!

How we usually work around this is having the config provide a path to the thing instead, for example it could look like:

starlightDocSearch({
  // credentials etc.
  clientOptionsModule: './src/docsearch-options.ts',
})

With users than writing something like:

// src/docsearch-options.ts

export default {
  resultsFooterComponent({ state }) {
    // ...
  },
};

Internally we could then wire up importing those options via a virtual module so they worked.

[kodster28]

Yeah, we were evaluating the custom route on our end as well. Which can totally work, just as you mentioned, not ideal.

As long as there's a way to adjust the config a bit more, happy to defer to y'all on the exact implementation of it.

[delucis]

Would you be up for making a PR? If so, happy to share advice about anything/steps needed. I don’t think it’s actually that much code, just wiring things up.

[kodster28]

And.... here's where I tag in @KianNH 😄 .

[KianNH]

👋 #2822

[HiDeoo]

The clientOptionsModule option was released in the version 0.5.0 of the Starlight Docseach plugin 🎉