Show suggested pages on 404 page

[delucis]

@saif-shines suggested this a few weeks ago, so I’m capturing it in a feature request before we forget.

---

What version of starlight are you using?

0.36.1

What is your idea?

The basic idea is to try to suggest pages a user may be interested in based on the 404 URL.

For example, if a user lands on /internationaliztion-guide, search for "internationaliztion guide" and render the results to the 404 page.

Why is this feature necessary?

This may help a user find what they’re looking for more quickly when faced with a 404. Instead of our default suggestion to “Check the URL or try using the search bar.” we would provide some immediate options for them to pick from.

Do you have examples of this feature in other projects?

I’m sure I’ve seen this before, but can’t point to anything off the top of my head.

Participation

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

[delucis]

Some considerations:

• We support multiple search providers so we'd have to provide a way to override this feature just like we do for the primary Search component.
• We probably would want this supported in our official Algolia DocSearch package as well as the default Pagefind.
• This has to be done client-side given the 404 is most often rendered statically and won’t know the mistaken URL at build time.
• For users with custom 404 pages, should there be a component or API they can use to replicate the behaviour? For example, in the Starlight docs we have a 404.md for each language. I suppose these users might need to import and place a suggestion component in their custom 404s if they want to preserve that functionality.

I tested this idea out when it was first suggested to see how it might work. It is possible with relatively little code for a basic PoC:

<page-suggestions>
  <p>Loading suggested pages…</p>
</page-suggestions>

<script type="module">
  const pagefind = await import("/pagefind/pagefind.js");
  pagefind.init();

  const { pathname } = window.location;
  const query = pathname
    .replaceAll(/[^A-z0-9]/g, ' ') // way too simple, would wreck non-Latin languages
    .replaceAll(/\s+/g, ' ')
    .trim();

  const search = await pagefind.search(query);
  const results = await Promise.all(search.results.slice(0, 3).map((result) => result.data()));

  class Suggestions extends HTMLElement {
    connectedCallback() {
      const p = this.querySelector('p');
      const list = document.createElement('ul');
      for (const result of results) {
        const li = document.createElement('li');
        const link = document.createElement('a');
        link.href = result.url;
        link.textContent = result.meta.title;
        li.append(link);
        list.append(li);
      }
      p.textContent = 'Maybe you were looking for one of these pages?';
      this.append(list);
      console.log(results);
    }
  }
  customElements.define('page-suggestions', Suggestions);
</script>

(The <script type="module"> is a bit of a hack so I could quickly reuse the existing Pagefind client code, but we would do this properly and import the search client.)