starlight search dev | Astro Lounge | Page 1

oblique hatch Apr 15, 2026, 7:58 AM

#

how can i see and test starlight search in dev mode?

somber sleetBOT Apr 15, 2026, 7:58 AM

#

Hi @oblique hatch. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

Starlight's search (powered by Pagefind) is not available in development mode — it only works in production builds. This is by design, as Pagefind requires a built site to generate its search index.

You can see this noted in Starlight's default UI strings: [Starlight i18n]

"search.devWarning": "Search is only available in production builds. \nTry building and previewing the site to test it out locally."

How to test search locally

To test search, you need to build your site and run the preview server:

Stop the dev server (Ctrl + C)
Run the build command:
```
npm run build
```
Then run the preview command:
```
npm run preview
```

This will serve your built site locally, including a fully functional search index. [Build and preview]

Note: The preview reflects your site as it was when you last ran the build. If you make changes, you'll need to rebuild before they appear in the preview.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@oblique hatch Kapa.ai is still learning and improving, please let me know how I did by reacting below.

oblique hatch Apr 15, 2026, 8:58 AM

#

@somber sleet how can i edit and adapt markup inside element id="starlight__search". in seach.astro override is not deeper than this div

somber sleetBOT Apr 15, 2026, 8:58 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

The knowledge sources do not contain enough information to answer this specific question confidently.

What I can confirm from the knowledge sources is that you can override the Search component in Starlight, which is the component that renders the search UI including the button in the header and the search modal: [Search override]

To override it, you create a custom component and register it:

// astro.config.mjs
starlight({
  components: {
    Search: './src/components/CustomSearch.astro',
  },
});

You can also reuse the built-in Search.astro component inside your override if you only want to add things around it: [Reuse built-in component]

---
import Default from '@astrojs/starlight/components/Search.astro';
---
<Default><slot /></Default>

However, the internal markup inside #starlight__search (the search modal/dialog itself) is rendered by Pagefind's own UI library at runtime — it is not part of Starlight's Astro component tree. This means it cannot be customized through component overrides alone.

For deeper customization of Pagefind's rendered markup, I'd suggest:

Checking Pagefind's own documentation for UI customization options
Using custom CSS to style the #starlight__search element and its children, as described in Starlight's CSS guide

The knowledge sources don't go deeper into this topic, so I'd recommend consulting Pagefind's documentation directly for markup-level customization.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@oblique hatch Kapa.ai is still learning and improving, please let me know how I did by reacting below.

oblique hatch Apr 15, 2026, 9:00 AM

#

@somber sleet in search.astro override comp is only <div id="starlight__search" /> .. and in frontend rendered with children, those i want to adap in markup, but i dont know where cause i cant see any

somber sleetBOT Apr 15, 2026, 9:00 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

Based on the knowledge sources available to me, I cannot provide a confident answer about the internal rendering mechanism of Pagefind's #starlight__search div and where its children are injected.

What the knowledge sources confirm is:

The Search component override is the entry point for customizing search UI [Search override]
The default Search.astro includes "the button in the header and the code for displaying a search modal when it is clicked and loading Pagefind's UI"

The children rendered inside #starlight__search are generated by Pagefind's own JavaScript UI library at runtime — not by any Astro component. This is why you don't see them in the Astro component tree or in any overridable .astro file.

For adapting that markup, the knowledge sources only point to custom CSS as the supported approach: [CSS & Styling]

/* src/styles/custom.css */
#starlight__search .your-target-element {
  /* your styles */
}

For actual markup-level changes inside Pagefind's rendered UI, the knowledge sources do not contain enough information to guide you further. You would need to consult Pagefind's documentation directly, as that UI is outside of Starlight's component system.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@oblique hatch Kapa.ai is still learning and improving, please let me know how I did by reacting below.

oblique hatch Apr 15, 2026, 10:20 AM

#

@somber sleet any chance to adapt message text in .pagefind-ui__message, due to language?

somber sleetBOT Apr 15, 2026, 10:20 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

Yes! Starlight has built-in support for translating Pagefind's UI strings, including messages like the one in .pagefind-ui__message. You do this through Starlight's i18n system using pagefind keys in your translation JSON files. [Starlight i18n]

Here are the available Pagefind translation keys you can set:

{
  "pagefind.clear_search": "Clear",
  "pagefind.load_more": "Load more results",
  "pagefind.search_label": "Search this site",
  "pagefind.filters_label": "Filters",
  "pagefind.zero_results": "No results for [SEARCH_TERM]",
  "pagefind.many_results": "[COUNT] results for [SEARCH_TERM]",
  "pagefind.one_result": "[COUNT] result for [SEARCH_TERM]",
  "pagefind.alt_search": "No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead",
  "pagefind.search_suggestion": "No results for [SEARCH_TERM]. Try one of the following searches:",
  "pagefind.searching": "Searching for [SEARCH_TERM]..."
}

The .pagefind-ui__message element typically displays result count/status messages, which correspond to keys like pagefind.zero_results, pagefind.many_results, pagefind.one_result, etc.

How to set it up

Make sure your i18n collection is configured in src/content.config.ts:

import { defineCollection } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};

Add or edit a JSON file in src/content/i18n/ for your language (e.g. en.json, fr.json) with the pagefind.* keys you want to override:

#

{
  "pagefind.zero_results": "Nothing found for [SEARCH_TERM]",
  "pagefind.many_results": "Found [COUNT] results for [SEARCH_TERM]"
}

This works per locale, so each language file can have its own translated messages.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@oblique hatch Kapa.ai is still learning and improving, please let me know how I did by reacting below.

oblique hatch Apr 15, 2026, 11:25 AM

#

@somber sleet didnt work unfortunally

somber sleetBOT Apr 15, 2026, 11:25 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

I'm sorry to hear that. To help troubleshoot, could you share more details about what specifically didn't work? For example:

Did you add the i18n collection to src/content.config.ts?
Did you create/edit the JSON file in src/content/i18n/ (e.g. en.json)?
Are you testing in a production build (npm run build && npm run preview)? As mentioned earlier, search is not available in dev mode, so translation changes to Pagefind's UI won't be visible there either.

What I can confirm from the knowledge sources is that the correct setup requires both steps: [Starlight i18n]

The i18n collection must be configured in src/content.config.ts:

import { defineCollection } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};

A JSON file like src/content/i18n/en.json with the pagefind.* keys you want to override.

Beyond this, the knowledge sources don't provide further troubleshooting details. If the setup looks correct and it still doesn't work, I'd recommend checking Starlight's GitHub issues for similar reports.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@oblique hatch Kapa.ai is still learning and improving, please let me know how I did by reacting below.

oblique hatch Apr 15, 2026, 11:29 AM

#

@somber sleet

config.ts:

import { docsLoader, i18nLoader } from "<@&1055234544183287879>/starlight/loaders";
import { docsSchema, i18nSchema } from "<@&1055234544183287879>/starlight/schema";
import { defineCollection, z } from "astro:content";

export const collections = {
docs: defineCollection({
loader: docsLoader(),
schema: docsSchema({ extend: z.object({ update: z.string().optional() }) }),
}),
i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};

indeed "i18n" folder inside "content"; inside "i18n" folder file with "de.json" and its values

{
"pagefind.clear_search": "Löschen",
"pagefind.load_more": "Weitere Ergebnisse laden",
"pagefind.search_label": "Diese Seite durchsuchen",
"pagefind.filters_label": "Filter",
"pagefind.zero_results": "Keine Ergebnisse für [SEARCH_TERM]",
"pagefind.many_results": "[COUNT] Ergebnisse für [SEARCH_TERM]",
"pagefind.one_result": "[COUNT] Ergebnis für [SEARCH_TERM]",
"pagefind.alt_search": "Keine Ergebnisse für [SEARCH_TERM]. Zeige stattdessen Ergebnisse für [DIFFERENT_TERM]",
"pagefind.search_suggestion": "Keine Ergebnisse für [SEARCH_TERM]. Versuchen Sie eine der folgenden Suchen:",
"pagefind.searching": "Suche für [SEARCH_TERM]..."
}

somber sleetBOT Apr 15, 2026, 11:29 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

Your setup looks correct based on the knowledge sources. The configuration in content.config.ts and the de.json file structure match exactly what Starlight expects. [Starlight i18n]

A few things to verify:

1. Are you testing in a production build?
Search (and therefore Pagefind's UI translations) only works after running:

npm run build && npm run preview

Changes won't be visible in dev mode (npm run dev).

2. Is German (de) configured as a locale in astro.config.mjs?
The de.json file needs to match a locale you've defined. For example:

starlight({
  defaultLocale: 'en',
  locales: {
    en: { label: 'English' },
    de: { label: 'Deutsch' },
  },
})

If German isn't registered as a locale, Starlight won't apply those translations.

3. Is the filename correct?
The JSON file name must match the lang BCP-47 tag of your locale. If your locale config uses lang: 'de', the file should be de.json. If it uses lang: 'de-DE', it should be de-DE.json.

Beyond these points, the knowledge sources don't provide further troubleshooting details for this specific scenario. If everything above checks out and it still doesn't work, I'd recommend opening an issue on Starlight's GitHub.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@oblique hatch Kapa.ai is still learning and improving, please let me know how I did by reacting below.

oblique hatch Apr 15, 2026, 11:34 AM

#

@somber sleet adding locales to config breaks build - i guess because i didnt have any i18n or local setups at all (cause not needed) .. how can i solve this issue

somber sleetBOT Apr 15, 2026, 11:34 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

The issue is that you're adding locales to your Starlight config, but you don't actually have a multilingual content structure set up. Since you only need German translations for Pagefind's UI strings (not a full multilingual site), you can use a root locale instead — this avoids the need for language-prefixed directories. [Root locale]

Set your site up as a monolingual German site using root:

// astro.config.mjs
starlight({
  title: 'My Docs',
  locales: {
    root: {
      label: 'Deutsch',
      lang: 'de',
    },
  },
})

With this setup:

Your docs stay in src/content/docs/ without any language subfolder
Starlight will pick up src/content/i18n/de.json for UI translations
No language switcher or multilingual routing is enabled

This is exactly the use case described for monolingual sites that just want to override the default language: [Monolingual sites]

"This allows you to override Starlight's default language without enabling other internationalization features for multi-language sites, such as the language picker."

After making this change, rebuild with `npm run build && npm run preview` to test the Pagefind translations.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@oblique hatch Kapa.ai is still learning and improving, please let me know how I did by reacting below.

oblique hatch Apr 15, 2026, 11:37 AM

#

@somber sleet can i somehow adapt search logic a bit - i tyed a word which doesnt exist in files, but it says 2 results, but as seen, not reall ymatching

somber sleetBOT Apr 15, 2026, 11:37 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

The knowledge sources do contain some information about configuring Pagefind's search behavior, specifically around result ranking. You can pass a pagefind configuration object in astro.config.mjs to tune how results are ranked: [Pagefind config]

// astro.config.mjs
starlight({
  pagefind: {
    ranking: {
      termSimilarity: 1.0,  // How much weight to give to similar (fuzzy) terms
      termFrequency: 1.0,   // Weight for how often the term appears
      pageLength: 0.75,     // Normalization for page length
      termSaturation: 1.4,  // Diminishing returns for repeated terms
    },
  },
})

Adjusting termSimilarity downward could reduce fuzzy/partial matches that don't really match your search term.

However, the knowledge sources do not go deeper into how to fully control Pagefind's matching logic (e.g. disabling fuzzy matching entirely or setting a minimum match threshold). For that level of control, you would need to consult Pagefind's own documentation directly, as the knowledge sources only reference it without detailing all available options.

Note: As always, test changes with a production build (npm run build && npm run preview), since search isn't available in dev mode.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@oblique hatch Kapa.ai is still learning and improving, please let me know how I did by reacting below.

oblique hatch Apr 15, 2026, 11:47 AM

#

@somber sleet
Invalid config passed to starlight integration
Hint:
pagefind: Expected type "boolean", received "object"

somber sleetBOT Apr 15, 2026, 11:47 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

This error suggests your version of Starlight doesn't yet support passing an object to the pagefind option — it only accepts a boolean.

The pagefind option accepting an object (with ranking, mergeIndex, etc.) is documented in the Starlight configuration reference [Pagefind config], but this feature may have been added in a newer version of @astrojs/starlight than what you currently have installed.

To fix this, update Starlight to the latest version:

npm install @astrojs/starlight@latest

or with pnpm/yarn:

pnpm add @astrojs/starlight@latest
# or
yarn add @astrojs/starlight@latest

Then rebuild with npm run build && npm run preview to test.

If you're on an older version that only supports a boolean, your only options for pagefind in the config are:

starlight({
  pagefind: true,  // enabled (default)
  // or
  pagefind: false, // disabled
})

In that case, the ranking customization options won't be available until you upgrade.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@oblique hatch Kapa.ai is still learning and improving, please let me know how I did by reacting below.

oblique hatch Apr 15, 2026, 11:48 AM

#

@somber sleet what starlight version is needed? if older, how can i deifne term rankings?

somber sleetBOT Apr 15, 2026, 11:48 AM

#

Let me check the knowledge base for you again. One moment! :books:

#

The knowledge sources do not specify which exact version of Starlight introduced the pagefind object configuration (with ranking options). [Pagefind config]

What I can confirm is:

The feature is documented in the current Starlight configuration reference, so upgrading to the latest version should enable it.
The recommended way to upgrade is: [Updating Starlight]

npx @astrojs/upgrade

This upgrades Starlight and all Astro packages together.

If you're on an older version that doesn't support the object form, the knowledge sources do not describe any alternative way to configure Pagefind's term ranking within Starlight itself. The pagefind option only accepted true or false in older versions, and there is no documented workaround for ranking configuration in that case.

#starlight search dev

How to test search locally

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

The knowledge sources don't go deeper into this topic, so I'd recommend consulting Pagefind's documentation directly for markup-level customization.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

For actual markup-level changes inside Pagefind's rendered UI, the knowledge sources do not contain enough information to guide you further. You would need to consult Pagefind's documentation directly, as that UI is outside of Starlight's component system.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

How to set it up

This works per locale, so each language file can have its own translated messages.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Beyond this, the knowledge sources don't provide further troubleshooting details. If the setup looks correct and it still doesn't work, I'd recommend checking Starlight's GitHub issues for similar reports.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Beyond these points, the knowledge sources don't provide further troubleshooting details for this specific scenario. If everything above checks out and it still doesn't work, I'd recommend opening an issue on Starlight's GitHub.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

After making this change, rebuild with `npm run build && npm run preview` to test the Pagefind translations.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

In that case, the ranking customization options won't be available until you upgrade.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

I'd recommend simply upgrading to the latest Starlight version, which should resolve the error and enable the ranking options.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#starlight search dev

How to test search locally

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

The knowledge sources don't go deeper into this topic, so I'd recommend consulting Pagefind's documentation directly for markup-level customization.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

For actual markup-level changes inside Pagefind's rendered UI, the knowledge sources do not contain enough information to guide you further. You would need to consult Pagefind's documentation directly, as that UI is outside of Starlight's component system.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

How to set it up

This works per locale, so each language file can have its own translated messages.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Beyond this, the knowledge sources don't provide further troubleshooting details. If the setup looks correct and it still doesn't work, I'd recommend checking Starlight's GitHub issues for similar reports.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Beyond these points, the knowledge sources don't provide further troubleshooting details for this specific scenario. If everything above checks out and it still doesn't work, I'd recommend opening an issue on Starlight's GitHub.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

After making this change, rebuild with npm run build && npm run preview to test the Pagefind translations.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

In that case, the ranking customization options won't be available until you upgrade.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

I'd recommend simply upgrading to the latest Starlight version, which should resolve the error and enable the ranking options.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

After making this change, rebuild with `npm run build && npm run preview` to test the Pagefind translations.