feat(search): upgrade DocSearch to v4 #3346

dylantientcheu · 2025-07-28T10:56:29Z

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

changeset-bot · 2025-07-28T10:56:33Z

🦋 Changeset detected

Latest commit: e060e93

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 · 2025-07-28T10:56:34Z

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	`e060e93`
🔍 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 · 2025-07-28T10:57:01Z

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

Here’s what will happen next:

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!
In a few minutes, you’ll be able to see a preview of your changes on Netlify 🤩
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 · 2025-07-28T10:57:06Z

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 · 2025-07-28T12:20:59Z

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 · 2025-07-30T09:36:09Z

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 · 2025-08-15T15:39:53Z

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 · 2025-08-15T15:42:51Z

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.

packages/docsearch/index.ts

packages/docsearch/schema.ts

packages/docsearch/DocSearch.astro

docs/src/content/docs/guides/site-search.mdx

NatanTechofNY · 2025-08-19T15:11:39Z

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 · 2025-08-23T05:42:09Z

Looking forward 🥇 , @NatanTechofNY !

dylantientcheu · 2025-08-26T08:48:59Z

@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 👏

packages/docsearch/index.ts

packages/docsearch/DocSearch.astro

NatanTechofNY · 2025-09-15T16:17:59Z

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

dylantientcheu · 2025-09-30T14:56:09Z

Thanks for the insight i'll work on this.

dylantientcheu · 2025-10-09T12:00:31Z

@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 · 2025-10-13T07:14:49Z

@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 🥳

.changeset/chilly-seals-whisper.md

…to pr/dylantientcheu/3346

.changeset/chilly-seals-whisper.md

Co-authored-by: Felix Schneider <[email protected]>

dylantientcheu · 2025-10-15T12:22:58Z

@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 · 2025-10-15T12:53:50Z

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.

randomguy-2650

I left two tiny comments that don’t affect usability at all, just branding and I’m not really sure what to classify the other one as.

.changeset/chilly-seals-whisper.md

docs/src/content/docs/guides/site-search.mdx

Co-authored-by: randomguy-2650 <[email protected]>

randomguy-2650

LGTM! 🚀

One tiny UI issue I’ve found is this dropdown in Ask AI:

There isn’t a background, at least on Safari 26 on iOS 26.0.1.

You can check this on other browsers, not sure if this is an Algolia issue or Starlight issue.

packages/docsearch/schema.ts

randomguy-2650 · 2025-10-27T16:48:03Z

docs/astro.config.mjs

+						starlightDocSearch({
+							appId: 'PMZUYBQDAK',
+							apiKey: '24b09689d5b4223813d9b8e48563c8f6',
+							indexName: '[Demo][Tmp] Astro Starlight',
+							askAi: 'askAIDemo'
+						}),


I would assume all of this would be removed later, right? Because the Starlight docs use the default search, Pagefind, by default.

This is just to remind you just in case you forget.

randomguy-2650 · 2025-10-27T16:48:25Z

docs/package.json

    "@astrojs/starlight": "workspace:*",
+    "@astrojs/starlight-docsearch": "workspace:*",


Here as well. Replace it with the published versions in the future rather than workspace:*.

we use workspace here because the package is local. We'll not need it, when we'll remove the top comment

github-actions bot added i18n Anything to do with internationalization & translation efforts 📚 docs Documentation website changes 🌟 docsearch Changes to Starlight’s DocSearch plugin labels Jul 28, 2025

delucis reviewed Jul 28, 2025

View reviewed changes

fix: remove unneeded files

3e8a040

dylantientcheu force-pushed the main branch from 4da4fcc to 3e8a040 Compare July 28, 2025 11:58

saif-at-scalekit mentioned this pull request Jul 29, 2025

AI driven algolia search scalekit-inc/developer-docs#186

Draft

7 tasks

HiDeoo reviewed Aug 19, 2025

View reviewed changes

dylantientcheu added 2 commits August 26, 2025 09:42

fix: documentation

c0d686e

fix: based on comments

575a24b

dylantientcheu requested a review from HiDeoo August 26, 2025 08:49

dylantientcheu added 2 commits August 26, 2025 10:50

Merge branch 'main' into main

2b7f591

fix: broken lockfile

0d3149a

HiDeoo reviewed Aug 26, 2025

View reviewed changes

fix: based on comments

9074031

dylantientcheu requested a review from HiDeoo August 26, 2025 16:25

dylantientcheu mentioned this pull request Sep 15, 2025

chore: release v4.0.0 algolia/docsearch#2757

Merged

Merge branch 'main' into main

1a9e73d

dylantientcheu mentioned this pull request Oct 2, 2025

fix: remove hit favorite and hit deletion animations algolia/docsearch#2777

Merged

dylantientcheu added 3 commits October 9, 2025 13:53

fix: bump version

201142c

Merge branch 'main' into main

2747d40

fix: lock file

73bd631

trueberryless approved these changes Oct 10, 2025

View reviewed changes

dylantientcheu added 2 commits October 13, 2025 09:11

fix: changeset

35eebb9

Merge branch 'main' into main

2163c21

dylantientcheu requested a review from trueberryless October 13, 2025 07:14

trueberryless reviewed Oct 13, 2025

View reviewed changes

.changeset/chilly-seals-whisper.md Outdated Show resolved Hide resolved

dylantientcheu added 2 commits October 13, 2025 12:07

fix: changeset message

335f2de

Merge branch 'main' of https://github.com/dylantientcheu/starlight in…

cd98524

…to pr/dylantientcheu/3346

dylantientcheu requested a review from trueberryless October 13, 2025 10:09

trueberryless reviewed Oct 13, 2025

View reviewed changes

.changeset/chilly-seals-whisper.md Outdated Show resolved Hide resolved

Update .changeset/chilly-seals-whisper.md

2400723

Co-authored-by: Felix Schneider <[email protected]>

dylantientcheu changed the title ~~feat(search): upgrade DocSearch to v4-beta~~ feat(search): upgrade DocSearch to v4 Oct 13, 2025

dylantientcheu requested review from trueberryless October 13, 2025 15:50

randomguy-2650 reviewed Oct 26, 2025

View reviewed changes

.changeset/chilly-seals-whisper.md Outdated Show resolved Hide resolved

docs/src/content/docs/guides/site-search.mdx Outdated Show resolved Hide resolved

dylantientcheu and others added 2 commits October 27, 2025 16:05

Update .changeset/chilly-seals-whisper.md

9e50fb8

Co-authored-by: randomguy-2650 <[email protected]>

update site-search.mdx

74ba3af

dylantientcheu requested a review from randomguy-2650 October 27, 2025 16:23

randomguy-2650 approved these changes Oct 27, 2025

View reviewed changes

dylantientcheu added 2 commits October 30, 2025 10:25

update variables.css

ca76fdb

fix variables.css

e060e93

saif-at-scalekit approved these changes Nov 5, 2025

View reviewed changes

		"@astrojs/starlight": "workspace:*",
		"@astrojs/starlight-docsearch": "workspace:*",

Uh oh!

feat(search): upgrade DocSearch to v4 #3346

Are you sure you want to change the base?

feat(search): upgrade DocSearch to v4 #3346

Uh oh!

Conversation

dylantientcheu commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Additional Context & Motivation

What’s in this PR

Features

DocSearch v4

Ask AI (optional)

Related Docs

Uh oh!

changeset-bot bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

netlify bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-starlight ready!

Uh oh!

astrobot-houston commented Jul 28, 2025

Uh oh!

astrobot-houston commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

delucis left a comment

Choose a reason for hiding this comment

Uh oh!

dylantientcheu commented Jul 28, 2025

Uh oh!

dylantientcheu commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

NatanTechofNY commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

delucis commented Aug 15, 2025

Uh oh!

HiDeoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NatanTechofNY commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

saif-at-scalekit commented Aug 23, 2025

Uh oh!

dylantientcheu commented Aug 26, 2025

Uh oh!

HiDeoo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NatanTechofNY commented Sep 15, 2025

Uh oh!

dylantientcheu commented Sep 30, 2025

Uh oh!

dylantientcheu commented Oct 9, 2025

Uh oh!

trueberryless left a comment

Choose a reason for hiding this comment

dylantientcheu commented Jul 28, 2025 •

edited

Loading

changeset-bot bot commented Jul 28, 2025 •

edited

Loading

netlify bot commented Jul 28, 2025 •

edited

Loading

astrobot-houston commented Jul 28, 2025 •

edited

Loading

dylantientcheu commented Jul 30, 2025 •

edited

Loading

NatanTechofNY commented Aug 15, 2025 •

edited

Loading

NatanTechofNY commented Aug 19, 2025 •

edited

Loading