Repository: withastro/starlight (2025-07-12T10:21:21Z)

Issue:
/ can't be replaced anymore
### What version of `starlight` are you using?

5.11.0

### What version of `astro` are you using?

0.34.4

### What package manager are you using?

npm

### What operating system are you using?

macOS

### What browser are you using?

Chrome, Safari & Firefox

### Describe the Bug

I don't want to use the default index page.

In Astro 4, I was able to put the first page of the documentation as root by setting

 ~~~
slug: /
~~~

This now only delivers a 404 page when navigating to the domain.


### Link to Minimal Reproducible Example

https://github.com/CodeAndWeb/starlight-issue-with-root

### Participation

- [ ] I am willing to submit a pull request for this issue.


Discussion:
In newer updates this behaviour has changed.
You can try redirecting it. 
Just to try to understand the root cause: why can’t you use `src/docs/index.md`?

I’m not sure why or when this behaviour changed — seeing as you mentioned Astro 4, I guess it was maybe in the migration from Astro 4 to 5?
Using index.md in deed solves the issue :-)

I had organized the doc files on the file system to be prefixed with numbers to have then ordered in the same way I had them in the side bar of the documentation

10-getting-started.md
20-insalling.md
...

Otherwise they would be sorted alphabetically in my IDE and it would be quite confusing.
Since I don't want the numbers to show up on the webpage, I used slugs to use the "real" urls.


Still not 100% sure what changed on Astro’s end, but switching to `slug: index` fixes this for me:

```diff
---
title: Example Guide
-slug: /
+slug: index
---
```

I also had to update the sidebar config to match. Here’s your example working: https://stackblitz.com/edit/github-xum4xhdx?file=src%2Fcontent%2Fdocs%2Fguides%2Fexample.md,astro.config.mjs
Going to close this as a change in Astro which is beyond Starlight’s control. Given the change happened across major versions of Astro from what I understand (v4 => v5), the best course of action might be for us to document this as a breaking change and add it to the [“Upgrade to Astro v5”](https://docs.astro.build/en/guides/upgrade-to/v5/) guide.
Thanks to the fearless investigations of @ArmandPhilippot we realised that this _was_ in fact a Starlight bug introduced in v0.32! Apologies for jumping the gun on assuming this was Astro-related.

Our next patch release will fix this thanks to @HiDeoo’s meticulous PR #3293.



Patch:
diff --git a/.changeset/popular-planets-whisper.md b/.changeset/popular-planets-whisper.md
new file mode 100644
index 00000000000..85dd9fa3918
--- /dev/null
+++ b/.changeset/popular-planets-whisper.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Fixes an issue preventing to override the slug of a page with the [`slug` frontmatter property](https://starlight.astro.build/reference/frontmatter/#slug) using the `/` value.
diff --git a/packages/starlight/utils/slugs.ts b/packages/starlight/utils/slugs.ts
index c54e095d50e..996a624ac03 100644
--- a/packages/starlight/utils/slugs.ts
+++ b/packages/starlight/utils/slugs.ts
@@ -40,7 +40,7 @@ function localeToDir(locale: string | undefined): 'ltr' | 'rtl' {
 }
 
 export function slugToParam(slug: string): string | undefined {
-	return slug === 'index' || slug === ''
+	return slug === 'index' || slug === '' || slug === '/'
 		? undefined
 		: slug.endsWith('/index')
 			? slug.slice(0, -6)


Test patch:
diff --git a/packages/starlight/__tests__/basics/slugs.test.ts b/packages/starlight/__tests__/basics/slugs.test.ts
index a3f8f3992c6..0a42b9572b4 100644
--- a/packages/starlight/__tests__/basics/slugs.test.ts
+++ b/packages/starlight/__tests__/basics/slugs.test.ts
@@ -31,6 +31,9 @@ describe('slugToParam', () => {
 	test('returns undefined for root index', () => {
 		expect(slugToParam('index')).toBeUndefined();
 	});
+	test('returns undefined for /', () => {
+		expect(slugToParam('/')).toBeUndefined();
+	});
 	test('strips index from end of nested slug', () => {
 		expect(slugToParam('dir/index')).toBe('dir');
 		expect(slugToParam('dir/index/sub-dir/index')).toBe('dir/index/sub-dir');