Add config option to disable 404 page (#1389)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

5 files changed, 40 insertions, 4 deletions

diff --git a/.changeset/odd-rocks-clean.md b/.changeset/odd-rocks-clean.md
new file mode 100644
index 00000000..6c4bffd6
--- /dev/null
+++ b/.changeset/odd-rocks-clean.md
@@ -0,0 +1,5 @@
+---
+"@astrojs/starlight": minor
+---
+
+Adds new `disable404Route` config option to disable injection of Astro’s default 404 route
diff --git a/docs/src/content/docs/guides/customization.mdx b/docs/src/content/docs/guides/customization.mdx
index 58651e60..9b45f213 100644
--- a/docs/src/content/docs/guides/customization.mdx
+++ b/docs/src/content/docs/guides/customization.mdx
@@ -277,6 +277,25 @@ hero:
 ---
 ```
 
+### Disabling the default 404 page
+
+If your project requires an entirely customized 404 layout, you can create a `src/pages/404.astro` route and set the [`disable404Route`](/reference/configuration/#disable404route) config option to disable Starlight’s default route:
+
+```js {9}
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+	integrations: [
+		starlight({
+			title: 'Docs With Custom 404',
+			disable404Route: true,
+		}),
+	],
+});
+```
+
 ## Custom fonts
 
 By default, Starlight uses sans-serif fonts available on a user’s local device for all text.
diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx
index 08fc25e7..b20313e3 100644
--- a/docs/src/content/docs/reference/configuration.mdx
+++ b/docs/src/content/docs/reference/configuration.mdx
@@ -514,6 +514,13 @@ Sets the delimiter between page title and site title in the page’s `<title>` t
 By default, every page has a `<title>` of `Page Title | Site Title`.
 For example, this page is titled “Configuration Reference” and this site is titled “Starlight”, so the `<title>` for this page is “Configuration Reference | Starlight”.
 
+### `disable404Route`
+
+**type:** `boolean`  
+**default:** `'false'`
+
+Disables injecting Starlight's default [404 page](https://docs.astro.build/en/core-concepts/astro-pages/#custom-404-error-page). To use a custom `src/pages/404.astro` route in your project, set this option to `false`.
+
 ### `components`
 
 **type:** `Record<string, string>`
diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
index f5288619..205cc23b 100644
--- a/packages/starlight/index.ts
+++ b/packages/starlight/index.ts
@@ -39,10 +39,12 @@ export default function StarlightIntegration({
 
 				const useTranslations = createTranslationSystemFromFs(starlightConfig, config);
 
-				injectRoute({
-					pattern: '404',
-					entrypoint: '@astrojs/starlight/404.astro',
-				});
+				if (!userConfig.disable404Route) {
+					injectRoute({
+						pattern: '404',
+						entrypoint: '@astrojs/starlight/404.astro',
+					});
+				}
 				injectRoute({
 					pattern: '[...slug]',
 					entrypoint: '@astrojs/starlight/index.astro',
diff --git a/packages/starlight/utils/user-config.ts b/packages/starlight/utils/user-config.ts
index 9a581f3f..f77f4e90 100644
--- a/packages/starlight/utils/user-config.ts
+++ b/packages/starlight/utils/user-config.ts
@@ -205,6 +205,9 @@ const UserConfigSchema = z.object({
 		.string()
 		.default('|')
 		.describe('Will be used as title delimiter in the generated `<title>` tag.'),
+
+	/** Disable Starlight's default 404 page. */
+	disable404Route: z.boolean().default(false).describe("Disable Starlight's default 404 page."),
 });
 
 export const StarlightConfigSchema = UserConfigSchema.strict().transform(