feat(search): upgrade DocSearch to v4

[dylantientcheu]

Description

Upgrade DocSearch to v4 in the Astro docs theme. This bumps the dependency, wires the new API, and optionally exposes Ask AI.

Additional Context & Motivation

• 10 years of DocSearch – a decade of better docs discovery

• 5 years since v3 – time for a fresh UI/UX and new features

• We 💙 Astro – first-class integration matters

• DocSearch v4 ships a redesigned modal, better accessibility, mobile polish, and is still 💯 free.

• Ask AI (opt-in) layers conversational Q&A on top of your Algolia index.

  • Ask AI is completely optional and never enabled by default. DocSearch v4 can be used independently of Ask AI, giving you full control over your integration.
  • Interested in trying Ask AI – visit https://docsearch.algolia.com/docs/v4/askai
  • See the full list of supported LLM providers for Ask AI.
  • Read more in the DocSearch v4 documentation and Ask AI documentation.

What’s in this PR

• upgrade @algolia/docsearch-astro → latest stable v4
• expose new askAi prop in DocSearch.astro
• inject extra i18n strings for DocSearch v4 / Ask AI

Playground: https://community.algolia.com/docsearch-playground/ Demo video:

https://github.com/user-attachments/assets/a96bcac1-a8d5-4b4c-9ef0-82a284332605

Features

DocSearch v4

• Modernised UI • Faster load • Recent & favourite searches • Dark-mode aware • ARIA-improved

Ask AI (optional)

• Natural-language Q&A • Free • BYOLLM • Pulls context from your Algolia index • Conversation history

Related Docs

• https://docsearch.algolia.com/docs/docsearch
• https://docsearch.algolia.com/docs/v4/askai/

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: e060e93037a60dd9a46c9f0e052bf9d7d045e4a8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight-docsearch	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify[bot]]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	e060e93037a60dd9a46c9f0e052bf9d7d045e4a8
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/690330a9b982050008805990
😎 Deploy Preview	https://deploy-preview-3346--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 99 (🔴 down 1 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Hello! Thank you for opening your first PR to Starlight! ✨

Here’s what will happen next:

1. Our GitHub bots will run to check your changes. If they spot any issues you will see some error messages on this PR. Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🤩

3. One or more of our maintainers will take a look and may ask you to make changes. We try to be responsive, but don’t worry if this takes a few days.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	guides/site-search.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[dylantientcheu]

Thanks @delucis.

I just updated the docs files. If you need to test the integration, use this commit changes: https://github.com/withastro/starlight/compare/4da4fcc8be9a9d2ba2a44c760c645018c0834795..3e8a040af25fee712d1a7a4b2564c690c0a63975

I had to remove it to keep the PR lean.

[dylantientcheu]

For some reason, I'm unable to make "favoriting" results and "deleting recent searches" function properly. Maybe the event can't propagate properly?

I have no apparent error and I'm having a hard time debugging this. @delucis please, let me know if something pops out during your review

[NatanTechofNY]

Hey @delucis any chance we can get some eyes on this or merge it? There are a few folks waiting for it. Please let us know!

[delucis]

Hi @NatanTechofNY and @dylantientcheu — yes, thanks for your patience!

Do you have a rough timeline of when you’re planning for v4 to move out of beta? I’ll obviously go ahead and review, but I guess we’d time a release to align with the stable v4 release.

[NatanTechofNY]

Thanks for the review @HiDeoo and @delucis, we are aiming for our v4 stable release in the next 2 weeks. We will make the review adjustments

[saif-at-scalekit]

Looking forward 🥇 , @NatanTechofNY !

[dylantientcheu]

@HiDeoo thanks for the thorough review.

I just pushed a few changes to resolve these comments. Let me know if it works for you!

[NatanTechofNY]

@HiDeoo @delucis We have released our stable version. Let us know when this is good to be merged! Thank you

[OliverSpeir]

When over scroll propagates I get trapped and can’t scroll all the way back up to close

This video is on iOS 18.6.2 on https://deploy-preview-3346--astro-starlight.netlify.app/

https://github.com/user-attachments/assets/0417fc27-920e-489c-9d4e-b8f088ec49a5

[dylantientcheu]

When over scroll propagates I get trapped and can’t scroll all the way back up to close

Hey @OliverSpeir , the default search is not docsearch. The implementation you've shown is the default search experience on Astro

[trueberryless]

@dylantientcheu Could you maybe run pnpm i locally with the new package.json updates so the lockfile updates? And then push the lockfile updates, so that the Netlify preview works... My bad, I did forget to mention that in the review...

[dylantientcheu]

Hi @trueberryless, @HiDeoo I added back the changes from https://github.com/withastro/starlight/pull/3346#issuecomment-3126980042 to help deploy that on the preview site. View a preview on the website

[!NOTE] Please remember to remove this config, and return to the default search as they might be revoked anytime.

I have another issue with events not triggering on the component, I suspect it might be related to client side rendering or something. I'm not sure of Astro internals, but please could you have a look?

[trueberryless]

I have another issue with events not triggering on the component, I suspect it might be related to client side rendering or something. I'm not sure of Astro internals, but please could you have a look?

I am not exactly sure what you mean with "events not triggering on the component" as I have not yet taking a closer look at the implementation of the DocSearch.astro component.

As I currently see it we should however keep one thing in mind: The DocSearch index for this PR's preview is built off of the main Starlight branch I think as results also link back to the production deployment. I do not know if this might be the reason why the events are not triggering as you expect.

Double headings

One other thing I noticed: All page titles from each group appear twice (except the title from pages that are not listed under the sidebar configuration in astro.config.ts). So basically all pages that have some "group label" in the astro.config.ts get double headings.

Discovered issue (potentially unrelated)

This also led me to some interesting finding in other languages: The title of the index page does not get translated and I wonder where this string comes from:

I could not find the string Documentation in the astro.config.ts or index.mdx pages (from different languages). Even after a global search in the whole project I could not figure out where this Documentation string comes from. Is this maybe a DocSearch thing as the default Pagefind search does not even show those labels in the results?

[dylantientcheu]

Thanks for the quick review.

The double headings and issue you found happens because Astro index was built for demo purposes–might not be the most optimized for this.

Docsearch works by crawling a page and building an index with data found in the page, sometimes you can enrich or fill certain parts of the data to build a valid information hierarchy. This code shows how this temporary index was built:

As I mentioned in my previous comment, this is not supposed to go to production, it is there just to help see Docsearch V4 and AskAI.

---

The issue I mentioned above is this:

https://github.com/user-attachments/assets/a94c20f7-3ca7-4958-b0e3-d1003351ae9c

As you can see the buttons do not work. I can't grasp why, I strongly believe it has to do with the way we render the component, but I'm not sure, neither do I know how to approach this.

[trueberryless]

Thanks for clarifying!

I'm not sure what the issue exactly is, but I noticed that when you ask the AI something the buttons for the feedback and copying the AI response work perfectly fine. I analyzed it for some time yesterday, but could not find out where the issue lies.

I have some more ideas, but need to try them out before sharing any misinformation. Unfortunately, I'm little bit busy the next week, so we'll see if maybe Chris is back before or HiDeoo spots this tricky error.

[HiDeoo]

As you can see the buttons do not work. I can't grasp why, I strongly believe it has to do with the way we render the component, but I'm not sure, neither do I know how to approach this.

Turns out this is related to how these actions are triggered and some CSS. The associated runFavoriteTransition and runDeleteTransition functions are called by a callback only triggered on onAnimationEnd.

Such animations (DocSearch-Hit--favoriting and DocSearch-Hit--deleting) rely on CSS custom properties like --fav-out-dur, --del-dur, --ease-smooth, and --ease-fast which are not defined in the modal.css file which ends up breaking the animations and thus the buttons.

Quickly importing the style.css which defines these variables fixes the issue altho brings other styling issues. I don't have enough context and knowledge about DocSearch to know what is the best way to fix this properly considering only modal.css is imported right now. Should these variables be defined in modal.css? Should they have a fallback value if the variables don't exist? Should the actions not rely on animations? Etc.

I'm guessing this should be enough info for someone more familiar with DocSearch to figure out the best way to handle this.

[dylantientcheu]

Thanks for the insight i'll work on this.

[dylantientcheu]

@HiDeoo we just upgraded to 4.2 which fixes this issue. The PR should be ready 👍🏽. Please LMK if that works for you.

[!IMPORTANT] Remember the values in astro.config.mjs L194-199 are purely for demo purposes and should not go into production

[dylantientcheu]

@trueberryless done :)

[dylantientcheu]

@trueberryless not to hurry you.

We have a few starlight users that are closely watching this PR. When they ping us, we can't do much, we'd love to get this merged :)

[trueberryless]

Good things take time 😅

From my side, I have nothing to add or reject, but please note that I am not a maintainer. Chris and/or HiDeoo will probably take another close look at the changes.

I am deliberately not giving any time frame; all contributors and maintainers are doing this voluntarily, so I kindly ask for your understanding! Nonetheless, I am already looking forward to this upgrade myself.