@astrojs/starlight 0.13.0 → 0.14.0

package/404.astro

@@ -26,7 +26,7 @@ const fallbackEntry: StarlightDocsEntry = {
 		head: [],
 		hero: { tagline: t('404.text'), actions: [] },
 		pagefind: false,
-		sidebar: { hidden: false },
+		sidebar: { hidden: false, attrs: {} },
 	},
 	render: async () => ({
 		Content: EmptyContent,

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @astrojs/starlight
 
+## 0.14.0
+
+### Minor Changes
+
+- [#1144](https://github.com/withastro/starlight/pull/1144) [`7c0b8cb`](https://github.com/withastro/starlight/commit/7c0b8cb334c501678f7ab87cce372cddfdde34ed) Thanks [@delucis](https://github.com/delucis)! - Adds a configuration option to disable site indexing with Pagefind and the default search UI
+
+- [#942](https://github.com/withastro/starlight/pull/942) [`efd7fdc`](https://github.com/withastro/starlight/commit/efd7fdcb55b39988f157c1a4b2c368c86a39520f) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds plugin API
+
+  See the [plugins reference](https://starlight.astro.build/reference/plugins/) to learn more about creating plugins for Starlight using this new API.
+
+- [#1135](https://github.com/withastro/starlight/pull/1135) [`e5a863a`](https://github.com/withastro/starlight/commit/e5a863a98b2e5335e122ca440dcb84e9426939b4) Thanks [@delucis](https://github.com/delucis)! - Exposes localized UI strings in route data
+
+  Component overrides can now access a `labels` object in their props which includes all the localized UI strings for the current page.
+
+- [#1162](https://github.com/withastro/starlight/pull/1162) [`00d101b`](https://github.com/withastro/starlight/commit/00d101b159bfa4bb307a66ccae53dd417d9564e0) Thanks [@delucis](https://github.com/delucis)! - Adds support for extending Starlight’s content collection schemas
+
+## 0.13.1
+
+### Patch Changes
+
+- [#1111](https://github.com/withastro/starlight/pull/1111) [`cb19d07`](https://github.com/withastro/starlight/commit/cb19d07d6192ffb732ac6fcf9df04d4f098bfc1f) Thanks [@at-the-vr](https://github.com/at-the-vr)! - Fix minor punctuation typo in Hindi UI string
+
+- [#1156](https://github.com/withastro/starlight/pull/1156) [`631c5ae`](https://github.com/withastro/starlight/commit/631c5aeccba60254ff649712f93ba30495775edf) Thanks [@votemike](https://github.com/votemike)! - Updates `@astrojs/sitemap` dependency to the latest version
+
+- [#1109](https://github.com/withastro/starlight/pull/1109) [`0c25c1f`](https://github.com/withastro/starlight/commit/0c25c1f33bbfe311724784530c30ada44eb5de19) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Internal: fix import issue with expressive-code
+
 ## 0.13.0
 
 ### Minor Changes

package/components/EditLink.astro

@@ -1,17 +1,15 @@
 ---
 import Icon from '../user-components/Icon.astro';
 import type { Props } from '../props';
-import { useTranslations } from '../utils/translations';
 
-const t = useTranslations(Astro.props.locale);
-const { editUrl } = Astro.props;
+const { editUrl, labels } = Astro.props;
 ---
 
 {
 	editUrl && (
 		<a href={editUrl} class="sl-flex">
 			<Icon name="pencil" size="1.2em" />
-			{t('page.editLink')}
+			{labels['page.editLink']}
 		</a>
 	)
 }

package/components/FallbackContentNotice.astro

@@ -1,14 +1,13 @@
 ---
 import Icon from '../user-components/Icon.astro';
 import type { Props } from '../props';
-import { useTranslations } from '../utils/translations';
 
-const t = useTranslations(Astro.props.locale);
+const { labels } = Astro.props;
 ---
 
 <p class="sl-flex">
 	<Icon name={'warning'} size="1.5em" color="var(--sl-color-orange-high)" /><span
-		>{t('i18n.untranslatedContent')}</span
+		>{labels['i18n.untranslatedContent']}</span
 	>
 </p>
 

package/components/Header.astro

@@ -1,4 +1,5 @@
 ---
+import config from 'virtual:starlight/user-config';
 import type { Props } from '../props';
 
 import {
@@ -8,6 +9,12 @@ import {
 	SocialIcons,
 	ThemeSelect,
 } from 'virtual:starlight/components';
+
+/**
+ * Render the `Search` component if Pagefind is enabled or the default search component has been overridden.
+ */
+const shouldRenderSearch =
+	config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
 ---
 
 <div class="header sl-flex">
@@ -15,7 +22,7 @@ import {
 		<SiteTitle {...Astro.props} />
 	</div>
 	<div class="sl-flex">
-		<Search {...Astro.props} />
+		{shouldRenderSearch && <Search {...Astro.props} />}
 	</div>
 	<div class="sl-hidden md:sl-flex right-group">
 		<div class="sl-flex social-icons">

package/components/LanguageSelect.astro

@@ -1,7 +1,6 @@
 ---
 import config from 'virtual:starlight/user-config';
 import { localizedUrl } from '../utils/localizedUrl';
-import { useTranslations } from '../utils/translations';
 import Select from './Select.astro';
 import type { Props } from '../props';
 
@@ -12,7 +11,7 @@ function localizedPathname(locale: string | undefined): string {
 	return localizedUrl(Astro.url, locale).pathname;
 }
 
-const t = useTranslations(Astro.props.locale);
+const { labels } = Astro.props;
 ---
 
 {
@@ -20,7 +19,7 @@ const t = useTranslations(Astro.props.locale);
 		<starlight-lang-select>
 			<Select
 				icon="translate"
-				label={t('languageSelect.accessibleLabel')}
+				label={labels['languageSelect.accessibleLabel']}
 				value={localizedPathname(Astro.props.locale)}
 				options={Object.entries(config.locales).map(([code, locale]) => ({
 					value: localizedPathname(code),

package/components/LastUpdated.astro

@@ -1,15 +1,13 @@
 ---
 import type { Props } from '../props';
-import { useTranslations } from '../utils/translations';
 
-const { lang, lastUpdated, locale } = Astro.props;
-const t = useTranslations(locale);
+const { labels, lang, lastUpdated } = Astro.props;
 ---
 
 {
 	lastUpdated && (
 		<p>
-			{t('page.lastUpdated')}{' '}
+			{labels['page.lastUpdated']}{' '}
 			<time datetime={lastUpdated.toISOString()}>
 				{lastUpdated.toLocaleDateString(lang, { dateStyle: 'medium' })}
 			</time>

package/components/MobileMenuToggle.astro

@@ -1,16 +1,14 @@
 ---
 import type { Props } from '../props';
-import { useTranslations } from '../utils/translations';
-
 import Icon from '../user-components/Icon.astro';
 
-const t = useTranslations(Astro.props.locale);
+const { labels } = Astro.props;
 ---
 
 <starlight-menu-button>
 	<button
 		aria-expanded="false"
-		aria-label={t('menuButton.accessibleLabel')}
+		aria-label={labels['menuButton.accessibleLabel']}
 		aria-controls="starlight__sidebar"
 		class="sl-flex md:sl-hidden"
 	>

package/components/MobileTableOfContents.astro

@@ -1,11 +1,9 @@
 ---
-import { useTranslations } from '../utils/translations';
 import Icon from '../user-components/Icon.astro';
 import TableOfContentsList from './TableOfContents/TableOfContentsList.astro';
 import type { Props } from '../props';
 
-const { locale, toc } = Astro.props;
-const t = useTranslations(locale);
+const { labels, toc } = Astro.props;
 ---
 
 {
@@ -15,7 +13,7 @@ const t = useTranslations(locale);
 				<details id="starlight__mobile-toc">
 					<summary id="starlight__on-this-page--mobile" class="sl-flex">
 						<div class="toggle sl-flex">
-							{t('tableOfContents.onThisPage')}
+							{labels['tableOfContents.onThisPage']}
 							<Icon name={'right-caret'} class="caret" size="1rem" />
 						</div>
 						<span class="display-current" />

package/components/PageFrame.astro

@@ -1,18 +1,15 @@
 ---
-import type { Props } from '../props';
-import { useTranslations } from '../utils/translations';
-
 import { MobileMenuToggle } from 'virtual:starlight/components';
+import type { Props } from '../props';
 
-const { hasSidebar, locale } = Astro.props;
-const t = useTranslations(locale);
+const { hasSidebar, labels } = Astro.props;
 ---
 
 <div class="page sl-flex">
 	<header class="header"><slot name="header" /></header>
 	{
 		hasSidebar && (
-			<nav class="sidebar" aria-label={t('sidebarNav.accessibleLabel')}>
+			<nav class="sidebar" aria-label={labels['sidebarNav.accessibleLabel']}>
 				<MobileMenuToggle {...Astro.props} />
 				<div id="starlight__sidebar" class="sidebar-pane">
 					<div class="sidebar-content sl-flex">

package/components/Pagination.astro

@@ -1,12 +1,10 @@
 ---
-import { useTranslations } from '../utils/translations';
 import Icon from '../user-components/Icon.astro';
 import type { Props } from '../props';
 
-const { dir, locale, pagination } = Astro.props;
+const { dir, labels, pagination } = Astro.props;
 const { prev, next } = pagination;
 const isRtl = dir === 'rtl';
-const t = useTranslations(locale);
 ---
 
 <div class="pagination-links" dir={dir}>
@@ -15,7 +13,7 @@ const t = useTranslations(locale);
 			<a href={prev.href} rel="prev">
 				<Icon name={isRtl ? 'right-arrow' : 'left-arrow'} size="1.5rem" />
 				<span>
-					{t('page.previousLink')}
+					{labels['page.previousLink']}
 					<br />
 					<span class="link-title">{prev.label}</span>
 				</span>
@@ -27,7 +25,7 @@ const t = useTranslations(locale);
 			<a href={next.href} rel="next">
 				<Icon name={isRtl ? 'left-arrow' : 'right-arrow'} size="1.5rem" />
 				<span>
-					{t('page.nextLink')}
+					{labels['page.nextLink']}
 					<br />
 					<span class="link-title">{next.label}</span>
 				</span>

package/components/Search.astro

@@ -1,14 +1,16 @@
 ---
 import '@pagefind/default-ui/css/ui.css';
-import { useTranslations } from '../utils/translations';
 import Icon from '../user-components/Icon.astro';
 import type { Props } from '../props';
 
-const t = useTranslations(Astro.props.locale);
+const { labels } = Astro.props;
+
 const pagefindTranslations = {
-	placeholder: t('search.label'),
+	placeholder: labels['search.label'],
 	...Object.fromEntries(
-		Object.entries(t.pick('pagefind.')).map(([key, value]) => [key.replace('pagefind.', ''), value])
+		Object.entries(labels)
+			.filter(([key]) => key.startsWith('pagefind.'))
+			.map(([key, value]) => [key.replace('pagefind.', ''), value])
 	),
 };
 ---
@@ -18,23 +20,27 @@ const pagefindTranslations = {
 		{
 			/* The span is `aria-hidden` because it is not shown on small screens. Instead, the icon label is used for accessibility purposes. */
 		}
-		<Icon name="magnifier" label={t('search.label')} />
-		<span class="sl-hidden md:sl-block" aria-hidden="true">{t('search.label')}</span>
-		<Icon name="forward-slash" class="sl-hidden md:sl-block" label={t('search.shortcutLabel')} />
+		<Icon name="magnifier" label={labels['search.label']} />
+		<span class="sl-hidden md:sl-block" aria-hidden="true">{labels['search.label']}</span>
+		<Icon
+			name="forward-slash"
+			class="sl-hidden md:sl-block"
+			label={labels['search.shortcutLabel']}
+		/>
 	</button>
 
-	<dialog style="padding:0" aria-label={t('search.label')}>
+	<dialog style="padding:0" aria-label={labels['search.label']}>
 		<div class="dialog-frame sl-flex">
 			{
 				/* TODO: Make the layout of this button flexible to accommodate different word lengths. Currently hard-coded for English: “Cancel” */
 			}
 			<button data-close-modal class="sl-flex md:sl-hidden">
-				{t('search.cancelLabel')}
+				{labels['search.cancelLabel']}
 			</button>
 			{
 				import.meta.env.DEV ? (
 					<div style="margin: auto; text-align: center; white-space: pre-line;" dir="ltr">
-						<p>{t('search.devWarning')}</p>
+						<p>{labels['search.devWarning']}</p>
 					</div>
 				) : (
 					<div class="search-container">

package/components/SidebarSublist.astro

@@ -7,17 +7,19 @@ interface Props {
 	sublist: SidebarEntry[];
 	nested?: boolean;
 }
+
+const { sublist, nested } = Astro.props;
 ---
 
-<ul class:list={{ 'top-level': !Astro.props.nested }}>
+<ul class:list={{ 'top-level': !nested }}>
 	{
-		Astro.props.sublist.map((entry) => (
+		sublist.map((entry) => (
 			<li>
 				{entry.type === 'link' ? (
 					<a
 						href={entry.href}
 						aria-current={entry.isCurrent && 'page'}
-						class:list={[{ large: !Astro.props.nested }, entry.attrs.class]}
+						class:list={[{ large: !nested }, entry.attrs.class]}
 						{...entry.attrs}
 					>
 						<span>{entry.label}</span>

package/components/SkipLink.astro

@@ -1,12 +1,11 @@
 ---
 import { PAGE_TITLE_ID } from '../constants';
-import { useTranslations } from '../utils/translations';
 import type { Props } from '../props';
 
-const t = useTranslations(Astro.props.locale);
+const { labels } = Astro.props;
 ---
 
-<a href={`#${PAGE_TITLE_ID}`}>{t('skipLink.label')}</a>
+<a href={`#${PAGE_TITLE_ID}`}>{labels['skipLink.label']}</a>
 
 <style>
 	a {

package/components/TableOfContents.astro

@@ -1,17 +1,15 @@
 ---
-import { useTranslations } from '../utils/translations';
 import TableOfContentsList from './TableOfContents/TableOfContentsList.astro';
 import type { Props } from '../props';
 
-const { locale, toc } = Astro.props;
-const t = useTranslations(locale);
+const { labels, toc } = Astro.props;
 ---
 
 {
 	toc && (
 		<starlight-toc data-min-h={toc.minHeadingLevel} data-max-h={toc.maxHeadingLevel}>
 			<nav aria-labelledby="starlight__on-this-page">
-				<h2 id="starlight__on-this-page">{t('tableOfContents.onThisPage')}</h2>
+				<h2 id="starlight__on-this-page">{labels['tableOfContents.onThisPage']}</h2>
 				<TableOfContentsList toc={toc.items} />
 			</nav>
 		</starlight-toc>

package/components/ThemeSelect.astro

@@ -1,21 +1,20 @@
 ---
-import { useTranslations } from '../utils/translations';
 import Select from './Select.astro';
 import type { Props } from '../props';
 
-const t = useTranslations(Astro.props.locale);
+const { labels } = Astro.props;
 ---
 
 <starlight-theme-select>
 	{/* TODO: Can we give this select a width that works well for each language’s strings? */}
 	<Select
 		icon="laptop"
-		label={t('themeSelect.accessibleLabel')}
+		label={labels['themeSelect.accessibleLabel']}
 		value="auto"
 		options={[
-			{ label: t('themeSelect.dark'), selected: false, value: 'dark' },
-			{ label: t('themeSelect.light'), selected: false, value: 'light' },
-			{ label: t('themeSelect.auto'), selected: true, value: 'auto' },
+			{ label: labels['themeSelect.dark'], selected: false, value: 'dark' },
+			{ label: labels['themeSelect.light'], selected: false, value: 'light' },
+			{ label: labels['themeSelect.auto'], selected: true, value: 'auto' },
 		]}
 		width="6.25em"
 	/>

package/index.ts

@@ -4,31 +4,41 @@ import { spawn } from 'node:child_process';
 import { dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { starlightAsides } from './integrations/asides';
-import { starlightExpressiveCode } from './integrations/expressive-code';
+import { starlightExpressiveCode } from './integrations/expressive-code/index';
 import { starlightSitemap } from './integrations/sitemap';
 import { vitePluginStarlightUserConfig } from './integrations/virtual-user-config';
-import { errorMap } from './utils/error-map';
-import { StarlightConfigSchema, type StarlightUserConfig } from './utils/user-config';
 import { rehypeRtlCodeSupport } from './integrations/code-rtl-support';
 import { createTranslationSystemFromFs } from './utils/translations-fs';
+import { runPlugins, type StarlightUserConfigWithPlugins } from './utils/plugins';
+import type { StarlightConfig } from './types';
 
-export default function StarlightIntegration(opts: StarlightUserConfig): AstroIntegration {
-	const parsedConfig = StarlightConfigSchema.safeParse(opts, { errorMap });
-
-	if (!parsedConfig.success) {
-		throw new Error(
-			'Invalid config passed to starlight integration\n' +
-				parsedConfig.error.issues.map((i) => i.message).join('\n')
-		);
-	}
-
-	const userConfig = parsedConfig.data;
-
-	const Starlight: AstroIntegration = {
+export default function StarlightIntegration({
+	plugins,
+	...opts
+}: StarlightUserConfigWithPlugins): AstroIntegration {
+	let userConfig: StarlightConfig;
+	return {
 		name: '@astrojs/starlight',
 		hooks: {
-			'astro:config:setup': ({ config, injectRoute, updateConfig }) => {
-				const useTranslations = createTranslationSystemFromFs(userConfig, config);
+			'astro:config:setup': async ({
+				command,
+				config,
+				injectRoute,
+				isRestart,
+				logger,
+				updateConfig,
+			}) => {
+				// Run plugins to get the final configuration and any extra Astro integrations to load.
+				const { integrations, starlightConfig } = await runPlugins(opts, plugins, {
+					command,
+					config,
+					isRestart,
+					logger,
+				});
+				userConfig = starlightConfig;
+
+				const useTranslations = createTranslationSystemFromFs(starlightConfig, config);
+
 				injectRoute({
 					pattern: '404',
 					entryPoint: '@astrojs/starlight/404.astro',
@@ -37,34 +47,28 @@ export default function StarlightIntegration(opts: StarlightUserConfig): AstroIn
 					pattern: '[...slug]',
 					entryPoint: '@astrojs/starlight/index.astro',
 				});
-				const integrations: AstroIntegration[] = [];
-				if (!config.integrations.find(({ name }) => name === 'astro-expressive-code')) {
+				// Add built-in integrations only if they are not already added by the user through the
+				// config or by a plugin.
+				const allIntegrations = [...config.integrations, ...integrations];
+				if (!allIntegrations.find(({ name }) => name === 'astro-expressive-code')) {
 					integrations.push(
-						...starlightExpressiveCode({
-							starlightConfig: userConfig,
-							astroConfig: config,
-							useTranslations,
-						})
+						...starlightExpressiveCode({ starlightConfig, astroConfig: config, useTranslations })
 					);
 				}
-				if (!config.integrations.find(({ name }) => name === '@astrojs/sitemap')) {
-					integrations.push(starlightSitemap(userConfig));
+				if (!allIntegrations.find(({ name }) => name === '@astrojs/sitemap')) {
+					integrations.push(starlightSitemap(starlightConfig));
 				}
-				if (!config.integrations.find(({ name }) => name === '@astrojs/mdx')) {
+				if (!allIntegrations.find(({ name }) => name === '@astrojs/mdx')) {
 					integrations.push(mdx());
 				}
 				const newConfig: AstroUserConfig = {
 					integrations,
 					vite: {
-						plugins: [vitePluginStarlightUserConfig(userConfig, config)],
+						plugins: [vitePluginStarlightUserConfig(starlightConfig, config)],
 					},
 					markdown: {
 						remarkPlugins: [
-							...starlightAsides({
-								starlightConfig: userConfig,
-								astroConfig: config,
-								useTranslations,
-							}),
+							...starlightAsides({ starlightConfig, astroConfig: config, useTranslations }),
 						],
 						rehypePlugins: [rehypeRtlCodeSupport()],
 						shikiConfig:
@@ -77,6 +81,7 @@ export default function StarlightIntegration(opts: StarlightUserConfig): AstroIn
 			},
 
 			'astro:build:done': ({ dir }) => {
+				if (!userConfig.pagefind) return;
 				const targetDir = fileURLToPath(dir);
 				const cwd = dirname(fileURLToPath(import.meta.url));
 				const relativeDir = relative(cwd, targetDir);
@@ -90,6 +95,4 @@ export default function StarlightIntegration(opts: StarlightUserConfig): AstroIn
 			},
 		},
 	};
-
-	return Starlight;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -170,7 +170,7 @@
   },
   "dependencies": {
     "@astrojs/mdx": "^1.1.0",
-    "@astrojs/sitemap": "^3.0.0",
+    "@astrojs/sitemap": "^3.0.3",
     "@pagefind/default-ui": "^1.0.3",
     "@types/mdast": "^3.0.11",
     "astro-expressive-code": "^0.29.0",

package/schema.ts

@@ -8,100 +8,153 @@ import { HeroSchema } from './schemas/hero';
 import { SidebarLinkItemHTMLAttributesSchema } from './schemas/sidebar';
 export { i18nSchema } from './schemas/i18n';
 
-export function docsSchema() {
-	return (context: SchemaContext) =>
-		z.object({
-			/** The title of the current page. Required. */
-			title: z.string(),
-
-			/**
-			 * A short description of the current page’s content. Optional, but recommended.
-			 * A good description is 150–160 characters long and outlines the key content
-			 * of the page in a clear and engaging way.
-			 */
-			description: z.string().optional(),
-
-			/**
-			 * Custom URL where a reader can edit this page.
-			 * Overrides the `editLink.baseUrl` global config if set.
-			 *
-			 * Can also be set to `false` to disable showing an edit link on this page.
-			 */
-			editUrl: z.union([z.string().url(), z.boolean()]).optional().default(true),
-
-			/** Set custom `<head>` tags just for this page. */
-			head: HeadConfigSchema(),
-
-			/** Override global table of contents configuration for this page. */
-			tableOfContents: TableOfContentsSchema().optional(),
-
-			/**
-			 * Set the layout style for this page.
-			 * Can be `'doc'` (the default) or `'splash'` for a wider layout without any sidebars.
-			 */
-			template: z.enum(['doc', 'splash']).default('doc'),
-
-			/** Display a hero section on this page. */
-			hero: HeroSchema(context).optional(),
-
-			/**
-			 * The last update date of the current page.
-			 * Overrides the `lastUpdated` global config or the date generated from the Git history.
-			 */
-			lastUpdated: z.union([z.date(), z.boolean()]).optional(),
-
-			/**
-			 * The previous navigation link configuration.
-			 * Overrides the `pagination` global config or the link text and/or URL.
-			 */
-			prev: PrevNextLinkConfigSchema(),
-			/**
-			 * The next navigation link configuration.
-			 * Overrides the `pagination` global config or the link text and/or URL.
-			 */
-			next: PrevNextLinkConfigSchema(),
-
-			sidebar: z
-				.object({
-					/**
-					 * The order of this page in the navigation.
-					 * Pages are sorted by this value in ascending order. Then by slug.
-					 * If not provided, pages will be sorted alphabetically by slug.
-					 * If two pages have the same order value, they will be sorted alphabetically by slug.
-					 */
-					order: z.number().optional(),
-
-					/**
-					 * The label for this page in the navigation.
-					 * Defaults to the page `title` if not set.
-					 */
-					label: z.string().optional(),
-
-					/**
-					 * Prevents this page from being included in autogenerated sidebar groups.
-					 */
-					hidden: z.boolean().default(false),
-					/**
-					 * Adds a badge to the sidebar link.
-					 * Can be a string or an object with a variant and text.
-					 * Variants include 'note', 'tip', 'caution', 'danger', 'success', and 'default'.
-					 * Passing only a string defaults to the 'default' variant which uses the site accent color.
-					 */
-					badge: BadgeConfigSchema(),
-					/** HTML attributes to add to the sidebar link. */
-					attrs: SidebarLinkItemHTMLAttributesSchema(),
-				})
-				.default({}),
-
-			/** Display an announcement banner at the top of this page. */
-			banner: z
-				.object({
-					/** The content of the banner. Supports HTML syntax. */
-					content: z.string(),
-				})
-				.optional(),
-
-			/** Pagefind indexing for this page - set to false to disable. */
-			pagefind: z.boolean().default(true),
-		});
+/** Default content collection schema for Starlight’s `docs` collection. */
+const StarlightFrontmatterSchema = (context: SchemaContext) =>
+	z.object({
+		/** The title of the current page. Required. */
+		title: z.string(),
+
+		/**
+		 * A short description of the current page’s content. Optional, but recommended.
+		 * A good description is 150–160 characters long and outlines the key content
+		 * of the page in a clear and engaging way.
+		 */
+		description: z.string().optional(),
+
+		/**
+		 * Custom URL where a reader can edit this page.
+		 * Overrides the `editLink.baseUrl` global config if set.
+		 *
+		 * Can also be set to `false` to disable showing an edit link on this page.
+		 */
+		editUrl: z.union([z.string().url(), z.boolean()]).optional().default(true),
+
+		/** Set custom `<head>` tags just for this page. */
+		head: HeadConfigSchema(),
+
+		/** Override global table of contents configuration for this page. */
+		tableOfContents: TableOfContentsSchema().optional(),
+
+		/**
+		 * Set the layout style for this page.
+		 * Can be `'doc'` (the default) or `'splash'` for a wider layout without any sidebars.
+		 */
+		template: z.enum(['doc', 'splash']).default('doc'),
+
+		/** Display a hero section on this page. */
+		hero: HeroSchema(context).optional(),
+
+		/**
+		 * The last update date of the current page.
+		 * Overrides the `lastUpdated` global config or the date generated from the Git history.
+		 */
+		lastUpdated: z.union([z.date(), z.boolean()]).optional(),
+
+		/**
+		 * The previous navigation link configuration.
+		 * Overrides the `pagination` global config or the link text and/or URL.
+		 */
+		prev: PrevNextLinkConfigSchema(),
+		/**
+		 * The next navigation link configuration.
+		 * Overrides the `pagination` global config or the link text and/or URL.
+		 */
+		next: PrevNextLinkConfigSchema(),
+
+		sidebar: z
+			.object({
+				/**
+				 * The order of this page in the navigation.
+				 * Pages are sorted by this value in ascending order. Then by slug.
+				 * If not provided, pages will be sorted alphabetically by slug.
+				 * If two pages have the same order value, they will be sorted alphabetically by slug.
+				 */
+				order: z.number().optional(),
+
+				/**
+				 * The label for this page in the navigation.
+				 * Defaults to the page `title` if not set.
+				 */
+				label: z.string().optional(),
+
+				/**
+				 * Prevents this page from being included in autogenerated sidebar groups.
+				 */
+				hidden: z.boolean().default(false),
+				/**
+				 * Adds a badge to the sidebar link.
+				 * Can be a string or an object with a variant and text.
+				 * Variants include 'note', 'tip', 'caution', 'danger', 'success', and 'default'.
+				 * Passing only a string defaults to the 'default' variant which uses the site accent color.
+				 */
+				badge: BadgeConfigSchema(),
+				/** HTML attributes to add to the sidebar link. */
+				attrs: SidebarLinkItemHTMLAttributesSchema(),
+			})
+			.default({}),
+
+		/** Display an announcement banner at the top of this page. */
+		banner: z
+			.object({
+				/** The content of the banner. Supports HTML syntax. */
+				content: z.string(),
+			})
+			.optional(),
+
+		/** Pagefind indexing for this page - set to false to disable. */
+		pagefind: z.boolean().default(true),
+	});
+/** Type of Starlight’s default frontmatter schema. */
+type DefaultSchema = ReturnType<typeof StarlightFrontmatterSchema>;
+
+/** Plain object, union, and intersection Zod types. */
+type BaseSchemaWithoutEffects =
+	| z.AnyZodObject
+	| z.ZodUnion<[BaseSchemaWithoutEffects, ...BaseSchemaWithoutEffects[]]>
+	| z.ZodDiscriminatedUnion<string, z.AnyZodObject[]>
+	| z.ZodIntersection<BaseSchemaWithoutEffects, BaseSchemaWithoutEffects>;
+/** Base subset of Zod types that we support passing to the `extend` option. */
+type BaseSchema = BaseSchemaWithoutEffects | z.ZodEffects<BaseSchemaWithoutEffects>;
+
+/** Type that extends Starlight’s default schema with an optional, user-defined schema. */
+type ExtendedSchema<T extends BaseSchema> = T extends BaseSchema
+	? z.ZodIntersection<DefaultSchema, T>
+	: DefaultSchema;
+
+interface DocsSchemaOpts<T extends BaseSchema> {
+	/**
+	 * Extend Starlight’s schema with additional fields.
+	 *
+	 * @example
+	 * // Extend the built-in schema with a Zod schema.
+	 * docsSchema({
+	 * 	extend: z.object({
+	 * 		// Add a new field to the schema.
+	 * 		category: z.enum(['tutorial', 'guide', 'reference']).optional(),
+	 * 	}),
+	 * })
+	 *
+	 * // Use the Astro image helper.
+	 * docsSchema({
+	 * 	extend: ({ image }) => {
+	 * 		return z.object({
+	 * 			cover: image(),
+	 * 		});
+	 * 	},
+	 * })
+	 */
+	extend?: T | ((context: SchemaContext) => T);
+}
+
+/** Content collection schema for Starlight’s `docs` collection. */
+export function docsSchema<T extends BaseSchema>({ extend }: DocsSchemaOpts<T> = {}) {
+	return (context: SchemaContext): ExtendedSchema<T> => {
+		const UserSchema = typeof extend === 'function' ? extend(context) : extend;
+
+		return (
+			UserSchema
+				? StarlightFrontmatterSchema(context).and(UserSchema)
+				: StarlightFrontmatterSchema(context)
+		) as ExtendedSchema<T>;
+	};
 }

package/schemas/i18n.ts

@@ -1,7 +1,31 @@
 import { z } from 'astro/zod';
 
-export function i18nSchema() {
-	return starlightI18nSchema().merge(pagefindI18nSchema()).merge(expressiveCodeI18nSchema());
+interface i18nSchemaOpts<T extends z.AnyZodObject = z.ZodObject<{}>> {
+	/**
+	 * Extend Starlight’s i18n schema with additional fields.
+	 *
+	 * @example
+	 * // Add two optional fields to the default schema.
+	 * i18nSchema({
+	 * 	extend: z
+	 * 		.object({
+	 * 			'customUi.heading': z.string(),
+	 * 			'customUi.text': z.string(),
+	 * 		})
+	 * 		.partial(),
+	 * })
+	 */
+	extend?: T;
+}
+
+/** Content collection schema for Starlight’s optional `i18n` collection. */
+export function i18nSchema<T extends z.AnyZodObject = z.ZodObject<{}>>({
+	extend = z.object({}) as T,
+}: i18nSchemaOpts<T> = {}) {
+	return starlightI18nSchema()
+		.merge(pagefindI18nSchema())
+		.merge(expressiveCodeI18nSchema())
+		.merge(extend);
 }
 export type i18nSchemaOutput = z.output<ReturnType<typeof i18nSchema>>;
 

package/translations/hi.json

@@ -13,7 +13,7 @@
   "sidebarNav.accessibleLabel": "मुख्य",
   "tableOfContents.onThisPage": "इस पृष्ठ पर",
   "tableOfContents.overview": "अवलोकन",
-  "i18n.untranslatedContent": "यह कंटेंट अभी तक आपकी भाषा में उपलब्ध नहीं है.",
+  "i18n.untranslatedContent": "यह कंटेंट अभी तक आपकी भाषा में उपलब्ध नहीं है।",
   "page.editLink": "पृष्ठ संपादित करें",
   "page.lastUpdated": "आखिरी अद्यतन:",
   "page.previousLink": "पिछला",

package/types.ts

@@ -1 +1,2 @@
 export type { StarlightConfig } from './utils/user-config';
+export type { StarlightPlugin } from './utils/plugins';

package/utils/createTranslationSystem.ts

@@ -19,10 +19,16 @@ export function createTranslationSystem(
 
 	/**
 	 * Generate a utility function that returns UI strings for the given `locale`.
+	 *
+	 * Also includes an `all()` method for getting the entire dictionary.
+	 *
 	 * @param {string | undefined} [locale]
 	 * @example
 	 * const t = useTranslations('en');
-	 * const label = t('search.label'); // => 'Search'
+	 * const label = t('search.label');
+	 * // => 'Search'
+	 * const dictionary = t.all();
+	 * // => { 'skipLink.label': 'Skip to content', 'search.label': 'Search', ... }
 	 */
 	return function useTranslations(locale: string | undefined) {
 		const lang = localeToLang(locale, config.locales, config.defaultLocale);
@@ -32,8 +38,7 @@ export function createTranslationSystem(
 			userTranslations[lang]
 		);
 		const t = <K extends keyof typeof dictionary>(key: K) => dictionary[key];
-		t.pick = (startOfKey: string) =>
-			Object.fromEntries(Object.entries(dictionary).filter(([k]) => k.startsWith(startOfKey)));
+		t.all = () => dictionary;
 		return t;
 	};
 }

package/utils/plugins.ts

@@ -0,0 +1,226 @@
+import type { AstroIntegration } from 'astro';
+import { z } from 'astro/zod';
+import { StarlightConfigSchema, type StarlightUserConfig } from '../utils/user-config';
+import { errorMap } from '../utils/error-map';
+
+/**
+ * Runs Starlight plugins in the order that they are configured after validating the user-provided
+ * configuration and returns the final validated user config that may have been updated by the
+ * plugins and a list of any integrations added by the plugins.
+ */
+export async function runPlugins(
+	starlightUserConfig: StarlightUserConfig,
+	pluginsUserConfig: StarlightPluginsUserConfig,
+	context: StarlightPluginContext
+) {
+	// Validate the user-provided configuration.
+	let userConfig = starlightUserConfig;
+	let starlightConfig = StarlightConfigSchema.safeParse(userConfig, { errorMap });
+
+	if (!starlightConfig.success) {
+		throwValidationError(starlightConfig.error, 'Invalid config passed to starlight integration');
+	}
+
+	// Validate the user-provided plugins configuration.
+	const pluginsConfig = starlightPluginsConfigSchema.safeParse(pluginsUserConfig, {
+		errorMap,
+	});
+
+	if (!pluginsConfig.success) {
+		throwValidationError(
+			pluginsConfig.error,
+			'Invalid plugins config passed to starlight integration'
+		);
+	}
+
+	// A list of Astro integrations added by the various plugins.
+	const integrations: AstroIntegration[] = [];
+
+	for (const {
+		name,
+		hooks: { setup },
+	} of pluginsConfig.data) {
+		await setup({
+			config: pluginsUserConfig ? { ...userConfig, plugins: pluginsUserConfig } : userConfig,
+			updateConfig(newConfig) {
+				// Ensure that plugins do not update the `plugins` config key.
+				if ('plugins' in newConfig) {
+					throw new Error(
+						`The '${name}' plugin tried to update the 'plugins' config key which is not supported.`
+					);
+				}
+
+				// If the plugin is updating the user config, re-validate it.
+				const mergedUserConfig = { ...userConfig, ...newConfig };
+				const mergedConfig = StarlightConfigSchema.safeParse(mergedUserConfig, { errorMap });
+
+				if (!mergedConfig.success) {
+					throwValidationError(
+						mergedConfig.error,
+						`Invalid config update provided by the '${name}' plugin`
+					);
+				}
+
+				// If the updated config is valid, keep track of both the user config and parsed config.
+				userConfig = mergedUserConfig;
+				starlightConfig = mergedConfig;
+			},
+			addIntegration(integration) {
+				// Collect any Astro integrations added by the plugin.
+				integrations.push(integration);
+			},
+			astroConfig: {
+				...context.config,
+				integrations: [...context.config.integrations, ...integrations],
+			},
+			command: context.command,
+			isRestart: context.isRestart,
+			logger: context.logger.fork(name),
+		});
+	}
+
+	return { integrations, starlightConfig: starlightConfig.data };
+}
+
+function throwValidationError(error: z.ZodError, message: string): never {
+	throw new Error(`${message}\n${error.issues.map((i) => i.message).join('\n')}`);
+}
+
+// https://github.com/withastro/astro/blob/910eb00fe0b70ca80bd09520ae100e8c78b675b5/packages/astro/src/core/config/schema.ts#L113
+const astroIntegrationSchema = z.object({
+	name: z.string(),
+	hooks: z.object({}).passthrough().default({}),
+}) as z.Schema<AstroIntegration>;
+
+const baseStarlightPluginSchema = z.object({
+	/** Name of the Starlight plugin. */
+	name: z.string(),
+});
+
+/**
+ * A plugin `config` and `updateConfig` argument are purposely not validated using the Starlight
+ * user config schema but properly typed for user convenience because we do not want to run any of
+ * the Zod `transform`s used in the user config schema when running plugins.
+ */
+const starlightPluginSchema = baseStarlightPluginSchema.extend({
+	/** The different hooks available to the plugin. */
+	hooks: z.object({
+		/**
+		 * Plugin setup function called with an object containing various values that can be used by
+		 * the plugin to interact with Starlight.
+		 */
+		setup: z.function(
+			z.tuple([
+				z.object({
+					/**
+					 * A read-only copy of the user-supplied Starlight configuration.
+					 *
+					 * Note that this configuration may have been updated by other plugins configured
+					 * before this one.
+					 */
+					config: z.any() as z.Schema<
+						// The configuration passed to plugins should contains the list of plugins.
+						StarlightUserConfig & { plugins?: z.input<typeof baseStarlightPluginSchema>[] }
+					>,
+					/**
+					 * A callback function to update the user-supplied Starlight configuration.
+					 *
+					 * You only need to provide the configuration values that you want to update but no deep
+					 * merge is performed.
+					 *
+					 * @example
+					 * {
+					 * 	name: 'My Starlight Plugin',
+					 *	hooks: {
+					 * 		setup({ updateConfig }) {
+					 * 			updateConfig({
+					 * 				description: 'Custom description',
+					 * 			});
+					 * 		}
+					 *	}
+					 * }
+					 */
+					updateConfig: z.function(
+						z.tuple([z.record(z.any()) as z.Schema<Partial<StarlightUserConfig>>]),
+						z.void()
+					),
+					/**
+					 * A callback function to add an Astro integration required by this plugin.
+					 *
+					 * @see https://docs.astro.build/en/reference/integrations-reference/
+					 *
+					 * @example
+					 * {
+					 * 	name: 'My Starlight Plugin',
+					 * 	hooks: {
+					 * 		setup({ addIntegration }) {
+					 * 			addIntegration({
+					 * 				name: 'My Plugin Astro Integration',
+					 * 				hooks: {
+					 * 					'astro:config:setup': () => {
+					 * 						// …
+					 * 					},
+					 * 				},
+					 * 			});
+					 * 		}
+					 * 	}
+					 * }
+					 */
+					addIntegration: z.function(z.tuple([astroIntegrationSchema]), z.void()),
+					/**
+					 * A read-only copy of the user-supplied Astro configuration.
+					 *
+					 * Note that this configuration is resolved before any other integrations have run.
+					 *
+					 * @see https://docs.astro.build/en/reference/integrations-reference/#config-option
+					 */
+					astroConfig: z.any() as z.Schema<StarlightPluginContext['config']>,
+					/**
+					 * The command used to run Starlight.
+					 *
+					 * @see https://docs.astro.build/en/reference/integrations-reference/#command-option
+					 */
+					command: z.any() as z.Schema<StarlightPluginContext['command']>,
+					/**
+					 * `false` when the dev server starts, `true` when a reload is triggered.
+					 *
+					 * @see https://docs.astro.build/en/reference/integrations-reference/#isrestart-option
+					 */
+					isRestart: z.any() as z.Schema<StarlightPluginContext['isRestart']>,
+					/**
+					 * An instance of the Astro integration logger with all logged messages prefixed with the
+					 * plugin name.
+					 *
+					 * @see https://docs.astro.build/en/reference/integrations-reference/#astrointegrationlogger
+					 */
+					logger: z.any() as z.Schema<StarlightPluginContext['logger']>,
+				}),
+			]),
+			z.union([z.void(), z.promise(z.void())])
+		),
+	}),
+});
+
+const starlightPluginsConfigSchema = z.array(starlightPluginSchema).default([]);
+
+type StarlightPluginsUserConfig = z.input<typeof starlightPluginsConfigSchema>;
+
+export type StarlightPlugin = z.input<typeof starlightPluginSchema>;
+
+export type StarlightUserConfigWithPlugins = StarlightUserConfig & {
+	/**
+	 * A list of plugins to extend Starlight with.
+	 *
+	 * @example
+	 * // Add Starlight Algolia plugin.
+	 * starlight({
+	 * 	plugins: [starlightAlgolia({ … })],
+	 * })
+	 */
+	plugins?: StarlightPluginsUserConfig;
+};
+
+export type StarlightPluginContext = Pick<
+	Parameters<NonNullable<AstroIntegration['hooks']['astro:config:setup']>>[0],
+	'command' | 'config' | 'isRestart' | 'logger'
+>;

package/utils/route-data.ts

@@ -29,6 +29,8 @@ export interface StarlightRouteData extends Route {
 	lastUpdated: Date | undefined;
 	/** URL object for the address where this page can be edited if enabled. */
 	editUrl: URL | undefined;
+	/** Record of UI strings localized for the current page. */
+	labels: ReturnType<ReturnType<typeof useTranslations>['all']>;
 }
 
 export function generateRouteData({
@@ -48,6 +50,7 @@ export function generateRouteData({
 		toc: getToC(props),
 		lastUpdated: getLastUpdated(props),
 		editUrl: getEditUrl(props),
+		labels: useTranslations(locale).all(),
 	};
 }
 

package/utils/user-config.ts

@@ -190,6 +190,13 @@ 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.
+	 */
+	pagefind: z.boolean().default(true),
+
 	/** Specify paths to components that should override Starlight’s default components */
 	components: ComponentConfigSchema(),