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:

Screen.Recording.2025-07-28.at.12.53.00.2.1.mp4

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]

🦋 Changeset detected

Latest commit: 2400723

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]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	2400723
🔍 Latest deploy log	https://app.netlify.com/projects/astro-starlight/deploys/68ecd01c608a3a00080f7271
😎 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: 100 (no change 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.

[delucis]

Thanks for the PR @dylantientcheu!

I’ll take a proper look later, but quick heads up that this PR should only change the English language docs, not the others. Then our translation contributors will PR translations of the updated content. (At least, I’m assuming you’re not fluent in all of these languages 😁)

Should make it easier for you to contribute that way, and easier for us to review too.

[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.

[HiDeoo]

Thanks for the contribution 🙌

While waiting for a timeline for a stable release, I went through the changes for an early review (mostly code, I did not take a good look at the docs changes yet) and left a few comment/questions I have.

Also linking to https://docsearch.algolia.com/docs/migrating-from-v3#translations as a reminder which should be helpful when drafting the changeset for the changes to make sure we include the updated translation keys.

[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!

[HiDeoo]

Thanks for the update 🙌

I left a few final suggestions mostly to clean up some types and to avoid some type-checking issues but this is looking great! From my local testing using the shared playground configuration, I did not run into any issues.

I'll let Chris take a final look as he's the more familiar with the plugin as he built it and he's more familiar with DocSearch specifically than I am.

Congrats on the new major 👏

[NatanTechofNY]

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

[dylantientcheu]

Hi @trueberryless, @HiDeoo I added back the changes from #3346 (comment)
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:

astro.mov

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

[trueberryless]

Nice work 🙌

I think we need a changeset for the @astrojs/starlight-docsearch package. I suggest a minor bump which describes the update to the docsearch package v4 👍

Do you know how to do that?
If not, you should be able to run pnpm changeset and follow the instructions, if unclear, the maintainers can also do that I think 🚀

[dylantientcheu]

@trueberryless done :)

[trueberryless]

Awesome progress 🙌

I left a small comment refining the changeset wording to better fit Astro's changeset guidelines.

Another question: Could you maybe update the PR description to be up-to-date? Eg it currently mentions "beta" updates, but this was in the past, now we are stable 🥳

[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.