Fix `index.md` slug issue in routing logic (#55)

11 files changed, 340 insertions, 29 deletions

diff --git a/.changeset/eleven-snails-act.md b/.changeset/eleven-snails-act.md
new file mode 100644
index 00000000..8da1bb21
--- /dev/null
+++ b/.changeset/eleven-snails-act.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Fix routing logic to handle `index.md` slug differences between docs collection root and nested directories.
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index c679b3a1..ae30e047 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -38,10 +38,6 @@ export default defineConfig({
           label: 'Deutsch',
           lang: 'de',
         },
-        'fr-ca': {
-          label: 'Français canadien',
-          lang: 'fr-CA',
-        },
       },
       sidebar: [
         {
diff --git a/docs/src/content/docs/de/getting-started.md b/docs/src/content/docs/de/getting-started.md
deleted file mode 100644
index 99fc14f1..00000000
--- a/docs/src/content/docs/de/getting-started.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-title: Erste Schritte
----
diff --git a/docs/src/content/docs/de/index.mdx b/docs/src/content/docs/de/index.mdx
new file mode 100644
index 00000000..6bd2e532
--- /dev/null
+++ b/docs/src/content/docs/de/index.mdx
@@ -0,0 +1,24 @@
+---
+title: Wilkommen, Welt
+---
+
+:::caution[Laufende Arbeiten]
+Starlight befindet sich in einem frühen Entwicklungsstadium, also rechne mit Fehlern und Änderungen, während wir es weiterentwickeln.
+Wenn du etwas findest, das nicht funktioniert, [öffne bitte ein Issue auf GitHub](https://github.com/withastro/starlight/issues/new/choose) oder gib uns auf [Discord](https://astro.build/chat) Bescheid.
+:::
+
+## Was ist im Lieferumfang enthalten?
+
+Starlight enthält alle notwendige Funktionen, um eine Dokumentationsseite schnell zum Laufen zu bringen:
+
+- Unterstützung von Markdown und MDX
+- Leicht zu lesende typografische Stile
+- Syntaxhervorhebung für Code-Beispiele
+- Einfach zu konfigurierende Navigationsmenüs
+- Eingebaute Suchfunktion
+- [Internationalisierungsfunktionen](/de/guides/i18n)
+- Barrierfreie Seitenaufbau
+- Unterstützung von [Komponenten im Inhalt](/de/guides/components) mit MDX
+- Unterstützung für benutzerdefinierte Stile
+- Schnelle und [umweltfreundliche](/de/environmental-impact) Architektur
+- Kompatibilität mit dem [Astro-Ökosystem](https://astro.build/integrations)
diff --git a/docs/src/content/docs/de/reference/configuration.md b/docs/src/content/docs/de/reference/configuration.md
index b5d41c32..8c1f4d3e 100644
--- a/docs/src/content/docs/de/reference/configuration.md
+++ b/docs/src/content/docs/de/reference/configuration.md
@@ -1,3 +1,278 @@
 ---
 title: Konfigurations­referenz
+description: Ein Überblick über alle von Starlight unterstützten Konfigurationsoptionen.
 ---
+
+## Die Starlight-Integration konfigurieren
+
+Du kannst die folgenden Optionen an die Starlight-Integration übergeben.
+
+### `title` (erforderlich)
+
+**Typ:** `string`
+
+Lege den Titel für deine Website fest. Wird in den Metadaten und im Titel der Browser-Tabs verwendet.
+
+### `description`
+
+**Typ:** `string`
+
+Lege die Beschreibung für deine Website fest. Wird in den Metadaten verwendet, die mit Suchmaschinen im `<meta name="description">`-Tag geteilt werden, für Seiten wo `description` nicht im Frontmatter festgelegt ist.
+
+### `logo`
+
+**Typ:** [`LogoConfig`](#logoconfig)
+
+Legt ein Logobild fest, das in der Navigationsleiste neben oder anstelle des Seitentitels angezeigt wird. Du kannst entweder eine einzige `src`-Eigenschaft oder separate Bildquellen für `light` und `dark` festlegen.
+
+```js
+starlight({
+  logo: {
+    src: '/src/assets/my-logo.svg',
+  },
+});
+```
+
+#### `LogoConfig`
+
+```ts
+type LogoConfig = { alt?: string; replacesTitle?: boolean } & (
+  | { src: string }
+  | { light: string; dark: string }
+);
+```
+
+### `tableOfContents`
+
+**Typ:** `{ minHeadingLevel?: number; maxHeadingLevel?: number; }`  
+**Voreinstellung:** `{ minHeadingLevel: 2; maxHeadingLevel: 3; }`
+
+Konfiguriere das Inhaltsverzeichnis, das rechts auf jeder Seite angezeigt wird. Standardmäßig werden `<h2>` und `<h3>` Überschriften in dieses Inhaltsverzeichnis aufgenommen.
+
+### `editLink`
+
+**Typ:** `{ baseUrl: string }`
+
+Aktiviere "Diese Seite bearbeiten"-Links, indem du die Basis-URL für diese festlegst. Der endgültige Link wird `editLink.baseUrl` + der aktuelle Seitenpfad sein. Zum Beispiel, um das Bearbeiten von Seiten im `withastro/starlight` Repo auf GitHub zu ermöglichen:
+
+```js
+starlight({
+  editLink: {
+    baseUrl: 'https://github.com/withastro/starlight/edit/main/',
+  },
+});
+```
+
+Mit dieser Konfiguration würde eine `/einfuehrung` einen Bearbeitungslink haben, der auf `https://github.com/withastro/starlight/edit/main/src/docs/einfuehrung.md` zeigt.
+
+### `sidebar`
+
+**Typ:** [`SidebarGroup[]`](#sidebargroup)
+
+Konfiguriere die Navigationselemente der Seitenleiste deiner Website.
+
+Ein Sidebar ist ein Array von Gruppen, jede mit einem `Label` für die Gruppe und entweder einem `items`-Array oder einem `autogenerate` Konfigurationsobjekt.
+
+Du kannst den Inhalt einer Gruppe manuell festlegen, indem du `items` verwendest, welches ein Array ist, das Links und Untergruppen enthalten kann. Du kannst den Inhalt einer Gruppe auch automatisch aus einem bestimmten Verzeichnis erzeugen, indem du `autogenerate` verwendest.
+
+```js
+starlight({
+  sidebar: [
+    // Eine Gruppe mit der Bezeichnung "Hier anfangen", die zwei Links enthält.
+    {
+      label: 'Hier anfangen',
+      items: [
+        { label: 'Einleitung', link: '/intro' },
+        { label: 'Nächste Schritte', link: '/next-steps' },
+      ],
+    },
+    // Eine Gruppe, die auf alle Seiten im Referenzverzeichnis verweist.
+    {
+      label: 'Referenz',
+      autogenerate: {
+        directory: 'referenz',
+      },
+    },
+  ],
+});
+```
+
+#### `SidebarGroup`
+
+```ts
+type SidebarGroup =
+  | {
+      label: string;
+      items: Array<LinkItem | SidebarGroup>;
+    }
+  | {
+      label: string;
+      autogenerate: {
+        directory: string;
+      };
+    };
+```
+
+#### `LinkItem`
+
+```ts
+interface LinkItem {
+  label: string;
+  link: string;
+}
+```
+
+### `locales`
+
+**Typ:** `{ [dir: string]: LocaleConfig }`
+
+Konfiguriere die Internationalisierung (i18n) für Ihre Website, indem du festlegst, welche `Locales` unterstützt werden.
+
+Jeder Eintrag sollte das Verzeichnis, in dem die Dateien der jeweiligen Sprache gespeichert sind, als Schlüssel verwenden.
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      // Englisch als Standardsprache festlegen.
+      defaultLocale: 'en',
+      locales: {
+        // Englische Seiten in `src/content/docs/en/`
+        en: {
+          label: 'English',
+        },
+        // Chinesische Seiten in `src/content/docs/zh/`
+        zh: {
+          label: '简体中文',
+          lang: 'zh-CN',
+        },
+        // Arabische Seiten in `src/content/docs/ar/`
+        ar: {
+          label: 'العربية',
+          dir: 'rtl',
+        },
+      },
+    }),
+  ],
+});
+```
+
+#### Locale-Optionen
+
+Du kannst die folgenden Optionen für jedes Locale-Schema festlegen:
+
+##### `label` (erforderlich)
+
+**Typ:** `string`
+
+Die Bezeichnung für diese Sprache, die den Benutzern angezeigt werden soll, z. B. im Sprachumschalter. Meistens wird dies der Name der Sprache sein, wie ihn ein Benutzer dieser Sprache erwarten würde, z.B. `"English"`, `"العربية"`, oder `"简体中文"`.
+
+##### `lang`
+
+**Typ:** `string`
+
+Das BCP-47-Tag für diese Sprache, z. B. `"en"`, `"ar"` oder `"zh-CN"`. Wenn nicht gesetzt, wird standardmäßig der Verzeichnisname der Sprache verwendet.
+
+##### `dir`
+
+**Typ:** `'ltr' | 'rtl'`
+
+Die Schreibrichtung dieser Sprache; `"ltr"` für links-nach-rechts (die Voreinstellung) oder `"rtl"` für rechts-nach-links.
+
+#### Root-Locale
+
+Du kannst die Standardsprache ohne ein `/lang/`-Verzeichnis anbieten, indem du ein `root`-Locale setzst:
+
+```js
+starlight({
+  locales: {
+    root: {
+      label: 'Englisch',
+      lang: 'en',
+    },
+    fr: {
+      label: 'Français',
+    },
+  },
+});
+```
+
+So kannst du zum Beispiel `/getting-started/` als englische Seite und `/fr/getting-started/` als entsprechende französische Seite verwenden.
+
+### `defaultLocale`
+
+**Typ:** `string`
+
+Legt die Sprache fest, die als Standard für diese Webseite gilt.
+Der Wert sollte mit einem der Schlüssel deines [`locales`](#locales)-Objekts übereinstimmen.
+(Wenn deine Standardsprache deiner [Root-Locale](#root-locale) ist, kannst du dies überspringen).
+
+Das `defaultLocale` wird verwendet, um Ersatzinhalte bereitzustellen, wenn Übersetzungen fehlen.
+
+### `social`
+
+**Typ:** `{ discord?: string; github?: string; mastodon?: string; twitter?: string }`
+
+Optionale Angaben zu den Social-Media-Konten für diese Site. Wenn du eines dieser Konten hinzufügst, werden sie als Icon-Links in der Kopfzeile der Website angezeigt.
+
+```js
+starlight({
+  social: {
+    discord: 'https://astro.build/chat',
+    github: 'https://github.com/withastro/starlight',
+    mastodon: 'https://m.webtoo.ls/@astro',
+    twitter: 'https://twitter.com/astrodotbuild',
+  },
+});
+```
+
+### `customCss`
+
+**Typ:** `string[]`
+
+Stellen CSS-Dateien zur Verfügung, um das Aussehen deines Starlight-Projekts anzupassen.
+
+Unterstützt lokale CSS-Dateien relativ zum Stammverzeichnis deines Projekts, z.B. `'/src/custom.css'`, und CSS, die du als npm-Modul installiert hast, z.B. `'@fontsource/roboto'`.
+
+```js
+starlight({
+  customCss: ['/src/custom-styles.css', '@fontsource/roboto'],
+});
+```
+
+### `head`
+
+**Typ:** [`HeadConfig[]`](#headconfig)
+
+Füge zusätzliche Tags in den `<head>` deines Starlight-Projekts ein.
+Kann nützlich sein, um Analytics und andere Skripte und Ressourcen von Drittanbietern hinzuzufügen.
+
+```js
+starlight({
+  head: [
+    // Beispiel: Fathom Analytics Skript-Tag hinzufügen.
+    {
+      tag: 'script',
+      attrs: {
+        src: 'https://cdn.usefathom.com/script.js',
+        'data-site': 'MY-FATHOM-ID',
+        defer: true,
+      },
+    },
+  ],
+});
+```
+
+#### `HeadConfig`
+
+```ts
+interface HeadConfig {
+  tag: string;
+  attrs?: Record<string, string | boolean | undefined>;
+  content?: string;
+}
+```
diff --git a/docs/src/content/docs/environmental-impact.md b/docs/src/content/docs/environmental-impact.md
index 86d5f397..f75eb032 100644
--- a/docs/src/content/docs/environmental-impact.md
+++ b/docs/src/content/docs/environmental-impact.md
@@ -116,6 +116,7 @@ These tests with the [Website Carbon Calculator][wcc] compare similar pages buil
 ### Tools
 
 - [Website Carbon Calculator][wcc]
+- [Ecograder](https://ecograder.com/)
 - [WebPageTest Carbon Control](https://www.webpagetest.org/carbon-control/)
 - [Ecoping](https://ecoping.earth/)
 
diff --git a/docs/src/content/docs/fr-ca/getting-started.md b/docs/src/content/docs/fr-ca/getting-started.md
deleted file mode 100644
index 62f02405..00000000
--- a/docs/src/content/docs/fr-ca/getting-started.md
+++ /dev/null
@@ -1,3 +0,0 @@
----
-title: Bien démarrer
----
diff --git a/docs/src/content/docs/reference/configuration.md b/docs/src/content/docs/reference/configuration.md
index a3cd1902..56bfa164 100644
--- a/docs/src/content/docs/reference/configuration.md
+++ b/docs/src/content/docs/reference/configuration.md
@@ -246,7 +246,7 @@ starlight({
 
 ### `head`
 
-**type:** `HeadConfig[]`
+**type:** [`HeadConfig[]`](#headconfig)
 
 Add custom tags to the `<head>` of your Starlight site.
 Can be useful for adding analytics and other third-party scripts and resources.
diff --git a/packages/starlight/components/RightSidebar.astro b/packages/starlight/components/RightSidebar.astro
index b7a30a6b..3979e537 100644
--- a/packages/starlight/components/RightSidebar.astro
+++ b/packages/starlight/components/RightSidebar.astro
@@ -1,13 +1,13 @@
 ---
 import type { MarkdownHeading } from 'astro';
-import type { CollectionEntry } from 'astro:content';
 import config from 'virtual:starlight/user-config';
+import type { StarlightDocsEntry } from '../utils/routing';
 import EditLink from './EditLink.astro';
 import RightSidebarPanel from './RightSidebarPanel.astro';
 import TableOfContents from './TableOfContents.astro';
 
 interface Props {
-  entry: CollectionEntry<'docs'>;
+  entry: StarlightDocsEntry;
   headings: MarkdownHeading[];
 }
 
diff --git a/packages/starlight/utils/routing.ts b/packages/starlight/utils/routing.ts
index 138e7f68..e8d56254 100644
--- a/packages/starlight/utils/routing.ts
+++ b/packages/starlight/utils/routing.ts
@@ -8,8 +8,12 @@ import {
   slugToParam,
 } from './slugs';
 
+export type StarlightDocsEntry = Omit<CollectionEntry<'docs'>, 'slug'> & {
+  slug: string;
+};
+
 export interface Route extends LocaleData {
-  entry: CollectionEntry<'docs'>;
+  entry: StarlightDocsEntry;
   entryMeta: LocaleData;
   slug: string;
   isFallback?: true;
@@ -21,8 +25,17 @@ interface Path extends GetStaticPathsItem {
   props: Route;
 }
 
+/**
+ * Astro is inconsistent in its `index.md` slug generation. In most cases,
+ * `index` is stripped, but in the root of a collection, we get a slug of `index`.
+ * We map that to an empty string for consistent behaviour.
+ */
+const normalizeIndexSlug = (slug: string) => (slug === 'index' ? '' : slug);
+
 /** All entries in the docs content collection. */
-const docs = await getCollection('docs');
+const docs: StarlightDocsEntry[] = (await getCollection('docs')).map(
+  ({ slug, ...entry }) => ({ ...entry, slug: normalizeIndexSlug(slug) })
+);
 
 function getRoutes(): Route[] {
   const routes: Route[] = docs.map((entry) => ({
@@ -87,7 +100,7 @@ export function getLocaleRoutes(locale: string | undefined): Route[] {
  * Get all entries in the docs content collection for a specific locale.
  * A locale of `undefined` is treated as the “root” locale, if configured.
  */
-function getLocaleDocs(locale: string | undefined): CollectionEntry<'docs'>[] {
+function getLocaleDocs(locale: string | undefined): StarlightDocsEntry[] {
   return filterByLocale(docs, locale);
 }
 
@@ -98,11 +111,16 @@ function filterByLocale<T extends { slug: string }>(
 ): T[] {
   if (config.locales) {
     if (locale && locale in config.locales) {
-      return items.filter((i) => i.slug.startsWith(locale + '/'));
+      return items.filter(
+        (i) => i.slug === locale || i.slug.startsWith(locale + '/')
+      );
     } else if (config.locales.root) {
       const langKeys = Object.keys(config.locales).filter((k) => k !== 'root');
+      const isLangIndex = new RegExp(`^(${langKeys.join('|')})$`);
       const isLangDir = new RegExp(`^(${langKeys.join('|')})/`);
-      return items.filter((i) => !isLangDir.test(i.slug));
+      return items.filter(
+        (i) => !isLangIndex.test(i.slug) && !isLangDir.test(i.slug)
+      );
     }
   }
   return items;
diff --git a/packages/starlight/utils/slugs.ts b/packages/starlight/utils/slugs.ts
index 7ce5d506..65b98e63 100644
--- a/packages/starlight/utils/slugs.ts
+++ b/packages/starlight/utils/slugs.ts
@@ -1,4 +1,3 @@
-import type { CollectionEntry } from 'astro:content';
 import config from 'virtual:starlight/user-config';
 
 export interface LocaleData {
@@ -16,9 +15,7 @@ export interface LocaleData {
  * Root locale slugs will return `undefined`.
  * @param slug A collection entry slug
  */
-function slugToLocale(
-  slug: CollectionEntry<'docs'>['slug']
-): string | undefined {
+function slugToLocale(slug: string): string | undefined {
   const locales = Object.keys(config.locales || {});
   const baseSegment = slug.split('/')[0];
   if (baseSegment && locales.includes(baseSegment)) return baseSegment;
@@ -26,9 +23,7 @@ function slugToLocale(
 }
 
 /** Get locale information for a given slug. */
-export function slugToLocaleData(
-  slug: CollectionEntry<'docs'>['slug']
-): LocaleData {
+export function slugToLocaleData(slug: string): LocaleData {
   const locale = slugToLocale(slug);
   return { dir: localeToDir(locale), lang: localeToLang(locale), locale };
 }
@@ -56,7 +51,7 @@ function localeToDir(locale: string | undefined): 'ltr' | 'rtl' {
 }
 
 export function slugToParam(slug: string): string | undefined {
-  return slug === 'index'
+  return slug === 'index' || slug === ''
     ? undefined
     : slug.endsWith('/index')
     ? slug.replace('/index', '')
@@ -79,13 +74,16 @@ export function slugToPathname(slug: string): string {
  * localizedSlug('en/home', undefined)  // => 'home'
  */
 export function localizedSlug(
-  slug: CollectionEntry<'docs'>['slug'],
+  slug: string,
   locale: string | undefined
 ): string {
   const slugLocale = slugToLocale(slug);
   if (slugLocale === locale) return slug;
+  locale = locale || '';
   if (slugLocale) {
-    return slug.replace(slugLocale + '/', locale ? locale + '/' : '');
+    return slug
+      .replace(slugLocale + '/', locale ? locale + '/' : '')
+      .replace(/\/$/, '');
   }
-  return locale + '/' + slug;
+  return slug ? locale + '/' + slug : locale;
 }