@astrojs/starlight 0.29.3 → 0.30.1

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @astrojs/starlight
 
+## 0.30.1
+
+### Patch Changes
+
+- [#2688](https://github.com/withastro/starlight/pull/2688) [`5c6996c`](https://github.com/withastro/starlight/commit/5c6996cd248e9da735a14e7fcaf638b51f2796bc) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes an issue with autogenerated sidebars when using Starlight with Astro's new Content Layer API where group names would be sluggified.
+
+## 0.30.0
+
+### Minor Changes
+
+- [#2612](https://github.com/withastro/starlight/pull/2612) [`8d5a4e8`](https://github.com/withastro/starlight/commit/8d5a4e8000d9e3a4bb9ca8178767cf3d8bc48773) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds support for Astro v5, drops support for Astro v4.
+
+  #### Upgrade Astro and dependencies
+
+  ⚠️ **BREAKING CHANGE:** Astro v4 is no longer supported. Make sure you [update Astro](https://docs.astro.build/en/guides/upgrade-to/v5/) and any other official integrations at the same time as updating Starlight:
+
+  ```sh
+  npx @astrojs/upgrade
+  ```
+
+  _Community Starlight plugins and Astro integrations may also need to be manually updated to work with Astro v5. If you encounter any issues, please reach out to the plugin or integration author to see if it is a known issue or if an updated version is being worked on._
+
+  #### Update your collections
+
+  ⚠️ **BREAKING CHANGE:** Starlight's internal [content collections](https://docs.astro.build/en/guides/content-collections/), which organize, validate, and render your content, have been updated to use Astro's new Content Layer API and require configuration changes in your project.
+
+  1. **Move the content config file.** This file no longer lives within the `src/content/config.ts` folder and should now exist at `src/content.config.ts`.
+  1. **Edit the collection definition(s).** To update the `docs` collection, a `loader` is now required:
+
+     ```diff
+      // src/content.config.ts
+      import { defineCollection } from "astro:content";
+     +import { docsLoader } from "@astrojs/starlight/loaders";
+      import { docsSchema } from "@astrojs/starlight/schema";
+
+      export const collections = {
+     -  docs: defineCollection({ schema: docsSchema() }),
+     +  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+      };
+     ```
+
+     If you are using the [`i18n` collection](https://starlight.astro.build/guides/i18n/#translate-starlights-ui) to provide translations for additional languages you support or override our default labels, you will need to update the collection definition in a similar way and remove the collection `type` which is no longer available:
+
+     ```diff
+      // 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({ schema: docsSchema() }),
+     +  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+     -  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
+     +  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
+      };
+     ```
+
+  1. **Update other collections.** To update any other collections you may have, follow the [“Updating existing collections”](https://docs.astro.build/en/guides/upgrade-to/v5/#updating-existing-collections) section in the Astro 5 upgrade guide.
+
+  If you are unable to make any changes to your collections at this time, including Starlight's default `docs` and `i18n` collections, you can enable the [`legacy.collections` flag](https://docs.astro.build/en/reference/legacy-flags/) to upgrade to v5 without updating your collections. This legacy flag exists to provide temporary backwards compatibility, and will allow you to keep your collections in their current state until the legacy flag is no longer supported.
+
+### Patch Changes
+
+- [#2669](https://github.com/withastro/starlight/pull/2669) [`310df7d`](https://github.com/withastro/starlight/commit/310df7d6b01f5c4a56540bdba9243fb60dace323) Thanks [@aaronperezaguilera](https://github.com/aaronperezaguilera)! - Adds Catalan UI translations
+
+- [#2664](https://github.com/withastro/starlight/pull/2664) [`62ff007`](https://github.com/withastro/starlight/commit/62ff0074d9a3f82e46f5c62db85c04d87ff5e931) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Publishes provenance containing verifiable data to link a package back to its source repository and the specific build instructions used to publish it.
+
+- [#2670](https://github.com/withastro/starlight/pull/2670) [`0223b42`](https://github.com/withastro/starlight/commit/0223b425249f8d1fa468e367c632467276c9c208) Thanks [@aaronperezaguilera](https://github.com/aaronperezaguilera)! - Adds Spanish UI translations for the Pagefind search modal
+
 ## 0.29.3
 
 ### Patch Changes

package/components/Page.astro

@@ -35,16 +35,14 @@ const pagefindEnabled =
 	Astro.props.entry.slug !== '404' &&
 	!Astro.props.entry.slug.endsWith('/404') &&
 	Astro.props.entry.data.pagefind !== false;
+
+const dataAttributes: DOMStringMap = { 'data-theme': 'dark' };
+if (Boolean(Astro.props.toc)) dataAttributes['data-has-toc'] = '';
+if (Astro.props.hasSidebar) dataAttributes['data-has-sidebar'] = '';
+if (Boolean(Astro.props.entry.data.hero)) dataAttributes['data-has-hero'] = '';
 ---
 
-<html
-	lang={Astro.props.lang}
-	dir={Astro.props.dir}
-	data-has-toc={Boolean(Astro.props.toc)}
-	data-has-sidebar={Astro.props.hasSidebar}
-	data-has-hero={Boolean(Astro.props.entry.data.hero)}
-	data-theme="dark"
->
+<html lang={Astro.props.lang} dir={Astro.props.dir} {...dataAttributes}>
 	<head>
 		<Head {...Astro.props} />
 		<style>

package/components/Search.astro

@@ -12,12 +12,12 @@ const pagefindTranslations = {
 			.map(([key, value]) => [key.replace('pagefind.', ''), value])
 	),
 };
+
+const dataAttributes: DOMStringMap = { 'data-translations': JSON.stringify(pagefindTranslations) };
+if (project.trailingSlash === 'never') dataAttributes['data-strip-trailing-slash'] = '';
 ---
 
-<site-search
-	data-translations={JSON.stringify(pagefindTranslations)}
-	data-strip-trailing-slash={project.trailingSlash === 'never'}
->
+<site-search class={Astro.props.class} {...dataAttributes}>
 	<button
 		data-open-modal
 		disabled

package/index.ts

@@ -137,9 +137,6 @@ export default function StarlightIntegration(
 					scopedStyleStrategy: 'where',
 					// If not already configured, default to prefetching all links on hover.
 					prefetch: config.prefetch ?? { prefetchAll: true },
-					experimental: {
-						globalRoutePriority: true,
-					},
 					i18n: astroI18nConfig,
 				});
 			},

package/integrations/shared/pathToLocale.ts

@@ -1,5 +1,6 @@
 import type { AstroConfig } from 'astro';
 import type { StarlightConfig } from '../../types';
+import { getCollectionPath } from '../../utils/collection';
 import { slugToLocale } from './slugToLocale';
 
 /** Get current locale from the full file path. */
@@ -13,15 +14,14 @@ export function pathToLocale(
 		astroConfig: { root: AstroConfig['root']; srcDir: AstroConfig['srcDir'] };
 	}
 ): string | undefined {
-	const srcDir = new URL(astroConfig.srcDir, astroConfig.root);
-	const docsDir = new URL('content/docs/', srcDir);
+	const docsPath = getCollectionPath('docs', astroConfig.srcDir);
 	// Format path to unix style path.
 	path = path?.replace(/\\/g, '/');
 	// Ensure that the page path starts with a slash if the docs directory also does,
 	// which makes stripping the docs path in the next step work on Windows, too.
-	if (path && !path.startsWith('/') && docsDir.pathname.startsWith('/')) path = '/' + path;
+	if (path && !path.startsWith('/') && docsPath.startsWith('/')) path = '/' + path;
 	// Strip docs path leaving only content collection file ID.
 	// Example: /Users/houston/repo/src/content/docs/en/guide.md => en/guide.md
-	const slug = path?.replace(docsDir.pathname, '');
+	const slug = path?.replace(docsPath, '');
 	return slugToLocale(slug, starlightConfig);
 }

package/integrations/virtual-user-config.ts

@@ -1,6 +1,8 @@
 import type { AstroConfig, HookParameters, ViteUserConfig } from 'astro';
+import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { resolveCollectionPath } from '../utils/collection';
 import type { StarlightConfig } from '../utils/user-config';
 import { getAllNewestCommitDate } from '../utils/git';
 import type { PluginTranslations } from '../utils/plugins';
@@ -15,11 +17,13 @@ export function vitePluginStarlightUserConfig(
 	opts: StarlightConfig,
 	{
 		build,
+		legacy,
 		root,
 		srcDir,
 		trailingSlash,
 	}: Pick<AstroConfig, 'root' | 'srcDir' | 'trailingSlash'> & {
 		build: Pick<AstroConfig['build'], 'format'>;
+		legacy: Pick<AstroConfig['legacy'], 'collections'>;
 	},
 	pluginTranslations: PluginTranslations
 ): NonNullable<ViteUserConfig['plugins']>[number] {
@@ -42,7 +46,19 @@ export function vitePluginStarlightUserConfig(
 	const resolveLocalPath = (path: string) =>
 		JSON.stringify(fileURLToPath(new URL(path, import.meta.url)));
 
-	const docsPath = resolve(fileURLToPath(srcDir), 'content/docs');
+	const rootPath = fileURLToPath(root);
+	const docsPath = resolveCollectionPath('docs', srcDir);
+
+	let collectionConfigImportPath = resolve(
+		fileURLToPath(srcDir),
+		legacy.collections ? './content/config.ts' : './content.config.ts'
+	);
+	// If not using legacy collections and the config doesn't exist, fallback to the legacy location.
+	// We need to test this ahead of time as we cannot `try/catch` a failing import in the virtual
+	// module as this would fail at build time when Rollup tries to resolve a non-existent path.
+	if (!legacy.collections && !existsSync(collectionConfigImportPath)) {
+		collectionConfigImportPath = resolve(fileURLToPath(srcDir), './content/config.ts');
+	}
 
 	const virtualComponentModules = Object.fromEntries(
 		Object.entries(opts.components).map(([name, path]) => [
@@ -56,6 +72,7 @@ export function vitePluginStarlightUserConfig(
 		'virtual:starlight/user-config': `export default ${JSON.stringify(opts)}`,
 		'virtual:starlight/project-context': `export default ${JSON.stringify({
 			build: { format: build.format },
+			legacyCollections: legacy.collections,
 			root,
 			srcDir,
 			trailingSlash,
@@ -63,9 +80,9 @@ export function vitePluginStarlightUserConfig(
 		'virtual:starlight/git-info':
 			(command !== 'build'
 				? `import { makeAPI } from ${resolveLocalPath('../utils/git.ts')};` +
-					`const api = makeAPI(${JSON.stringify(docsPath)});`
+					`const api = makeAPI(${JSON.stringify(rootPath)});`
 				: `import { makeAPI } from ${resolveLocalPath('../utils/gitInlined.ts')};` +
-					`const api = makeAPI(${JSON.stringify(getAllNewestCommitDate(docsPath))});`) +
+					`const api = makeAPI(${JSON.stringify(getAllNewestCommitDate(rootPath, docsPath))});`) +
 			'export const getNewestCommitDate = api.getNewestCommitDate;',
 		'virtual:starlight/user-css': opts.customCss.map((id) => `import ${resolveId(id)};`).join(''),
 		'virtual:starlight/user-images': opts.logo
@@ -79,7 +96,7 @@ export function vitePluginStarlightUserConfig(
 			: 'export const logos = {};',
 		'virtual:starlight/collection-config': `let userCollections;
 			try {
-				userCollections = (await import(${resolveId('./content/config.ts', srcDir)})).collections;
+				userCollections = (await import(${JSON.stringify(collectionConfigImportPath)})).collections;
 			} catch {}
 			export const collections = userCollections;`,
 		'virtual:starlight/plugin-translations': `export default ${JSON.stringify(pluginTranslations)}`,

package/loaders.ts

@@ -0,0 +1,40 @@
+import { glob, type Loader, type LoaderContext } from 'astro/loaders';
+import { getCollectionPathFromRoot, type StarlightCollection } from './utils/collection';
+
+// https://github.com/withastro/astro/blob/main/packages/astro/src/core/constants.ts#L87
+// https://github.com/withastro/astro/blob/main/packages/integrations/mdx/src/index.ts#L59
+const docsExtensions = ['markdown', 'mdown', 'mkdn', 'mkd', 'mdwn', 'md', 'mdx'];
+const i18nExtensions = ['json', 'yml', 'yaml'];
+
+export function docsLoader(): Loader {
+	return {
+		name: 'starlight-docs-loader',
+		load: createGlobLoadFn('docs'),
+	};
+}
+
+export function i18nLoader(): Loader {
+	return {
+		name: 'starlight-i18n-loader',
+		load: createGlobLoadFn('i18n'),
+	};
+}
+
+function createGlobLoadFn(collection: StarlightCollection): Loader['load'] {
+	return (context: LoaderContext) => {
+		const extensions = collection === 'docs' ? docsExtensions : i18nExtensions;
+
+		if (
+			collection === 'docs' &&
+			context.config.integrations.find(({ name }) => name === '@astrojs/markdoc')
+		) {
+			// https://github.com/withastro/astro/blob/main/packages/integrations/markdoc/src/content-entry-type.ts#L28
+			extensions.push('mdoc');
+		}
+
+		return glob({
+			base: getCollectionPathFromRoot(collection, context.config),
+			pattern: `**/[^_]*.{${extensions.join(',')}}`,
+		}).load(context);
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.29.3",
+  "version": "0.30.1",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -158,6 +158,7 @@
     "./internal": "./internal.ts",
     "./props": "./props.ts",
     "./schema": "./schema.ts",
+    "./loaders": "./loaders.ts",
     "./types": "./types.ts",
     "./expressive-code": {
       "types": "./expressive-code.d.ts",
@@ -171,19 +172,19 @@
     "./style/markdown.css": "./style/markdown.css"
   },
   "peerDependencies": {
-    "astro": "^4.14.0"
+    "astro": "^5.0.0"
   },
   "devDependencies": {
-    "@astrojs/markdown-remark": "^5.3.0",
+    "@astrojs/markdown-remark": "^6.0.0",
     "@playwright/test": "^1.45.0",
     "@types/node": "^18.16.19",
-    "@vitest/coverage-v8": "^1.6.0",
-    "astro": "^4.16.10",
+    "@vitest/coverage-v8": "2.1.6",
+    "astro": "^5.0.2",
     "linkedom": "^0.18.4",
-    "vitest": "^1.6.0"
+    "vitest": "2.1.6"
   },
   "dependencies": {
-    "@astrojs/mdx": "^3.1.3",
+    "@astrojs/mdx": "^4.0.1",
     "@astrojs/sitemap": "^3.1.6",
     "@pagefind/default-ui": "^1.0.3",
     "@types/hast": "^3.0.4",
@@ -208,8 +209,12 @@
     "unist-util-visit": "^5.0.0",
     "vfile": "^6.0.2"
   },
+  "publishConfig": {
+    "provenance": true
+  },
   "scripts": {
     "test": "vitest",
+    "test:legacy": "LEGACY_COLLECTIONS=true vitest",
     "test:coverage": "vitest run --coverage",
     "test:e2e": "playwright install --with-deps chromium && playwright test"
   }

package/routes/common.astro

@@ -1,4 +1,5 @@
 ---
+import { render } from 'astro:content';
 import { generateRouteData } from '../utils/route-data';
 import type { Route } from '../utils/routing';
 import Page from '../components/Page.astro';
@@ -9,7 +10,7 @@ export type Props = {
 
 const { route } = Astro.props;
 
-const { Content, headings } = await route.entry.render();
+const { Content, headings } = await render(route.entry);
 const routeData = generateRouteData({ props: { ...route, headings }, url: Astro.url });
 ---
 

package/routes/static/404.astro

@@ -1,8 +1,14 @@
 ---
 import { getEntry } from 'astro:content';
+import project from 'virtual:starlight/project-context';
 import config from 'virtual:starlight/user-config';
-import EmptyContent from '../../components/EmptyMarkdown.md';
-import type { Route, StarlightDocsEntry } from '../../utils/routing';
+import { getCollectionPathFromRoot } from '../../utils/collection';
+import {
+	normalizeCollectionEntry,
+	type Route,
+	type StarlightDocsCollectionEntry,
+	type StarlightDocsEntry,
+} from '../../utils/routing';
 import { BuiltInDefaultLocale } from '../../utils/i18n';
 import CommonPage from '../common.astro';
 
@@ -17,7 +23,7 @@ const entryMeta = { dir, lang, locale };
 
 const fallbackEntry: StarlightDocsEntry = {
 	slug: '404',
-	id: '404.md' as StarlightDocsEntry['id'],
+	id: '404',
 	body: '',
 	collection: 'docs',
 	data: {
@@ -30,15 +36,11 @@ const fallbackEntry: StarlightDocsEntry = {
 		sidebar: { hidden: false, attrs: {} },
 		draft: false,
 	},
-	render: async () => ({
-		Content: EmptyContent,
-		headings: [],
-		remarkPluginFrontmatter: {},
-	}),
+	filePath: `${getCollectionPathFromRoot('docs', project)}/404.md`,
 };
 
-const userEntry = await getEntry('docs', '404');
-const entry = userEntry || fallbackEntry;
+const userEntry = (await getEntry('docs', '404')) as StarlightDocsCollectionEntry;
+const entry = userEntry ? normalizeCollectionEntry(userEntry) : fallbackEntry;
 const route: Route = { ...entryMeta, entryMeta, entry, id: entry.id, slug: entry.slug };
 ---
 

package/style/shiki.css

@@ -1,6 +1,6 @@
 :root {
-	--astro-code-color-text: var(--sl-color-white);
-	--astro-code-color-background: var(--sl-color-gray-6);
+	--astro-code-foreground: var(--sl-color-white);
+	--astro-code-background: var(--sl-color-gray-6);
 	--astro-code-token-constant: var(--sl-color-blue-high);
 	--astro-code-token-string: var(--sl-color-green-high);
 	--astro-code-token-comment: var(--sl-color-gray-2);

package/translations/ca.json

@@ -0,0 +1,42 @@
+{
+  "skipLink.label": "Saltar al contingut",
+  "search.label": "Cercar",
+  "search.ctrlKey": "Ctrl",
+  "search.cancelLabel": "Cancel·lar",
+  "search.devWarning": "La cerca només està disponible a les versions de producció.  \nProva de construir i previsualitzar el lloc per provar-ho localment.",
+  "themeSelect.accessibleLabel": "Seleccionar tema",
+  "themeSelect.dark": "Fosc",
+  "themeSelect.light": "Clar",
+  "themeSelect.auto": "Automàtic",
+  "languageSelect.accessibleLabel": "Seleccionar idioma",
+  "menuButton.accessibleLabel": "Menú",
+  "sidebarNav.accessibleLabel": "Primari",
+  "tableOfContents.onThisPage": "En aquesta pàgina",
+  "tableOfContents.overview": "Sinopsi",
+  "i18n.untranslatedContent": "Aquesta pàgina encara no està disponible en el teu idioma.",
+  "page.editLink": "Edita aquesta pàgina",
+  "page.lastUpdated": "Última actualització:",
+  "page.previousLink": "Pàgina anterior",
+  "page.nextLink": "Pàgina següent",
+  "page.draft": "Aquest contingut és un esborrany i no s'inclourà en les versions de producció.",
+  "404.text": "Pàgina no trobada. Comprova la URL o intenta utilitzar la barra de cerca.",
+  "aside.note": "Nota",
+  "aside.tip": "Consell",
+  "aside.caution": "Precaució",
+  "aside.danger": "Perill",
+  "expressiveCode.copyButtonCopied": "Copiat!",
+  "expressiveCode.copyButtonTooltip": "Copiar al porta-retalls",
+  "expressiveCode.terminalWindowFallbackTitle": "Finestra del terminal",
+  "fileTree.directory": "Directori",
+  "builtWithStarlight.label": "Fet amb Starlight",
+  "pagefind.clear_search": "Netejar",
+  "pagefind.load_more": "Carregar més resultats",
+  "pagefind.search_label": "Cercar pàgina",
+  "pagefind.filters_label": "Filtres",
+  "pagefind.zero_results": "Cap resultat per a: [SEARCH_TERM]",
+  "pagefind.many_results": "[COUNT] resultats per a: [SEARCH_TERM]",
+  "pagefind.one_result": "[COUNT] resultat per a: [SEARCH_TERM]",
+  "pagefind.alt_search": "Cap resultat per a [SEARCH_TERM]. Mostrant resultats per a: [DIFFERENT_TERM]",
+  "pagefind.search_suggestion": "Cap resultat per a [SEARCH_TERM]. Prova alguna d’aquestes cerques:",
+  "pagefind.searching": "Cercant [SEARCH_TERM]..."
+}

package/translations/es.json

@@ -28,5 +28,15 @@
   "expressiveCode.copyButtonTooltip": "Copiar al portapapeles",
   "expressiveCode.terminalWindowFallbackTitle": "Ventana de terminal",
   "fileTree.directory": "Directory",
-  "builtWithStarlight.label": "Hecho con Starlight"
+  "builtWithStarlight.label": "Hecho con Starlight",
+  "pagefind.clear_search": "Limpiar",
+  "pagefind.load_more": "Cargar más resultados",
+  "pagefind.search_label": "Buscar página",
+  "pagefind.filters_label": "Filtros",
+  "pagefind.zero_results": "Ningún resultado para: [SEARCH_TERM]",
+  "pagefind.many_results": "[COUNT] resultados para: [SEARCH_TERM]",
+  "pagefind.one_result": "[COUNT] resultado para: [SEARCH_TERM]",
+  "pagefind.alt_search": "Ningún resultado para [SEARCH_TERM]. Mostrando resultados para: [DIFFERENT_TERM]",
+  "pagefind.search_suggestion": "Ningún resultado para [SEARCH_TERM]. Prueba alguna de estas búsquedas:",
+  "pagefind.searching": "Buscando [SEARCH_TERM]..."
 }

package/translations/index.ts

@@ -2,6 +2,7 @@ import { builtinI18nSchema } from '../schemas/i18n';
 import cs from './cs.json';
 import en from './en.json';
 import es from './es.json';
+import ca from './ca.json';
 import de from './de.json';
 import ja from './ja.json';
 import pt from './pt.json';
@@ -35,6 +36,7 @@ export default Object.fromEntries(
 		cs,
 		en,
 		es,
+		ca,
 		de,
 		ja,
 		pt,

package/utils/collection.ts

@@ -0,0 +1,45 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const collectionNames = ['docs', 'i18n'] as const;
+export type StarlightCollection = (typeof collectionNames)[number];
+
+/**
+ * We still rely on the content collection folder structure to be fixed for now:
+ *
+ * - At build time, if the feature is enabled, we get all the last commit dates for each file in
+ *   the docs folder ahead of time. In the current approach, we cannot know at this time the
+ *   user-defined content folder path in the integration context as this would only be available
+ *   from the loader. A potential solution could be to do that from a custom loader re-implementing
+ *   the glob loader or built on top of it. Although, we don't have access to the Starlight
+ *   configuration from the loader to even know we should do that.
+ * - Remark plugins get passed down an absolute path to a content file and we need to figure out
+ *   the language from that path. Without knowing the content folder path, we cannot reliably do
+ *   so.
+ *
+ * Below are various functions to easily get paths to these collections and avoid having to
+ * hardcode them throughout the codebase. When user-defined content folder locations are supported,
+ * these helper functions should be updated to reflect that in one place.
+ */
+
+export function getCollectionPath(collection: StarlightCollection, srcDir: URL) {
+	return new URL(`content/${collection}/`, srcDir).pathname;
+}
+
+export function resolveCollectionPath(collection: StarlightCollection, srcDir: URL) {
+	return resolve(fileURLToPath(srcDir), `content/${collection}`);
+}
+
+export function getCollectionPathFromRoot(
+	collection: StarlightCollection,
+	{ root, srcDir }: { root: URL | string; srcDir: URL | string }
+) {
+	return (
+		(typeof srcDir === 'string' ? srcDir : srcDir.pathname).replace(
+			typeof root === 'string' ? root : root.pathname,
+			''
+		) +
+		'content/' +
+		collection
+	);
+}

package/utils/git.ts

@@ -55,8 +55,8 @@ function getRepoRoot(directory: string): string {
 	}
 }
 
-export function getAllNewestCommitDate(directory: string): [string, number][] {
-	const repoRoot = getRepoRoot(directory);
+export function getAllNewestCommitDate(rootPath: string, docsPath: string): [string, number][] {
+	const repoRoot = getRepoRoot(docsPath);
 
 	const gitLog = spawnSync(
 		'git',
@@ -67,7 +67,7 @@ export function getAllNewestCommitDate(directory: string): [string, number][] {
 			// In each entry include the name and status for each modified file
 			'--name-status',
 			'--',
-			directory,
+			docsPath,
 		],
 		{
 			cwd: repoRoot,
@@ -105,7 +105,9 @@ export function getAllNewestCommitDate(directory: string): [string, number][] {
 
 	return Array.from(latestDates.entries()).map(([file, date]) => {
 		const fileFullPath = resolve(repoRoot, file);
-		const fileInDirectory = relative(directory, fileFullPath);
+		let fileInDirectory = relative(rootPath, fileFullPath);
+		// Format path to unix style path.
+		fileInDirectory = fileInDirectory?.replace(/\\/g, '/');
 
 		return [fileInDirectory, date];
 	});

package/utils/navigation.ts

@@ -1,5 +1,6 @@
 import { AstroError } from 'astro/errors';
 import config from 'virtual:starlight/user-config';
+import project from 'virtual:starlight/project-context';
 import type { Badge, I18nBadge, I18nBadgeConfig } from '../schemas/badge';
 import type { PrevNextLinkConfig } from '../schemas/prevNextLink';
 import type {
@@ -14,8 +15,9 @@ import { formatPath } from './format-path';
 import { BuiltInDefaultLocale, pickLang } from './i18n';
 import { ensureLeadingSlash, ensureTrailingSlash, stripLeadingAndTrailingSlashes } from './path';
 import { getLocaleRoutes, routes, type Route } from './routing';
-import { localeToLang, slugToPathname } from './slugs';
+import { localeToLang, localizedId, slugToPathname } from './slugs';
 import type { StarlightConfig } from './user-config';
+import { getCollectionPathFromRoot } from './collection';
 
 const DirKey = Symbol('DirKey');
 const SlugKey = Symbol('SlugKey');
@@ -108,7 +110,7 @@ function groupFromAutogenerateConfig(
 			// Match against `foo/anything/else.md`.
 			doc.id.startsWith(localeDir + '/')
 	);
-	const tree = treeify(dirDocs, localeDir);
+	const tree = treeify(dirDocs, locale, localeDir);
 	const label = pickLang(item.translations, localeToLang(locale)) || item.label;
 	return {
 		type: 'group',
@@ -218,16 +220,28 @@ function getBreadcrumbs(path: string, baseDir: string): string[] {
 }
 
 /** Turn a flat array of routes into a tree structure. */
-function treeify(routes: Route[], baseDir: string): Dir {
+function treeify(routes: Route[], locale: string | undefined, baseDir: string): Dir {
 	const treeRoot: Dir = makeDir(baseDir);
+	const collectionPathFromRoot = getCollectionPathFromRoot('docs', project);
 	routes
 		// Remove any entries that should be hidden
 		.filter((doc) => !doc.entry.data.sidebar.hidden)
+		// Compute the path of each entry from the root of the collection ahead of time.
+		.map(
+			(doc) =>
+				[
+					project.legacyCollections
+						? doc.id
+						: // For collections with a loader, use a localized filePath relative to the collection
+							localizedId(doc.entry.filePath.replace(`${collectionPathFromRoot}/`, ''), locale),
+					doc,
+				] as const
+		)
 		// Sort by depth, to build the tree depth first.
-		.sort((a, b) => b.id.split('/').length - a.id.split('/').length)
+		.sort(([a], [b]) => b.split('/').length - a.split('/').length)
 		// Build the tree
-		.forEach((doc) => {
-			const parts = getBreadcrumbs(doc.id, baseDir);
+		.forEach(([filePathFromContentDir, doc]) => {
+			const parts = getBreadcrumbs(filePathFromContentDir, baseDir);
 			let currentNode = treeRoot;
 
 			parts.forEach((part, index) => {
@@ -374,7 +388,7 @@ function getIntermediateSidebarFromConfig(
 	if (sidebarConfig) {
 		return sidebarConfig.map((group) => configItemToEntry(group, pathname, locale, routes));
 	} else {
-		const tree = treeify(routes, locale || '');
+		const tree = treeify(routes, locale, locale || '');
 		return sidebarFromDir(tree, pathname, locale, false);
 	}
 }

package/utils/plugins.ts

@@ -2,7 +2,6 @@ import type { AstroIntegration, HookParameters } from 'astro';
 import { z } from 'astro/zod';
 import { StarlightConfigSchema, type StarlightUserConfig } from '../utils/user-config';
 import { parseWithFriendlyErrors } from '../utils/error-map';
-import { AstroError } from 'astro/errors';
 import type { UserI18nSchema } from './translations';
 
 /**
@@ -83,14 +82,6 @@ export async function runPlugins(
 		});
 	}
 
-	if (context.config.output === 'static' && !starlightConfig.prerender) {
-		throw new AstroError(
-			'Starlight’s `prerender: false` option requires `output: "hybrid"` or `"server"` in your Astro config.',
-			'Either set `output` in your Astro config or set `prerender: true` in the Starlight options.\n\n' +
-				'Learn more about rendering modes in the Astro docs: https://docs.astro.build/en/basics/rendering-modes/'
-		);
-	}
-
 	return { integrations, starlightConfig, pluginTranslations };
 }
 

package/utils/route-data.ts

@@ -1,12 +1,10 @@
 import type { MarkdownHeading } from 'astro';
-import project from 'virtual:starlight/project-context';
 import config from 'virtual:starlight/user-config';
 import { generateToC, type TocItem } from './generateToC';
 import { getNewestCommitDate } from 'virtual:starlight/git-info';
 import { getPrevNextLinks, getSidebar, type SidebarEntry } from './navigation';
 import { ensureTrailingSlash } from './path';
 import type { Route } from './routing';
-import { localizedId } from './slugs';
 import { formatPath } from './format-path';
 import { useTranslations } from './translations';
 import { DeprecatedLabelsPropProxy } from './i18n';
@@ -85,7 +83,7 @@ function getLastUpdated({ entry }: PageProps): Date | undefined {
 		try {
 			return frontmatterLastUpdated instanceof Date
 				? frontmatterLastUpdated
-				: getNewestCommitDate(entry.id);
+				: getNewestCommitDate(entry.filePath);
 		} catch {
 			// If the git command fails, ignore the error.
 			return undefined;
@@ -95,7 +93,7 @@ function getLastUpdated({ entry }: PageProps): Date | undefined {
 	return undefined;
 }
 
-function getEditUrl({ entry, id, isFallback }: PageProps): URL | undefined {
+function getEditUrl({ entry }: PageProps): URL | undefined {
 	const { editUrl } = entry.data;
 	// If frontmatter value is false, editing is disabled for this page.
 	if (editUrl === false) return;
@@ -105,10 +103,8 @@ function getEditUrl({ entry, id, isFallback }: PageProps): URL | undefined {
 		// If a URL was provided in frontmatter, use that.
 		url = editUrl;
 	} else if (config.editLink.baseUrl) {
-		const srcPath = project.srcDir.replace(project.root, '');
-		const filePath = isFallback ? localizedId(id, config.defaultLocale.locale) : id;
 		// If a base URL was added in Starlight config, synthesize the edit URL from it.
-		url = ensureTrailingSlash(config.editLink.baseUrl) + srcPath + 'content/docs/' + filePath;
+		url = ensureTrailingSlash(config.editLink.baseUrl) + entry.filePath;
 	}
 	return url ? new URL(url) : undefined;
 }

package/utils/routing.ts

@@ -1,6 +1,8 @@
 import type { GetStaticPathsItem } from 'astro';
 import { type CollectionEntry, getCollection } from 'astro:content';
 import config from 'virtual:starlight/user-config';
+import project from 'virtual:starlight/project-context';
+import { getCollectionPathFromRoot } from './collection';
 import {
 	type LocaleData,
 	localizedId,
@@ -15,7 +17,22 @@ import { BuiltInDefaultLocale } from './i18n';
 // We do this here so all pages trigger it and at the top level so it runs just once.
 validateLogoImports();
 
-export type StarlightDocsEntry = Omit<CollectionEntry<'docs'>, 'slug'> & {
+// The type returned from `CollectionEntry` is different for legacy collections and collections
+// using a loader. This type is a common subset of both types.
+export type StarlightDocsCollectionEntry = Omit<
+	CollectionEntry<'docs'>,
+	'id' | 'filePath' | 'render' | 'slug'
+> & {
+	// Update the `id` property to be a string like in the loader type.
+	id: string;
+	// Add the `filePath` property which is only present in the loader type.
+	filePath?: string;
+	// Add the `slug` property which is only present in the legacy type.
+	slug?: string;
+};
+
+export type StarlightDocsEntry = StarlightDocsCollectionEntry & {
+	filePath: string;
 	slug: string;
 };
 
@@ -24,9 +41,9 @@ export interface Route extends LocaleData {
 	entry: StarlightDocsEntry;
 	/** Locale metadata for the page content. Can be different from top-level locale values when a page is using fallback content. */
 	entryMeta: LocaleData;
-	/** The slug, a.k.a. permalink, for this page. */
+	/** @deprecated Migrate to the new Content Layer API and use `id` instead. */
 	slug: string;
-	/** The unique ID for this page. */
+	/** The slug or unique ID if using the `legacy.collections` flag. */
 	id: string;
 	/** True if this page is untranslated in the current language and using fallback content from the default locale. */
 	isFallback?: true;
@@ -45,16 +62,27 @@ interface Path extends GetStaticPathsItem {
  */
 const normalizeIndexSlug = (slug: string) => (slug === 'index' ? '' : slug);
 
+/** Normalize the different collection entry we can get from a legacy collection or a loader. */
+export function normalizeCollectionEntry(entry: StarlightDocsCollectionEntry): StarlightDocsEntry {
+	const slug = normalizeIndexSlug(entry.slug ?? entry.id);
+	return {
+		...entry,
+		// In a collection with a loader, the `id` is a slug and should be normalized.
+		id: entry.slug ? entry.id : slug,
+		// In a legacy collection, the `filePath` property doesn't exist.
+		filePath: entry.filePath ?? `${getCollectionPathFromRoot('docs', project)}/${entry.id}`,
+		// In a collection with a loader, the `slug` property is replaced by the `id`.
+		slug: normalizeIndexSlug(entry.slug ?? entry.id),
+	};
+}
+
 /** All entries in the docs content collection. */
 const docs: StarlightDocsEntry[] = (
 	(await getCollection('docs', ({ data }) => {
 		// In production, filter out drafts.
 		return import.meta.env.MODE !== 'production' || data.draft === false;
 	})) ?? []
-).map(({ slug, ...entry }) => ({
-	...entry,
-	slug: normalizeIndexSlug(slug),
-}));
+).map(normalizeCollectionEntry);
 
 function getRoutes(): Route[] {
 	const routes: Route[] = docs.map((entry) => ({
@@ -79,7 +107,7 @@ function getRoutes(): Route[] {
 			const localeDocs = getLocaleDocs(locale);
 			for (const fallback of defaultLocaleDocs) {
 				const slug = localizedSlug(fallback.slug, locale);
-				const id = localizedId(fallback.id, locale);
+				const id = project.legacyCollections ? localizedId(fallback.id, locale) : slug;
 				const doesNotNeedFallback = localeDocs.some((doc) => doc.slug === slug);
 				if (doesNotNeedFallback) continue;
 				routes.push({

package/utils/slugs.ts

@@ -82,7 +82,8 @@ export function localizedSlug(slug: string, locale: string | undefined): string
 }
 
 /**
- * Convert a collection entry ID to a different locale.
+ * Convert a legacy collection entry ID or filePath relative to the collection root to a different
+ * locale.
  * For example, passing an ID of `en/home.md` and a locale of `fr` results in `fr/home.md`.
  * An undefined locale is treated as the root locale, resulting in `home.md`.
  * @param id A collection entry ID

package/utils/starlight-page.ts

@@ -1,6 +1,8 @@
 import { z } from 'astro/zod';
 import { type ContentConfig, type SchemaContext } from 'astro:content';
+import project from 'virtual:starlight/project-context';
 import config from 'virtual:starlight/user-config';
+import { getCollectionPathFromRoot } from './collection';
 import { parseWithFriendlyErrors, parseAsyncWithFriendlyErrors } from './error-map';
 import { stripLeadingAndTrailingSlashes } from './path';
 import {
@@ -97,8 +99,8 @@ export type StarlightPageProps = Prettify<
  */
 type StarlightPageDocsEntry = Omit<StarlightDocsEntry, 'id' | 'render'> & {
 	/**
-	 * The unique ID for this Starlight page which cannot be inferred from codegen like content
-	 * collection entries.
+	 * The unique ID if using the `legacy.collections` for this Starlight page which cannot be
+	 * inferred from codegen like content collection entries or the slug.
 	 */
 	id: string;
 };
@@ -113,7 +115,7 @@ export async function generateStarlightPageRouteData({
 	const { isFallback, frontmatter, ...routeProps } = props;
 	const slug = urlToSlug(url);
 	const pageFrontmatter = await getStarlightPageFrontmatter(frontmatter);
-	const id = `${stripLeadingAndTrailingSlashes(slug)}.md`;
+	const id = project.legacyCollections ? `${stripLeadingAndTrailingSlashes(slug)}.md` : slug;
 	const localeData = slugToLocaleData(slug);
 	const sidebar = props.sidebar
 		? getSidebarFromConfig(validateSidebarProp(props.sidebar), url.pathname, localeData.locale)
@@ -124,6 +126,7 @@ export async function generateStarlightPageRouteData({
 		slug,
 		body: '',
 		collection: 'docs',
+		filePath: `${getCollectionPathFromRoot('docs', project)}/${stripLeadingAndTrailingSlashes(slug)}.md`,
 		data: {
 			...pageFrontmatter,
 			sidebar: {

package/virtual-internal.d.ts

@@ -6,6 +6,7 @@ declare module 'virtual:starlight/project-context' {
 		build: {
 			format: import('astro').AstroConfig['build']['format'];
 		};
+		legacyCollections: boolean;
 	};
 	export default ProjectContext;
 }