`pagefind.ranking` schema missing `metaWeights` and `diacriticSimilarity`

[mrienstra]

Versions

• starlight: 0.39.2 (latest)
• astro: 6.2.2
• package manager: pnpm
• OS: macOS
• Browser: Chrome

Describe the Bug

Starlight's pagefind.ranking configuration schema is missing two ranking parameters that Pagefind supports: metaWeights and diacriticSimilarity. These options are silently stripped during config validation.

Current behavior

Starlight defines pagefindRankingWeightsSchema in schemas/pagefind.ts with four fields:

• pageLength
• termFrequency
• termSaturation
• termSimilarity

Pagefind's own PagefindRankingWeights type (in pagefind_web_js/types/index.d.ts) defines six:

• pageLength
• termFrequency
• termSaturation
• termSimilarity
• diacriticSimilarity (docs; added in Pagefind v1.2.0, see PR #995)
• metaWeights (docs; added in Pagefind v1.4.0, see commit ebfefd9) — Record<string, number>

Reproduction

// astro.config.mjs
starlight({
  pagefind: {
    ranking: {
      metaWeights: {
        title: 5.0,
        description: 2.0,
      },
    },
  },
})

Expected: Pagefind receives the metaWeights config and applies boosting to metadata field matches.

Actual: Zod's z.object() uses strip mode by default, silently removing unknown keys. The serialized config in the build output contains only the four known fields:

// From dist/_astro/Search.astro_..._.js
{ranking:{pageLength:.1,termFrequency:.1,termSaturation:2,termSimilarity:9}}
// metaWeights is gone

Possible fix

Add the two missing fields to pagefindRankingWeightsSchema:

// schemas/pagefind.ts
const pagefindRankingWeightsSchema = z.object({
  pageLength: z.number().min(0).max(1).default(0.1),
  termFrequency: z.number().min(0).max(1).default(0.1),
  termSaturation: z.number().min(0).max(2).default(2),
  termSimilarity: z.number().min(0).default(9),
  // New fields:
  diacriticSimilarity: z.number().min(0).optional(),
  metaWeights: z.record(z.string(), z.number()).optional(),
});

... and update Starlight docs.

Participation

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

[HiDeoo]

Thanks for the report 🙌

On top on adding the missing fields, I'm wondering if we should also change the pagefindRankingWeightsSchema schema to a z.looseObject. We would still add new properties with proper documentation and validation over time, but it would avoid similar cases where a new property is added in a pagefind minor, not defined in our schema, but still allows the user to use it without it being stripped by Zod.

Any thoughts on this?

[delucis]

Agree with the loose object idea here @HiDeoo 👍

These were two features were added since we created that schema, so we should also probably update Pagefind when adding them so that users don’t get misleading types while using an older Pagefind release that doesn’t support these options.

[mrienstra]

Much appreciated! ❤️