From e1873834d4a4328084a9ac056a089ee5b8f13103 Mon Sep 17 00:00:00 2001
From: Chris Swithinbank
Date: Mon, 13 Jan 2025 11:47:55 +0100
Subject: Upgrade Pagefind to 1.3.0 and configure Pagefind logging levels
 (#2728)

Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com>
---
 .changeset/long-pears-shop.md                      |  7 ++++
 .changeset/young-plants-fetch.md                   |  5 +++
 docs/src/content/docs/reference/configuration.mdx  | 20 +++++++++-
 package.json                                       |  2 +-
 .../__tests__/basics/config-errors.test.ts         |  9 ++++-
 packages/starlight/components/Search.astro         |  3 ++
 packages/starlight/index.ts                        | 23 +++++++++--
 .../starlight/integrations/virtual-user-config.ts  |  1 +
 packages/starlight/package.json                    |  4 +-
 packages/starlight/schemas/pagefind.ts             | 44 +++++++++++++++++++++
 packages/starlight/utils/user-config.ts            | 22 +++++++----
 packages/starlight/virtual-internal.d.ts           |  6 +++
 pnpm-lock.yaml                                     | 46 +++++++++++-----------
 13 files changed, 153 insertions(+), 39 deletions(-)
 create mode 100644 .changeset/long-pears-shop.md
 create mode 100644 .changeset/young-plants-fetch.md
 create mode 100644 packages/starlight/schemas/pagefind.ts

diff --git a/.changeset/long-pears-shop.md b/.changeset/long-pears-shop.md
new file mode 100644
index 00000000..5bec6019
--- /dev/null
+++ b/.changeset/long-pears-shop.md
@@ -0,0 +1,7 @@
+---
+'@astrojs/starlight': minor
+---
+
+Updates minimum Pagefind dependency to v1.3.0, sets new defaults for Pagefind’s ranking options, and adds support for manually configuring the ranking options
+
+The new ranking option defaults have been evaluated against Starlight’s own docs to improve the quality of search results. See [“Customize Pagefind's result ranking”](https://pagefind.app/docs/ranking/) for more details about how they work.
\ No newline at end of file
diff --git a/.changeset/young-plants-fetch.md b/.changeset/young-plants-fetch.md
new file mode 100644
index 00000000..556c973a
--- /dev/null
+++ b/.changeset/young-plants-fetch.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Fixes Pagefind logging to respect the Astro log level. When using Astro’s `--verbose` or `--silent` CLI flags, these are now respected by Pagefind as well.
diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx
index f4ceb57d..28132f34 100644
--- a/docs/src/content/docs/reference/configuration.mdx
+++ b/docs/src/content/docs/reference/configuration.mdx
@@ -447,16 +447,32 @@ When using custom themes and setting this to `true`, you must provide at least o
 
 ### `pagefind`
 
-**type:** `boolean`  
+**type:** <code>boolean | <a href="#pagefindoptions">PagefindOptions</a></code>  
 **default:** `true`
 
-Define whether Starlight’s default site search provider [Pagefind](https://pagefind.app/) is enabled.
+Configure Starlight’s default site search provider [Pagefind](https://pagefind.app/).
 
 Set to `false` to disable indexing your site with Pagefind.
 This will also hide the default search UI if in use.
 
 Pagefind cannot be enabled when the [`prerender`](#prerender) option is set to `false`.
 
+Set `pagefind` to an object to configure the Pagefind search client.
+See [“Customize Pagefind's result ranking”](https://pagefind.app/docs/ranking/) in the Pagefind documentation for more details about using the `pagefind.ranking` option to control how search result ranking is calculated.
+
+#### `PagefindOptions`
+
+```ts
+interface PagefindOptions {
+	ranking?: {
+		pageLength?: number;
+		termFrequency?: number;
+		termSaturation?: number;
+		termSimilarity?: number;
+	};
+}
+```
+
 ### `prerender`
 
 **type:** `boolean`  
diff --git a/package.json b/package.json
index 627a5464..06ad3495 100644
--- a/package.json
+++ b/package.json
@@ -33,7 +33,7 @@
     {
       "name": "/_astro/*.js",
       "path": "examples/basics/dist/_astro/*.js",
-      "limit": "23.5 kB",
+      "limit": "27 kB",
       "gzip": true
     },
     {
diff --git a/packages/starlight/__tests__/basics/config-errors.test.ts b/packages/starlight/__tests__/basics/config-errors.test.ts
index ed0d7374..426f5ae2 100644
--- a/packages/starlight/__tests__/basics/config-errors.test.ts
+++ b/packages/starlight/__tests__/basics/config-errors.test.ts
@@ -63,7 +63,14 @@ test('parses valid config successfully', () => {
 		  "isUsingBuiltInDefaultLocale": true,
 		  "lastUpdated": false,
 		  "locales": undefined,
-		  "pagefind": true,
+		  "pagefind": {
+		    "ranking": {
+		      "pageLength": 0.1,
+		      "termFrequency": 0.1,
+		      "termSaturation": 2,
+		      "termSimilarity": 9,
+		    },
+		  },
 		  "pagination": true,
 		  "prerender": true,
 		  "tableOfContents": {
diff --git a/packages/starlight/components/Search.astro b/packages/starlight/components/Search.astro
index e4398cdb..b5847608 100644
--- a/packages/starlight/components/Search.astro
+++ b/packages/starlight/components/Search.astro
@@ -76,6 +76,8 @@ if (project.trailingSlash === 'never') dataAttributes['data-strip-trailing-slash
 </script>
 
 <script>
+	import { pagefindUserConfig } from 'virtual:starlight/pagefind-config';
+
 	class SiteSearch extends HTMLElement {
 		constructor() {
 			super();
@@ -139,6 +141,7 @@ if (project.trailingSlash === 'never') dataAttributes['data-strip-trailing-slash
 					// @ts-expect-error — Missing types for @pagefind/default-ui package.
 					const { PagefindUI } = await import('@pagefind/default-ui');
 					new PagefindUI({
+						...pagefindUserConfig,
 						element: '#starlight__search',
 						baseUrl: import.meta.env.BASE_URL,
 						bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/pagefind/',
diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
index 26858b84..910601ba 100644
--- a/packages/starlight/index.ts
+++ b/packages/starlight/index.ts
@@ -8,7 +8,7 @@
 /// <reference path="./virtual.d.ts" />
 
 import mdx from '@astrojs/mdx';
-import type { AstroIntegration } from 'astro';
+import type { AstroIntegration, AstroIntegrationLogger } from 'astro';
 import { AstroError } from 'astro/errors';
 import { spawn } from 'node:child_process';
 import { dirname, relative } from 'node:path';
@@ -145,13 +145,14 @@ export default function StarlightIntegration(
 				injectPluginTranslationsTypes(pluginTranslations, injectTypes);
 			},
 
-			'astro:build:done': ({ dir }) => {
+			'astro:build:done': ({ dir, logger }) => {
 				if (!userConfig.pagefind) return;
+				const loglevelFlag = getPagefindLoggingFlags(logger.options.level);
 				const targetDir = fileURLToPath(dir);
 				const cwd = dirname(fileURLToPath(import.meta.url));
 				const relativeDir = relative(cwd, targetDir);
 				return new Promise<void>((resolve) => {
-					spawn('npx', ['-y', 'pagefind', '--site', relativeDir], {
+					spawn('npx', ['-y', 'pagefind', ...loglevelFlag, '--site', relativeDir], {
 						stdio: 'inherit',
 						shell: true,
 						cwd,
@@ -161,3 +162,19 @@ export default function StarlightIntegration(
 		},
 	};
 }
+
+/** Map the logging level of Astro’s logger to one of Pagefind’s logging level flags. */
+function getPagefindLoggingFlags(level: AstroIntegrationLogger['options']['level']) {
+	switch (level) {
+		case 'silent':
+		case 'error':
+			return ['--silent'];
+		case 'warn':
+			return ['--quiet'];
+		case 'debug':
+			return ['--verbose'];
+		case 'info':
+		default:
+			return [];
+	}
+}
diff --git a/packages/starlight/integrations/virtual-user-config.ts b/packages/starlight/integrations/virtual-user-config.ts
index c2cd662a..cef33dde 100644
--- a/packages/starlight/integrations/virtual-user-config.ts
+++ b/packages/starlight/integrations/virtual-user-config.ts
@@ -100,6 +100,7 @@ export function vitePluginStarlightUserConfig(
 			} catch {}
 			export const collections = userCollections;`,
 		'virtual:starlight/plugin-translations': `export default ${JSON.stringify(pluginTranslations)}`,
+		'virtual:starlight/pagefind-config': `export const pagefindUserConfig = ${JSON.stringify(opts.pagefind || {})}`,
 		...virtualComponentModules,
 	} satisfies Record<string, string>;
 
diff --git a/packages/starlight/package.json b/packages/starlight/package.json
index 7f30aff2..c104cdf7 100644
--- a/packages/starlight/package.json
+++ b/packages/starlight/package.json
@@ -192,7 +192,7 @@
   "dependencies": {
     "@astrojs/mdx": "^4.0.5",
     "@astrojs/sitemap": "^3.2.1",
-    "@pagefind/default-ui": "^1.0.3",
+    "@pagefind/default-ui": "^1.3.0",
     "@types/hast": "^3.0.4",
     "@types/js-yaml": "^4.0.9",
     "@types/mdast": "^4.0.4",
@@ -207,7 +207,7 @@
     "mdast-util-directive": "^3.0.0",
     "mdast-util-to-markdown": "^2.1.0",
     "mdast-util-to-string": "^4.0.0",
-    "pagefind": "^1.0.3",
+    "pagefind": "^1.3.0",
     "rehype": "^13.0.1",
     "rehype-format": "^5.0.0",
     "remark-directive": "^3.0.0",
diff --git a/packages/starlight/schemas/pagefind.ts b/packages/starlight/schemas/pagefind.ts
new file mode 100644
index 00000000..7889f330
--- /dev/null
+++ b/packages/starlight/schemas/pagefind.ts
@@ -0,0 +1,44 @@
+import { z } from 'astro/zod';
+
+const pagefindSchema = z.object({
+	/** Configure how search result rankings are calculated by Pagefind. */
+	ranking: z
+		.object({
+			/**
+			 * Set Pagefind’s `pageLength` ranking option.
+			 *
+			 * The default value is `0.1` and values must be in the range `0` to `1`.
+			 *
+			 * @see https://pagefind.app/docs/ranking/#configuring-page-length
+			 */
+			pageLength: z.number().min(0).max(1).default(0.1),
+			/**
+			 * Set Pagefind’s `termFrequency` ranking option.
+			 *
+			 * The default value is `0.1` and values must be in the range `0` to `1`.
+			 *
+			 * @see https://pagefind.app/docs/ranking/#configuring-term-frequency
+			 */
+			termFrequency: z.number().min(0).max(1).default(0.1),
+			/**
+			 * Set Pagefind’s `termSaturation` ranking option.
+			 *
+			 * The default value is `2` and values must be in the range `0` to `2`.
+			 *
+			 * @see https://pagefind.app/docs/ranking/#configuring-term-saturation
+			 */
+			termSaturation: z.number().min(0).max(2).default(2),
+			/**
+			 * Set Pagefind’s `termSimilarity` ranking option.
+			 *
+			 * The default value is `9` and values must be greater than or equal to `0`.
+			 *
+			 * @see https://pagefind.app/docs/ranking/#configuring-term-similarity
+			 */
+			termSimilarity: z.number().min(0).default(9),
+		})
+		.default({}),
+});
+
+export const PagefindConfigSchema = () => pagefindSchema;
+export const PagefindConfigDefaults = () => pagefindSchema.parse({});
diff --git a/packages/starlight/utils/user-config.ts b/packages/starlight/utils/user-config.ts
index 9a47db4c..280f881e 100644
--- a/packages/starlight/utils/user-config.ts
+++ b/packages/starlight/utils/user-config.ts
@@ -5,10 +5,11 @@ import { ExpressiveCodeSchema } from '../schemas/expressiveCode';
 import { FaviconSchema } from '../schemas/favicon';
 import { HeadConfigSchema } from '../schemas/head';
 import { LogoConfigSchema } from '../schemas/logo';
+import { PagefindConfigDefaults, PagefindConfigSchema } from '../schemas/pagefind';
 import { SidebarItemSchema } from '../schemas/sidebar';
+import { TitleConfigSchema, TitleTransformConfigSchema } from '../schemas/site-title';
 import { SocialLinksSchema } from '../schemas/social';
 import { TableOfContentsSchema } from '../schemas/tableOfContents';
-import { TitleConfigSchema, TitleTransformConfigSchema } from '../schemas/site-title';
 import { BuiltInDefaultLocale } from './i18n';
 
 const LocaleSchema = z.object({
@@ -191,11 +192,15 @@ const UserConfigSchema = z.object({
 	expressiveCode: ExpressiveCodeSchema(),
 
 	/**
-	 * Define whether Starlight’s default site search provider Pagefind is enabled.
-	 * Set to `false` to disable indexing your site with Pagefind.
-	 * This will also hide the default search UI if in use.
+	 * Configure Starlight’s default site search provider Pagefind. Set to `false` to disable indexing
+	 * your site with Pagefind, which will also hide the default search UI if in use.
 	 */
-	pagefind: z.boolean().optional(),
+	pagefind: z
+		.boolean()
+		// Transform `true` to our default config object.
+		.transform((val) => val && PagefindConfigDefaults())
+		.or(PagefindConfigSchema())
+		.optional(),
 
 	/** Specify paths to components that should override Starlight’s default components */
 	components: ComponentConfigSchema(),
@@ -227,10 +232,13 @@ export const StarlightConfigSchema = UserConfigSchema.strict()
 	.transform((config) => ({
 		...config,
 		// Pagefind only defaults to true if prerender is also true.
-		pagefind: config.pagefind ?? config.prerender,
+		pagefind:
+			typeof config.pagefind === 'undefined'
+				? config.prerender && PagefindConfigDefaults()
+				: config.pagefind,
 	}))
 	.refine((config) => !(!config.prerender && config.pagefind), {
-		message: 'Pagefind search is not support with prerendering disabled.',
+		message: 'Pagefind search is not supported with prerendering disabled.',
 	})
 	.transform(({ title, locales, defaultLocale, ...config }, ctx) => {
 		const configuredLocales = Object.keys(locales ?? {});
diff --git a/packages/starlight/virtual-internal.d.ts b/packages/starlight/virtual-internal.d.ts
index 10292513..ebf7c8ed 100644
--- a/packages/starlight/virtual-internal.d.ts
+++ b/packages/starlight/virtual-internal.d.ts
@@ -16,6 +16,12 @@ declare module 'virtual:starlight/collection-config' {
 	export const collections: import('astro:content').ContentConfig['collections'] | undefined;
 }
 
+declare module 'virtual:starlight/pagefind-config' {
+	export const pagefindUserConfig: Partial<
+		Extract<import('./types').StarlightConfig['pagefind'], object>
+	>;
+}
+
 declare module 'virtual:starlight/components/Banner' {
 	const Banner: typeof import('./components/Banner.astro').default;
 	export default Banner;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4f305501..32517ed9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -171,8 +171,8 @@ importers:
         specifier: ^3.2.1
         version: 3.2.1
       '@pagefind/default-ui':
-        specifier: ^1.0.3
-        version: 1.0.3
+        specifier: ^1.3.0
+        version: 1.3.0
       '@types/hast':
         specifier: ^3.0.4
         version: 3.0.4
@@ -216,8 +216,8 @@ importers:
         specifier: ^4.0.0
         version: 4.0.0
       pagefind:
-        specifier: ^1.0.3
-        version: 1.0.3
+        specifier: ^1.3.0
+        version: 1.3.0
       rehype:
         specifier: ^13.0.1
         version: 13.0.2
@@ -1746,44 +1746,44 @@ packages:
   /@oslojs/encoding@1.1.0:
     resolution: {integrity: sha512-70wQhgYmndg4GCPxPPxPGevRKqTIJ2Nh4OkiMWmDAVYsTQ+Ta7Sq+rPevXyXGdzr30/qZBnyOalCszoMxlyldQ==}
 
-  /@pagefind/darwin-arm64@1.0.3:
-    resolution: {integrity: sha512-vsHDtvao3W4iFCxVc4S0BVhpj3E2MAoIVM7RmuQfGp1Ng22nGLRaMP6FguLO8TMabRJdvp4SVr227hL4WGKOHA==}
+  /@pagefind/darwin-arm64@1.3.0:
+    resolution: {integrity: sha512-365BEGl6ChOsauRjyVpBjXybflXAOvoMROw3TucAROHIcdBvXk9/2AmEvGFU0r75+vdQI4LJdJdpH4Y6Yqaj4A==}
     cpu: [arm64]
     os: [darwin]
     requiresBuild: true
     dev: false
     optional: true
 
-  /@pagefind/darwin-x64@1.0.3:
-    resolution: {integrity: sha512-NhEXHHYmB/hT6lx5rCcmnVTxH+uIkMAd43bzEqMwHQosqTZEIQfwihmV39H+m8yo7jFvz3zRbJNzhAh7G4PiwA==}
+  /@pagefind/darwin-x64@1.3.0:
+    resolution: {integrity: sha512-zlGHA23uuXmS8z3XxEGmbHpWDxXfPZ47QS06tGUq0HDcZjXjXHeLG+cboOy828QIV5FXsm9MjfkP5e4ZNbOkow==}
     cpu: [x64]
     os: [darwin]
     requiresBuild: true
     dev: false
     optional: true
 
-  /@pagefind/default-ui@1.0.3:
-    resolution: {integrity: sha512-WieFJXvezyvjZh49I8j7a7Kz3LsXYY2Uep3IWvG5NG05mmiurURXjXc+KyrpIp/iAycSnjrC1TDJ8CdES/ee3A==}
+  /@pagefind/default-ui@1.3.0:
+    resolution: {integrity: sha512-CGKT9ccd3+oRK6STXGgfH+m0DbOKayX6QGlq38TfE1ZfUcPc5+ulTuzDbZUnMo+bubsEOIypm4Pl2iEyzZ1cNg==}
     dev: false
 
-  /@pagefind/linux-arm64@1.0.3:
-    resolution: {integrity: sha512-RGsMt4AmGT8WxCSeP09arU7Za6Vf/We4TWHVSbY7vDMuwWql9Ngoib/q1cP9dIAIMdkXh9ePG/S3mGnJYsdzuQ==}
+  /@pagefind/linux-arm64@1.3.0:
+    resolution: {integrity: sha512-8lsxNAiBRUk72JvetSBXs4WRpYrQrVJXjlRRnOL6UCdBN9Nlsz0t7hWstRk36+JqHpGWOKYiuHLzGYqYAqoOnQ==}
     cpu: [arm64]
     os: [linux]
     requiresBuild: true
     dev: false
     optional: true
 
-  /@pagefind/linux-x64@1.0.3:
-    resolution: {integrity: sha512-o+VCKaqImL42scSH1n5gUfppYSNyu3BuGTvtKKgWHmycbL+A3fkFH+ZOFbaLeN7LVTvJqJIOYbk4j2yaq9784Q==}
+  /@pagefind/linux-x64@1.3.0:
+    resolution: {integrity: sha512-hAvqdPJv7A20Ucb6FQGE6jhjqy+vZ6pf+s2tFMNtMBG+fzcdc91uTw7aP/1Vo5plD0dAOHwdxfkyw0ugal4kcQ==}
     cpu: [x64]
     os: [linux]
     requiresBuild: true
     dev: false
     optional: true
 
-  /@pagefind/windows-x64@1.0.3:
-    resolution: {integrity: sha512-S+Yq4FyvXJm4F+iN/wRiLvEEF8Xs9lTKGtQGaRHXJslQyl65dytDDPIULXJXIadrDbnMrnTt4C2YHmEUIyUIHg==}
+  /@pagefind/windows-x64@1.3.0:
+    resolution: {integrity: sha512-BR1bIRWOMqkf8IoU576YDhij1Wd/Zf2kX/kCI0b2qzCKC8wcc2GQJaaRMCpzvCCrmliO4vtJ6RITp/AnoYUUmQ==}
     cpu: [x64]
     os: [win32]
     requiresBuild: true
@@ -4986,15 +4986,15 @@ packages:
     resolution: {integrity: sha512-VgXbyrSNsml4eHWIvxxG/nTL4wgybMTXCV2Un/+yEc3aDKKU6nQBZjbeP3Pl3qm9Qg92X/1ng4ffvCeD/zwHgg==}
     dev: true
 
-  /pagefind@1.0.3:
-    resolution: {integrity: sha512-ws7kmMxW6OuxzsOjj3YAx6TYq/54MiE3wfyBM3J5CInbZyBBvM2Z8c8IYvnMkBcb5v2EoB9DewXEekOEiDRu5g==}
+  /pagefind@1.3.0:
+    resolution: {integrity: sha512-8KPLGT5g9s+olKMRTU9LFekLizkVIu9tes90O1/aigJ0T5LmyPqTzGJrETnSw3meSYg58YH7JTzhTTW/3z6VAw==}
     hasBin: true
     optionalDependencies:
-      '@pagefind/darwin-arm64': 1.0.3
-      '@pagefind/darwin-x64': 1.0.3
-      '@pagefind/linux-arm64': 1.0.3
-      '@pagefind/linux-x64': 1.0.3
-      '@pagefind/windows-x64': 1.0.3
+      '@pagefind/darwin-arm64': 1.3.0
+      '@pagefind/darwin-x64': 1.3.0
+      '@pagefind/linux-arm64': 1.3.0
+      '@pagefind/linux-x64': 1.3.0
+      '@pagefind/windows-x64': 1.3.0
     dev: false
 
   /parse-entities@4.0.1:
-- 
cgit