Add support for draft documentation pages (#1613)

Co-authored-by: Luiz Ferraz <luiz@lferraz.com>
Co-authored-by: liruifengv <liruifeng1024@gmail.com>
Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>
Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

44 files changed, 162 insertions, 29 deletions

diff --git a/.changeset/six-vans-trade.md b/.changeset/six-vans-trade.md
new file mode 100644
index 00000000..47b7dd4e
--- /dev/null
+++ b/.changeset/six-vans-trade.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds new `draft` frontmatter option to exclude a page from production builds.
diff --git a/docs/src/content/docs/guides/pages.mdx b/docs/src/content/docs/guides/pages.mdx
index 358f3e48..bb382590 100644
--- a/docs/src/content/docs/guides/pages.mdx
+++ b/docs/src/content/docs/guides/pages.mdx
@@ -105,6 +105,7 @@ The following properties differ from Markdown frontmatter:
 - The [`slug`](/reference/frontmatter/#slug) property is not supported and is automatically set based on the custom page’s URL.
 - The [`editUrl`](/reference/frontmatter/#editurl) option requires a URL to display an edit link.
 - The [`sidebar`](/reference/frontmatter/#sidebar) frontmatter property for customizing how the page appears in [autogenerated link groups](/reference/configuration/#sidebar) is not available. Pages using the `<StarlightPage />` component are not part of a collection and cannot be added to an autogenerated sidebar group.
+- The [`draft`](/reference/frontmatter/#draft) option only displays a [notice](/reference/overrides/#draftcontentnotice) that the page is a draft but does not automatically exclude it from production builds.
 
 ##### `sidebar`
 
diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index 89f3b43c..32ae46ca 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/docs/src/content/docs/reference/frontmatter.md
@@ -268,6 +268,21 @@ pagefind: false
 ---
 ```
 
+### `draft`
+
+**type:** `boolean`  
+**default:** `false`
+
+Set whether this page should be considered a draft and not be included in [production builds](https://docs.astro.build/en/reference/cli-reference/#astro-build) and [autogenerated link groups](/guides/sidebar/#autogenerated-groups). Set to `true` to mark a page as a draft and make it only visible during development.
+
+```md
+---
+# src/content/docs/example.md
+# Exclude this page from production builds
+draft: true
+---
+```
+
 ### `sidebar`
 
 **type:** [`SidebarConfig`](#sidebarconfig)
diff --git a/docs/src/content/docs/reference/overrides.md b/docs/src/content/docs/reference/overrides.md
index b758b1ea..74ae9032 100644
--- a/docs/src/content/docs/reference/overrides.md
+++ b/docs/src/content/docs/reference/overrides.md
@@ -338,6 +338,12 @@ Component containing the `<h1>` element for the current page.
 
 Implementations should ensure they set `id="_top"` on the `<h1>` element as in the default implementation.
 
+#### `DraftContentNotice`
+
+**Default component:** [`DraftContentNotice.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/DraftContentNotice.astro)
+
+Notice displayed to users during development when the current page is marked as a draft.
+
 #### `FallbackContentNotice`
 
 **Default component:** [`FallbackContentNotice.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/FallbackContentNotice.astro)
diff --git a/packages/starlight/__tests__/basics/config-errors.test.ts b/packages/starlight/__tests__/basics/config-errors.test.ts
index 2b9eab93..85ebd4c1 100644
--- a/packages/starlight/__tests__/basics/config-errors.test.ts
+++ b/packages/starlight/__tests__/basics/config-errors.test.ts
@@ -17,6 +17,7 @@ test('parses valid config successfully', () => {
 		  "components": {
 		    "Banner": "@astrojs/starlight/components/Banner.astro",
 		    "ContentPanel": "@astrojs/starlight/components/ContentPanel.astro",
+		    "DraftContentNotice": "@astrojs/starlight/components/DraftContentNotice.astro",
 		    "EditLink": "@astrojs/starlight/components/EditLink.astro",
 		    "FallbackContentNotice": "@astrojs/starlight/components/FallbackContentNotice.astro",
 		    "Footer": "@astrojs/starlight/components/Footer.astro",
diff --git a/packages/starlight/__tests__/basics/routing.test.ts b/packages/starlight/__tests__/basics/routing.test.ts
index 84c3ae58..9805362f 100644
--- a/packages/starlight/__tests__/basics/routing.test.ts
+++ b/packages/starlight/__tests__/basics/routing.test.ts
@@ -8,7 +8,7 @@ vi.mock('astro:content', async () =>
 		docs: [
 			['404.md', { title: 'Not found' }],
 			['index.mdx', { title: 'Home page' }],
-			['guides/authoring-content.md', { title: 'Authoring content' }],
+			['guides/authoring-content.md', { title: 'Authoring content', draft: true }],
 		],
 	})
 );
@@ -41,3 +41,21 @@ test('routes have locale data added', () => {
 		expect(route.locale).toBeUndefined();
 	}
 });
+
+test('routes includes drafts except in production', async () => {
+	expect(routes.find((route) => route.id === 'guides/authoring-content.md')).toBeTruthy();
+
+	// Reset the modules registry so that re-importing `utils/routing.ts` re-evaluates the module and
+	// re-computes the routes. Re-importing the module is necessary because top-level imports cannot
+	// be re-evaluated.
+	vi.resetModules();
+	// Set the mode to production.
+	vi.stubEnv('MODE', 'production');
+	// Re-import the module to re-evaluate it.
+	const { routes: prodRoutes } = await import('../../utils/routing');
+
+	expect(prodRoutes.find((route) => route.id === 'guides/authoring-content.md')).toBeFalsy();
+
+	vi.unstubAllEnvs();
+	vi.resetModules();
+});
diff --git a/packages/starlight/__tests__/test-utils.ts b/packages/starlight/__tests__/test-utils.ts
index 7c145378..2e821544 100644
--- a/packages/starlight/__tests__/test-utils.ts
+++ b/packages/starlight/__tests__/test-utils.ts
@@ -53,7 +53,13 @@ export async function mockedAstroContent({
 	const mockDicts = i18n.map((dict) => mockDict(...dict));
 	return {
 		...mod,
-		getCollection: (collection: 'docs' | 'i18n') => (collection === 'i18n' ? mockDicts : mockDocs),
+		getCollection: (
+			collection: 'docs' | 'i18n',
+			filter?: (entry: ReturnType<typeof mockDoc> | ReturnType<typeof mockDict>) => unknown
+		) => {
+			const entries = collection === 'i18n' ? mockDicts : mockDocs;
+			return filter ? entries.filter(filter) : entries;
+		},
 	};
 }
 
diff --git a/packages/starlight/components/ContentNotice.astro b/packages/starlight/components/ContentNotice.astro
new file mode 100644
index 00000000..9c354f93
--- /dev/null
+++ b/packages/starlight/components/ContentNotice.astro
@@ -0,0 +1,31 @@
+---
+import { Icons } from '../components/Icons';
+import Icon from '../user-components/Icon.astro';
+
+interface Props {
+	icon: keyof typeof Icons;
+	label: string;
+}
+
+const { icon, label } = Astro.props;
+---
+
+<p class="sl-flex">
+	<Icon name={icon} size="1.5em" color="var(--sl-color-orange-high)" />
+	<span>{label}</span>
+</p>
+
+<style>
+	p {
+		border: 1px solid var(--sl-color-orange);
+		padding: 0.75em 1em;
+		background-color: var(--sl-color-orange-low);
+		color: var(--sl-color-orange-high);
+		width: max-content;
+		max-width: 100%;
+		align-items: center;
+		gap: 0.75em;
+		font-size: var(--sl-text-body-sm);
+		line-height: var(--sl-line-height-headings);
+	}
+</style>
diff --git a/packages/starlight/components/DraftContentNotice.astro b/packages/starlight/components/DraftContentNotice.astro
new file mode 100644
index 00000000..67cd0466
--- /dev/null
+++ b/packages/starlight/components/DraftContentNotice.astro
@@ -0,0 +1,8 @@
+---
+import ContentNotice from './ContentNotice.astro';
+import type { Props } from '../props';
+
+const { labels } = Astro.props;
+---
+
+<ContentNotice icon="warning" label={labels['page.draft']} />
diff --git a/packages/starlight/components/FallbackContentNotice.astro b/packages/starlight/components/FallbackContentNotice.astro
index 44d553a4..b3474fb2 100644
--- a/packages/starlight/components/FallbackContentNotice.astro
+++ b/packages/starlight/components/FallbackContentNotice.astro
@@ -1,27 +1,8 @@
 ---
-import Icon from '../user-components/Icon.astro';
+import ContentNotice from './ContentNotice.astro';
 import type { Props } from '../props';
 
 const { labels } = Astro.props;
 ---
 
-<p class="sl-flex">
-	<Icon name={'warning'} size="1.5em" color="var(--sl-color-orange-high)" /><span
-		>{labels['i18n.untranslatedContent']}</span
-	>
-</p>
-
-<style>
-	p {
-		border: 1px solid var(--sl-color-orange);
-		padding: 0.75em 1em;
-		background-color: var(--sl-color-orange-low);
-		color: var(--sl-color-orange-high);
-		width: max-content;
-		max-width: 100%;
-		align-items: center;
-		gap: 0.75em;
-		font-size: var(--sl-text-body-sm);
-		line-height: var(--sl-line-height-headings);
-	}
-</style>
+<ContentNotice icon="warning" label={labels['i18n.untranslatedContent']} />
diff --git a/packages/starlight/components/Page.astro b/packages/starlight/components/Page.astro
index 515c6234..d040a5d6 100644
--- a/packages/starlight/components/Page.astro
+++ b/packages/starlight/components/Page.astro
@@ -11,6 +11,7 @@ import '../style/util.css';
 import Banner from 'virtual:starlight/components/Banner';
 import ContentPanel from 'virtual:starlight/components/ContentPanel';
 import FallbackContentNotice from 'virtual:starlight/components/FallbackContentNotice';
+import DraftContentNotice from 'virtual:starlight/components/DraftContentNotice';
 import Footer from 'virtual:starlight/components/Footer';
 import Head from 'virtual:starlight/components/Head';
 import Header from 'virtual:starlight/components/Header';
@@ -101,6 +102,7 @@ const pagefindEnabled =
 							<>
 								<ContentPanel {...Astro.props}>
 									<PageTitle {...Astro.props} />
+									{Astro.props.entry.data.draft && <DraftContentNotice {...Astro.props} />}
 									{Astro.props.isFallback && <FallbackContentNotice {...Astro.props} />}
 								</ContentPanel>
 								<ContentPanel {...Astro.props}>
diff --git a/packages/starlight/package.json b/packages/starlight/package.json
index 2dc4d5a9..4991eec2 100644
--- a/packages/starlight/package.json
+++ b/packages/starlight/package.json
@@ -98,6 +98,10 @@
       "types": "./components/FallbackContentNotice.astro.tsx",
       "import": "./components/FallbackContentNotice.astro"
     },
+    "./components/DraftContentNotice.astro": {
+      "types": "./components/DraftContentNotice.astro.tsx",
+      "import": "./components/DraftContentNotice.astro"
+    },
     "./components/Page.astro": {
       "types": "./components/Page.astro.tsx",
       "import": "./components/Page.astro"
diff --git a/packages/starlight/schema.ts b/packages/starlight/schema.ts
index ad281e5c..c3fd1d2a 100644
--- a/packages/starlight/schema.ts
+++ b/packages/starlight/schema.ts
@@ -103,6 +103,12 @@ const StarlightFrontmatterSchema = (context: SchemaContext) =>
 
 		/** Pagefind indexing for this page - set to false to disable. */
 		pagefind: z.boolean().default(true),
+
+		/**
+		 * Indicates that this page is a draft and will not be included in production builds.
+		 * Note that the page will still be available when running Astro in development mode.
+		 */
+		draft: z.boolean().default(false),
 	});
 /** Type of Starlight’s default frontmatter schema. */
 type DefaultSchema = ReturnType<typeof StarlightFrontmatterSchema>;
diff --git a/packages/starlight/schemas/components.ts b/packages/starlight/schemas/components.ts
index 26253031..3ae79ec6 100644
--- a/packages/starlight/schemas/components.ts
+++ b/packages/starlight/schemas/components.ts
@@ -203,6 +203,15 @@ export function ComponentConfigSchema() {
 				.default('@astrojs/starlight/components/FallbackContentNotice.astro'),
 
 			/**
+			 * Notice displayed to users on draft pages. Only used in development mode.
+			 *
+			 * @see {@link https://github.com/withastro/starlight/blob/main/packages/starlight/components/DraftContentNotice.astro `DraftContentNotice` default implementation}
+			 */
+			DraftContentNotice: z
+				.string()
+				.default('@astrojs/starlight/components/DraftContentNotice.astro'),
+
+			/**
 			 * Component rendered at the top of the page when `hero` is set in frontmatter. The default
 			 * implementation shows a large title, tagline, and call-to-action links alongside an optional image.
 			 *
diff --git a/packages/starlight/schemas/i18n.ts b/packages/starlight/schemas/i18n.ts
index 25fa35c9..c141a83e 100644
--- a/packages/starlight/schemas/i18n.ts
+++ b/packages/starlight/schemas/i18n.ts
@@ -123,6 +123,12 @@ function starlightI18nSchema() {
 				.string()
 				.describe('Label shown on the “next page” pagination arrow in the page footer.'),
 
+			'page.draft': z
+				.string()
+				.describe(
+					'Development-only notice informing users they are on a page that is a draft which will not be included in production builds.'
+				),
+
 			'404.text': z.string().describe('Text shown on Starlight’s default 404 page'),
 			'aside.tip': z.string().describe('Text shown on the tip aside variant'),
 			'aside.note': z.string().describe('Text shown on the note aside variant'),
diff --git a/packages/starlight/translations/ar.json b/packages/starlight/translations/ar.json
index 55bf01d8..9a489921 100644
--- a/packages/starlight/translations/ar.json
+++ b/packages/starlight/translations/ar.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "اخر تحديث:",
   "page.previousLink": "السابق",
   "page.nextLink": "التالي",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "الصفحة غير موجودة. تأكد من الرابط أو ابحث بإستعمال شريط البحث.",
   "aside.note": "ملحوظة",
   "aside.tip": "نصيحة",
diff --git a/packages/starlight/translations/cs.json b/packages/starlight/translations/cs.json
index fc800c69..f086f7fb 100644
--- a/packages/starlight/translations/cs.json
+++ b/packages/starlight/translations/cs.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Poslední aktualizace:",
   "page.previousLink": "Předchozí",
   "page.nextLink": "Další",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Stránka nenalezena. Zkontrolujte adresu URL nebo zkuste použít vyhledávací pole.",
   "aside.note": "Note",
   "aside.tip": "Tip",
diff --git a/packages/starlight/translations/da.json b/packages/starlight/translations/da.json
index c2a20d83..065c7a12 100644
--- a/packages/starlight/translations/da.json
+++ b/packages/starlight/translations/da.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Sidst opdateret:",
   "page.previousLink": "Forrige",
   "page.nextLink": "Næste",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Siden er ikke fundet. Tjek din URL eller prøv søgelinjen.",
   "aside.note": "Note",
   "aside.tip": "Tip",
diff --git a/packages/starlight/translations/de.json b/packages/starlight/translations/de.json
index de9c0d62..de181b7a 100644
--- a/packages/starlight/translations/de.json
+++ b/packages/starlight/translations/de.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Zuletzt bearbeitet:",
   "page.previousLink": "Vorherige Seite",
   "page.nextLink": "Nächste Seite",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Seite nicht gefunden. Überprüfe die URL oder nutze die Suchleiste.",
   "aside.note": "Hinweis",
   "aside.tip": "Tipp",
diff --git a/packages/starlight/translations/en.json b/packages/starlight/translations/en.json
index 6506b4fd..a7228c91 100644
--- a/packages/starlight/translations/en.json
+++ b/packages/starlight/translations/en.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Last updated:",
   "page.previousLink": "Previous",
   "page.nextLink": "Next",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Page not found. Check the URL or try using the search bar.",
   "aside.note": "Note",
   "aside.tip": "Tip",
diff --git a/packages/starlight/translations/es.json b/packages/starlight/translations/es.json
index 551c1c26..1d52d0c7 100644
--- a/packages/starlight/translations/es.json
+++ b/packages/starlight/translations/es.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Última actualización:",
   "page.previousLink": "Página anterior",
   "page.nextLink": "Siguiente página",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Página no encontrada. Verifica la URL o intenta usar la barra de búsqueda.",
   "aside.note": "Nota",
   "aside.tip": "Consejo",
diff --git a/packages/starlight/translations/fa.json b/packages/starlight/translations/fa.json
index 892a65ac..47e5b202 100644
--- a/packages/starlight/translations/fa.json
+++ b/packages/starlight/translations/fa.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "آخرین به‌روزرسانی:",
   "page.previousLink": "قبلی",
   "page.nextLink": "بعدی",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "صفحه یافت نشد. لطفاً URL را بررسی کنید یا از جستجو استفاده نمایید.",
   "aside.note": "یادداشت",
   "aside.tip": "نکته",
diff --git a/packages/starlight/translations/fr.json b/packages/starlight/translations/fr.json
index 8e15eef9..6e8cf9ba 100644
--- a/packages/starlight/translations/fr.json
+++ b/packages/starlight/translations/fr.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Dernière mise à jour :",
   "page.previousLink": "Précédent",
   "page.nextLink": "Suivant",
+  "page.draft": "Ce contenu est une ébauche et ne sera pas inclus dans la version de production.",
   "404.text": "Page non trouvée. Vérifiez l’URL ou essayez d’utiliser la barre de recherche.",
   "aside.note": "Note",
   "aside.tip": "Astuce",
diff --git a/packages/starlight/translations/gl.json b/packages/starlight/translations/gl.json
index fd9e026c..3d7fde51 100644
--- a/packages/starlight/translations/gl.json
+++ b/packages/starlight/translations/gl.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Última actualización:",
   "page.previousLink": "Anterior",
   "page.nextLink": "Seguinte",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Paxina non atopada. Comproba a URL ou intenta usar a barra de busca.",
   "aside.note": "Note",
   "aside.tip": "Tip",
diff --git a/packages/starlight/translations/he.json b/packages/starlight/translations/he.json
index d320e63b..93b3f8eb 100644
--- a/packages/starlight/translations/he.json
+++ b/packages/starlight/translations/he.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "עדכון אחרון:",
   "page.previousLink": "הקודם",
   "page.nextLink": "הבא",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "הדף לא נמצא. אנא בדקו את כתובת האתר או נסו להשתמש בסרגל החיפוש.",
   "aside.note": "Note",
   "aside.tip": "Tip",
diff --git a/packages/starlight/translations/hi.json b/packages/starlight/translations/hi.json
index 5caf36a1..b032372c 100644
--- a/packages/starlight/translations/hi.json
+++ b/packages/starlight/translations/hi.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "आखिरी अद्यतन:",
   "page.previousLink": "पिछला",
   "page.nextLink": "अगला",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "यह पृष्ठ नहीं मिला। URL जांचें या खोज बार का उपयोग करने का प्रयास करें।",
   "aside.note": "टिप्पणी",
   "aside.tip": "संकेत",
diff --git a/packages/starlight/translations/id.json b/packages/starlight/translations/id.json
index 13ae07f3..0f74f94c 100644
--- a/packages/starlight/translations/id.json
+++ b/packages/starlight/translations/id.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Terakhir diperbaharui:",
   "page.previousLink": "Sebelumnya",
   "page.nextLink": "Selanjutnya",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Halaman tidak ditemukan. Cek kembali kolom URL atau gunakan fitur pencarian.",
   "aside.note": "Catatan",
   "aside.tip": "Tips",
diff --git a/packages/starlight/translations/it.json b/packages/starlight/translations/it.json
index 2579eac3..2bf290d7 100644
--- a/packages/starlight/translations/it.json
+++ b/packages/starlight/translations/it.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Ultimo aggiornamento:",
   "page.previousLink": "Indietro",
   "page.nextLink": "Avanti",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Pagina non trovata. Verifica l'URL o prova a utilizzare la barra di ricerca.",
   "aside.note": "Nota",
   "aside.tip": "Consiglio",
diff --git a/packages/starlight/translations/ja.json b/packages/starlight/translations/ja.json
index 7705eb05..848bc174 100644
--- a/packages/starlight/translations/ja.json
+++ b/packages/starlight/translations/ja.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "最終更新日:",
   "page.previousLink": "前へ",
   "page.nextLink": "次へ",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "ページが見つかりません。 URL を確認するか、検索バーを使用してみてください。",
   "aside.note": "ノート",
   "aside.tip": "ヒント",
diff --git a/packages/starlight/translations/ko.json b/packages/starlight/translations/ko.json
index 01c6d065..ed3d7b7e 100644
--- a/packages/starlight/translations/ko.json
+++ b/packages/starlight/translations/ko.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "마지막 업데이트:",
   "page.previousLink": "이전",
   "page.nextLink": "다음",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "페이지를 찾을 수 없습니다. URL을 확인하거나 검색 막대를 사용해 보세요.",
   "aside.note": "노트",
   "aside.tip": "팁",
diff --git a/packages/starlight/translations/nb.json b/packages/starlight/translations/nb.json
index 0ad8374b..d2a5435a 100644
--- a/packages/starlight/translations/nb.json
+++ b/packages/starlight/translations/nb.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Sist oppdatert:",
   "page.previousLink": "Forrige",
   "page.nextLink": "Neste",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Siden ble ikke funnet. Sjekk URL-en eller prøv å bruke søkefeltet.",
   "aside.note": "Note",
   "aside.tip": "Tip",
diff --git a/packages/starlight/translations/nl.json b/packages/starlight/translations/nl.json
index 0d60c3b8..d9994c75 100644
--- a/packages/starlight/translations/nl.json
+++ b/packages/starlight/translations/nl.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Laatst bewerkt:",
   "page.previousLink": "Vorige",
   "page.nextLink": "Volgende",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Pagina niet gevonden. Controleer de URL of probeer de zoekbalk.",
   "aside.note": "Opmerking",
   "aside.tip": "Tip",
diff --git a/packages/starlight/translations/pl.json b/packages/starlight/translations/pl.json
index aa446c4a..234b5eda 100644
--- a/packages/starlight/translations/pl.json
+++ b/packages/starlight/translations/pl.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Ostatnia aktualizacja:",
   "page.previousLink": "Poprzednia strona",
   "page.nextLink": "Następna strona",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Nie znaleziono. Sprawdź URL lub użyj wyszukiwarki.",
   "aside.note": "Notatka",
   "aside.tip": "Wskazówka",
diff --git a/packages/starlight/translations/pt.json b/packages/starlight/translations/pt.json
index 48e9bd9a..d408a998 100644
--- a/packages/starlight/translations/pt.json
+++ b/packages/starlight/translations/pt.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Última atualização:",
   "page.previousLink": "Anterior",
   "page.nextLink": "Próximo",
+  "page.draft": "Esse conteúdo é um rascunho e não será incluído em builds de produção.",
   "404.text": "Página não encontrada. Verifique o URL ou tente usar a barra de pesquisa.",
   "aside.note": "Nota",
   "aside.tip": "Dica",
diff --git a/packages/starlight/translations/ro.json b/packages/starlight/translations/ro.json
index fac890a9..fc808e88 100644
--- a/packages/starlight/translations/ro.json
+++ b/packages/starlight/translations/ro.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Ultima actualizare:",
   "page.previousLink": "Pagina precendentă",
   "page.nextLink": "Pagina următoare",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Pagina nu a fost găsită. Verifică adresa URL sau încercă să folosești bara de căutare.",
   "aside.note": "Mențiune",
   "aside.tip": "Sfat",
diff --git a/packages/starlight/translations/ru.json b/packages/starlight/translations/ru.json
index eace5a8a..ec329055 100644
--- a/packages/starlight/translations/ru.json
+++ b/packages/starlight/translations/ru.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Последнее обновление:",
   "page.previousLink": "Предыдущая",
   "page.nextLink": "Следующая",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Страница не найдена. Проверьте URL или используйте поиск по сайту.",
   "aside.note": "Заметка",
   "aside.tip": "Знали ли вы?",
diff --git a/packages/starlight/translations/sv.json b/packages/starlight/translations/sv.json
index 9221e22b..2675e2a9 100644
--- a/packages/starlight/translations/sv.json
+++ b/packages/starlight/translations/sv.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Senast uppdaterad:",
   "page.previousLink": "Föregående",
   "page.nextLink": "Nästa",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Sidan hittades inte. Kontrollera URL:n eller testa att använda sökfältet.",
   "aside.note": "Note",
   "aside.tip": "Tip",
diff --git a/packages/starlight/translations/tr.json b/packages/starlight/translations/tr.json
index b27f71f3..3ea0d53d 100644
--- a/packages/starlight/translations/tr.json
+++ b/packages/starlight/translations/tr.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Son güncelleme:",
   "page.previousLink": "Önceki",
   "page.nextLink": "Sonraki",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Sayfa bulunamadı. URL'i kontrol edin ya da arama çubuğunu kullanmayı deneyin.",
   "aside.note": "Note",
   "aside.tip": "Tip",
diff --git a/packages/starlight/translations/uk.json b/packages/starlight/translations/uk.json
index 5ceb9c68..dc72ba30 100644
--- a/packages/starlight/translations/uk.json
+++ b/packages/starlight/translations/uk.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Останнє оновлення:",
   "page.previousLink": "Назад",
   "page.nextLink": "Далі",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Сторінку не знайдено. Перевірте URL або спробуйте скористатися пошуком.",
   "aside.note": "Заувага",
   "aside.tip": "Порада",
diff --git a/packages/starlight/translations/vi.json b/packages/starlight/translations/vi.json
index 7d8aa4fa..812799d3 100644
--- a/packages/starlight/translations/vi.json
+++ b/packages/starlight/translations/vi.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "Cập nhật lần cuối:",
   "page.previousLink": "Tiếp",
   "page.nextLink": "Trước",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "Không tìm thấy trang. Kiểm tra URL hoặc thử sử dụng thanh tìm kiếm.",
   "aside.note": "Ghi chú",
   "aside.tip": "Mẹo",
diff --git a/packages/starlight/translations/zh-CN.json b/packages/starlight/translations/zh-CN.json
index 25b25a34..63abbc1d 100644
--- a/packages/starlight/translations/zh-CN.json
+++ b/packages/starlight/translations/zh-CN.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "最近更新：",
   "page.previousLink": "上一页",
   "page.nextLink": "下一页",
+  "page.draft": "此内容为草稿，不会包含在生产版本中。",
   "404.text": "页面未找到。检查 URL 或尝试使用搜索栏。",
   "aside.note": "注意",
   "aside.tip": "提示",
diff --git a/packages/starlight/translations/zh-TW.json b/packages/starlight/translations/zh-TW.json
index 38ca85ae..815c8c1d 100644
--- a/packages/starlight/translations/zh-TW.json
+++ b/packages/starlight/translations/zh-TW.json
@@ -18,6 +18,7 @@
   "page.lastUpdated": "最後更新於：",
   "page.previousLink": "前一則",
   "page.nextLink": "下一則",
+  "page.draft": "This content is a draft and will not be included in production builds.",
   "404.text": "找不到頁面。請檢查網址或改用搜尋功能。",
   "aside.note": "注意",
   "aside.tip": "提示",
diff --git a/packages/starlight/utils/routing.ts b/packages/starlight/utils/routing.ts
index 5b0b7091..8ca555b4 100644
--- a/packages/starlight/utils/routing.ts
+++ b/packages/starlight/utils/routing.ts
@@ -45,12 +45,15 @@ interface Path extends GetStaticPathsItem {
 const normalizeIndexSlug = (slug: string) => (slug === 'index' ? '' : slug);
 
 /** All entries in the docs content collection. */
-const docs: StarlightDocsEntry[] = ((await getCollection('docs')) ?? []).map(
-	({ slug, ...entry }) => ({
-		...entry,
-		slug: normalizeIndexSlug(slug),
-	})
-);
+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),
+}));
 
 function getRoutes(): Route[] {
 	const routes: Route[] = docs.map((entry) => ({
diff --git a/packages/starlight/virtual.d.ts b/packages/starlight/virtual.d.ts
index 4dfce6e3..1e733866 100644
--- a/packages/starlight/virtual.d.ts
+++ b/packages/starlight/virtual.d.ts
@@ -44,6 +44,10 @@ declare module 'virtual:starlight/components/FallbackContentNotice' {
 	const FallbackContentNotice: typeof import('./components/FallbackContentNotice.astro').default;
 	export default FallbackContentNotice;
 }
+declare module 'virtual:starlight/components/DraftContentNotice' {
+	const DraftContentNotice: typeof import('./components/DraftContentNotice.astro').default;
+	export default DraftContentNotice;
+}
 
 declare module 'virtual:starlight/components/Footer' {
 	const Footer: typeof import('./components/Footer.astro').default;