@astrojs/starlight 0.15.4 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @astrojs/starlight
 
+## 0.17.0
+
+### Minor Changes
+
+- [#1389](https://github.com/withastro/starlight/pull/1389) [`21b3620`](https://github.com/withastro/starlight/commit/21b36201aa1e01c8395d0f24b2fa4e32b90550bb) Thanks [@connor-baer](https://github.com/connor-baer)! - Adds new `disable404Route` config option to disable injection of Astro’s default 404 route
+
+- [#1395](https://github.com/withastro/starlight/pull/1395) [`ce05dfb`](https://github.com/withastro/starlight/commit/ce05dfb4b1e9b90fad057d5d4328e4445f986b3b) Thanks [@hippotastic](https://github.com/hippotastic)! - Adds a new [`<Code>` component](https://starlight.astro.build/guides/components/#code) to render dynamic code strings with Expressive Code
+
+## 0.16.0
+
+### Minor Changes
+
+- [#1383](https://github.com/withastro/starlight/pull/1383) [`490c6ef`](https://github.com/withastro/starlight/commit/490c6eff34ab408c4f55777b7b0caa16787dd3d4) Thanks [@delucis](https://github.com/delucis)! - Refactors Starlight’s internal virtual module system for components to avoid circular references
+
+  This is a change to an internal API.
+  If you were importing the internal `virtual:starlight/components` module, this no longer exists.
+  Update your imports to use the individual virtual modules now available for each component, for example `virtual:starlight/components/EditLink`.
+
+- [#1151](https://github.com/withastro/starlight/pull/1151) [`134292d`](https://github.com/withastro/starlight/commit/134292ddd89683007d7de25545d39738a82c626c) Thanks [@kevinzunigacuellar](https://github.com/kevinzunigacuellar)! - Fixes sidebar auto-generation issue when a file and a directory, located at the same level, have identical names.
+
+  For example, `src/content/docs/guides.md` and `src/content/docs/guides/example.md` will now both be included and `src/content/docs/guides.md` is treated in the same way a `src/content/docs/guides/index.md` file would be.
+
+- [#1386](https://github.com/withastro/starlight/pull/1386) [`0163634`](https://github.com/withastro/starlight/commit/0163634abb8578ce7a3d7ceea36432e98ea70e78) Thanks [@delucis](https://github.com/delucis)! - Tightens `line-height` on `<LinkCard>` titles to fix regression from original design
+
+  If you want to preserve the previous `line-height`, you can add the following custom CSS to your site:
+
+  ```css
+  .sl-link-card a {
+  	line-height: 1.6;
+  }
+  ```
+
+- [#1376](https://github.com/withastro/starlight/pull/1376) [`8398432`](https://github.com/withastro/starlight/commit/8398432aa4a0f38e2dd4452dfcdf7033c5713334) Thanks [@delucis](https://github.com/delucis)! - Tweaks vertical spacing in Markdown content styles.
+
+  This is a subtle change to Starlight’s default content styling that should improve most sites:
+
+  - Default vertical spacing between content items is reduced from `1.5rem` to `1rem`.
+  - Spacing before headings is now relative to font size, meaning higher-level headings have slightly more spacing and lower-level headings slightly less.
+
+  The overall impact is to tighten up content that belongs together and improve the visual hierarchy of headings to break up sections.
+
+  Although this is a subtle change, we recommend visually inspecting your site in case this impacts layout of any custom CSS or components.
+
+  If you want to preserve the previous spacing, you can add the following custom CSS to your site:
+
+  ```css
+  /* Restore vertical spacing to match Starlight v0.15 and below. */
+  .sl-markdown-content
+  	:not(a, strong, em, del, span, input, code)
+  	+ :not(a, strong, em, del, span, input, code, :where(.not-content *)) {
+  	margin-top: 1.5rem;
+  }
+  .sl-markdown-content
+  	:not(h1, h2, h3, h4, h5, h6)
+  	+ :is(h1, h2, h3, h4, h5, h6):not(:where(.not-content *)) {
+  	margin-top: 2.5rem;
+  }
+  ```
+
+- [#1372](https://github.com/withastro/starlight/pull/1372) [`773880d`](https://github.com/withastro/starlight/commit/773880de87b79bf3107dbc32df29a86dd11e4e6f) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Updates the table of contents highlighting styles to prevent UI shifts when scrolling through a page.
+
+  If you want to preserve the previous, buggy styling, you can add the following custom CSS to your site:
+
+  ```css
+  starlight-toc a[aria-current='true'],
+  starlight-toc a[aria-current='true']:hover,
+  starlight-toc a[aria-current='true']:focus {
+  	font-weight: 600;
+  	color: var(--sl-color-text-invert);
+  	background-color: var(--sl-color-text-accent);
+  }
+  ```
+
 ## 0.15.4
 
 ### Patch Changes

package/components/Footer.astro

@@ -1,7 +1,9 @@
 ---
 import type { Props } from '../props';
 
-import { EditLink, LastUpdated, Pagination } from 'virtual:starlight/components';
+import EditLink from 'virtual:starlight/components/EditLink';
+import LastUpdated from 'virtual:starlight/components/LastUpdated';
+import Pagination from 'virtual:starlight/components/Pagination';
 ---
 
 <footer>

package/components/Header.astro

@@ -2,13 +2,11 @@
 import config from 'virtual:starlight/user-config';
 import type { Props } from '../props';
 
-import {
-	LanguageSelect,
-	Search,
-	SiteTitle,
-	SocialIcons,
-	ThemeSelect,
-} from 'virtual:starlight/components';
+import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
+import Search from 'virtual:starlight/components/Search';
+import SiteTitle from 'virtual:starlight/components/SiteTitle';
+import SocialIcons from 'virtual:starlight/components/SocialIcons';
+import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
 
 /**
  * Render the `Search` component if Pagefind is enabled or the default search component has been overridden.

package/components/MobileMenuFooter.astro

@@ -1,5 +1,7 @@
 ---
-import { LanguageSelect, ThemeSelect, SocialIcons } from 'virtual:starlight/components';
+import LanguageSelect from 'virtual:starlight/components/LanguageSelect';
+import SocialIcons from 'virtual:starlight/components/SocialIcons';
+import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
 import type { Props } from '../props';
 ---
 

package/components/Page.astro

@@ -8,23 +8,21 @@ import '../style/shiki.css';
 import '../style/util.css';
 
 // Components — can override built-in CSS, but not user CSS.
-import {
-	Banner,
-	ContentPanel,
-	PageTitle,
-	FallbackContentNotice,
-	Footer,
-	Header,
-	Head,
-	Hero,
-	MarkdownContent,
-	PageSidebar,
-	Sidebar,
-	SkipLink,
-	ThemeProvider,
-	PageFrame,
-	TwoColumnContent,
-} from 'virtual:starlight/components';
+import Banner from 'virtual:starlight/components/Banner';
+import ContentPanel from 'virtual:starlight/components/ContentPanel';
+import FallbackContentNotice from 'virtual:starlight/components/FallbackContentNotice';
+import Footer from 'virtual:starlight/components/Footer';
+import Head from 'virtual:starlight/components/Head';
+import Header from 'virtual:starlight/components/Header';
+import Hero from 'virtual:starlight/components/Hero';
+import MarkdownContent from 'virtual:starlight/components/MarkdownContent';
+import PageFrame from 'virtual:starlight/components/PageFrame';
+import PageSidebar from 'virtual:starlight/components/PageSidebar';
+import PageTitle from 'virtual:starlight/components/PageTitle';
+import Sidebar from 'virtual:starlight/components/Sidebar';
+import SkipLink from 'virtual:starlight/components/SkipLink';
+import ThemeProvider from 'virtual:starlight/components/ThemeProvider';
+import TwoColumnContent from 'virtual:starlight/components/TwoColumnContent';
 
 // Remark component CSS (needs to override `MarkdownContent.astro`)
 import '../style/asides.css';

package/components/PageFrame.astro

@@ -1,5 +1,5 @@
 ---
-import { MobileMenuToggle } from 'virtual:starlight/components';
+import MobileMenuToggle from 'virtual:starlight/components/MobileMenuToggle';
 import type { Props } from '../props';
 
 const { hasSidebar, labels } = Astro.props;

package/components/PageSidebar.astro

@@ -1,7 +1,8 @@
 ---
 import type { Props } from '../props';
 
-import { TableOfContents, MobileTableOfContents } from 'virtual:starlight/components';
+import MobileTableOfContents from 'virtual:starlight/components/MobileTableOfContents';
+import TableOfContents from 'virtual:starlight/components/TableOfContents';
 ---
 
 {
@@ -33,14 +34,14 @@ import { TableOfContents, MobileTableOfContents } from 'virtual:starlight/compon
 		line-height: var(--sl-line-height-headings);
 		margin-bottom: 0.5rem;
 	}
-	.right-sidebar-panel :global(a) {
+	.right-sidebar-panel :global(:where(a)) {
 		display: block;
 		font-size: var(--sl-text-xs);
 		text-decoration: none;
 		color: var(--sl-color-gray-3);
 		overflow-wrap: anywhere;
 	}
-	.right-sidebar-panel :global(a:hover) {
+	.right-sidebar-panel :global(:where(a):hover) {
 		color: var(--sl-color-white);
 	}
 	@media (min-width: 72rem) {

package/components/Sidebar.astro

@@ -1,7 +1,7 @@
 ---
 import type { Props } from '../props';
 
-import { MobileMenuFooter } from 'virtual:starlight/components';
+import MobileMenuFooter from 'virtual:starlight/components/MobileMenuFooter';
 import SidebarSublist from './SidebarSublist.astro';
 
 const { sidebar } = Astro.props;

package/components/TableOfContents/TableOfContentsList.astro

@@ -38,12 +38,8 @@ const { toc, isMobile = false, depth = 0 } = Astro.props;
 		padding-inline: calc(1rem * var(--depth) + var(--pad-inline)) var(--pad-inline);
 		line-height: 1.25;
 	}
-	a[aria-current='true'],
-	a[aria-current='true']:hover,
-	a[aria-current='true']:focus {
-		font-weight: 600;
-		color: var(--sl-color-text-invert);
-		background-color: var(--sl-color-text-accent);
+	a[aria-current='true'] {
+		color: var(--sl-color-text-accent);
 	}
 	.isMobile a {
 		--pad-inline: 1rem;

package/components.ts

@@ -4,3 +4,4 @@ export { default as Icon } from './user-components/Icon.astro';
 export { default as Tabs } from './user-components/Tabs.astro';
 export { default as TabItem } from './user-components/TabItem.astro';
 export { default as LinkCard } from './user-components/LinkCard.astro';
+export { Code } from 'astro-expressive-code/components';

package/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',
@@ -51,9 +53,7 @@ export default function StarlightIntegration({
 				// config or by a plugin.
 				const allIntegrations = [...config.integrations, ...integrations];
 				if (!allIntegrations.find(({ name }) => name === 'astro-expressive-code')) {
-					integrations.push(
-						...starlightExpressiveCode({ starlightConfig, astroConfig: config, useTranslations })
-					);
+					integrations.push(...starlightExpressiveCode({ starlightConfig, useTranslations }));
 				}
 				if (!allIntegrations.find(({ name }) => name === '@astrojs/sitemap')) {
 					integrations.push(starlightSitemap(starlightConfig));

package/integrations/expressive-code/exports.ts

@@ -34,3 +34,5 @@
  */
 
 export * from 'astro-expressive-code';
+
+export { getStarlightEcConfigPreprocessor } from './index';

package/integrations/expressive-code/index.ts

@@ -2,8 +2,9 @@ import {
 	astroExpressiveCode,
 	type AstroExpressiveCodeOptions,
 	addClassName,
+	type CustomConfigPreprocessors,
 } from 'astro-expressive-code';
-import type { AstroConfig, AstroIntegration } from 'astro';
+import type { AstroIntegration } from 'astro';
 import type { StarlightConfig } from '../../types';
 import type { createTranslationSystemFromFs } from '../../utils/translations-fs';
 import { pathToLocale } from '../shared/pathToLocale';
@@ -60,56 +61,59 @@ export type StarlightExpressiveCodeOptions = Omit<AstroExpressiveCodeOptions, 't
 	useStarlightUiThemeColors?: boolean | undefined;
 };
 
-export const starlightExpressiveCode = ({
-	astroConfig,
+type StarlightEcIntegrationOptions = {
+	starlightConfig: StarlightConfig;
+	useTranslations?: ReturnType<typeof createTranslationSystemFromFs> | undefined;
+};
+
+/**
+ * Create an Expressive Code configuration preprocessor based on Starlight config.
+ * Used internally to set up Expressive Code and by the `<Code>` component.
+ */
+export function getStarlightEcConfigPreprocessor({
 	starlightConfig,
 	useTranslations,
-}: {
-	astroConfig: Pick<AstroConfig, 'root' | 'srcDir'>;
-	starlightConfig: StarlightConfig;
-	useTranslations: ReturnType<typeof createTranslationSystemFromFs>;
-}): AstroIntegration[] => {
-	const { locales, expressiveCode } = starlightConfig;
-	if (expressiveCode === false) return [];
-	const config: StarlightExpressiveCodeOptions =
-		typeof expressiveCode === 'object' ? expressiveCode : {};
+}: StarlightEcIntegrationOptions): CustomConfigPreprocessors['preprocessAstroIntegrationConfig'] {
+	return (input): AstroExpressiveCodeOptions => {
+		const astroConfig = input.astroConfig;
+		const ecConfig = input.ecConfig as StarlightExpressiveCodeOptions;
+		const { locales } = starlightConfig;
 
-	const {
-		themes: themesInput,
-		customizeTheme,
-		styleOverrides: { textMarkers: textMarkersStyleOverrides, ...otherStyleOverrides } = {},
-		useStarlightDarkModeSwitch,
-		useStarlightUiThemeColors = config.themes === undefined,
-		plugins = [],
-		...rest
-	} = config;
+		const {
+			themes: themesInput,
+			customizeTheme,
+			styleOverrides: { textMarkers: textMarkersStyleOverrides, ...otherStyleOverrides } = {},
+			useStarlightDarkModeSwitch,
+			useStarlightUiThemeColors = ecConfig.themes === undefined,
+			plugins = [],
+			...rest
+		} = ecConfig;
 
-	// Handle the `themes` option
-	const themes = preprocessThemes(themesInput);
-	if (useStarlightUiThemeColors === true && themes.length < 2) {
-		console.warn(
-			`*** Warning: Using the config option "useStarlightUiThemeColors: true" ` +
-				`with a single theme is not recommended. For better color contrast, ` +
-				`please provide at least one dark and one light theme.\n`
-		);
-	}
+		// Handle the `themes` option
+		const themes = preprocessThemes(themesInput);
+		if (useStarlightUiThemeColors === true && themes.length < 2) {
+			console.warn(
+				`*** Warning: Using the config option "useStarlightUiThemeColors: true" ` +
+					`with a single theme is not recommended. For better color contrast, ` +
+					`please provide at least one dark and one light theme.\n`
+			);
+		}
 
-	// Add the `not-content` class to all rendered blocks to prevent them from being affected
-	// by Starlight's default content styles
-	plugins.push({
-		name: 'Starlight Plugin',
-		hooks: {
-			postprocessRenderedBlock: ({ renderData }) => {
-				addClassName(renderData.blockAst, 'not-content');
+		// Add the `not-content` class to all rendered blocks to prevent them from being affected
+		// by Starlight's default content styles
+		plugins.push({
+			name: 'Starlight Plugin',
+			hooks: {
+				postprocessRenderedBlock: ({ renderData }) => {
+					addClassName(renderData.blockAst, 'not-content');
+				},
 			},
-		},
-	});
+		});
 
-	// Add Expressive Code UI translations (if any) for all defined locales
-	addTranslations(locales, useTranslations);
+		// Add Expressive Code UI translations (if any) for all defined locales
+		if (useTranslations) addTranslations(locales, useTranslations);
 
-	return [
-		astroExpressiveCode({
+		return {
 			themes,
 			customizeTheme: (theme) => {
 				if (useStarlightUiThemeColors) {
@@ -151,6 +155,36 @@ export const starlightExpressiveCode = ({
 			getBlockLocale: ({ file }) => pathToLocale(file.path, { starlightConfig, astroConfig }),
 			plugins,
 			...rest,
+		};
+	};
+}
+
+export const starlightExpressiveCode = ({
+	starlightConfig,
+	useTranslations,
+}: StarlightEcIntegrationOptions): AstroIntegration[] => {
+	if (starlightConfig.expressiveCode === false) return [];
+
+	const configArgs =
+		typeof starlightConfig.expressiveCode === 'object'
+			? (starlightConfig.expressiveCode as AstroExpressiveCodeOptions)
+			: {};
+	return [
+		astroExpressiveCode({
+			...configArgs,
+			customConfigPreprocessors: {
+				preprocessAstroIntegrationConfig: getStarlightEcConfigPreprocessor({
+					starlightConfig,
+					useTranslations,
+				}),
+				preprocessComponentConfig: `
+					import starlightConfig from 'virtual:starlight/user-config'
+					import { useTranslations } from '@astrojs/starlight/internal'
+					import { getStarlightEcConfigPreprocessor } from '@astrojs/starlight/expressive-code'
+
+					export default getStarlightEcConfigPreprocessor({ starlightConfig, useTranslations })
+				`,
+			},
 		}),
 	];
 };

package/integrations/expressive-code/theming.ts

@@ -1,5 +1,6 @@
-import fs from 'node:fs';
 import { ExpressiveCodeTheme, type ThemeObjectOrShikiThemeName } from 'astro-expressive-code';
+import nightOwlDark from './themes/night-owl-dark.jsonc?raw';
+import nightOwlLight from './themes/night-owl-light.jsonc?raw';
 
 export type BundledThemeName = 'starlight-dark' | 'starlight-light';
 
@@ -20,13 +21,8 @@ export function preprocessThemes(
 	return themes.map((theme) => {
 		// If the current entry is the name of a bundled theme, load it
 		if (theme === 'starlight-dark' || theme === 'starlight-light') {
-			const bundledThemeFile =
-				theme === 'starlight-dark' ? 'night-owl-dark.jsonc' : 'night-owl-light.jsonc';
-			return customizeBundledTheme(
-				ExpressiveCodeTheme.fromJSONString(
-					fs.readFileSync(new URL(`./themes/${bundledThemeFile}`, import.meta.url), 'utf-8')
-				)
-			);
+			const bundledTheme = theme === 'starlight-dark' ? nightOwlDark : nightOwlLight;
+			return customizeBundledTheme(ExpressiveCodeTheme.fromJSONString(bundledTheme));
 		}
 		// Otherwise, just pass it through
 		return theme;

package/integrations/shared/pathToLocale.ts

@@ -22,11 +22,13 @@ export function pathToLocale(
 ): string | undefined {
 	const srcDir = new URL(astroConfig.srcDir, astroConfig.root);
 	const docsDir = new URL('content/docs/', srcDir);
-	const slug = path
-		// Format path to unix style path.
-		?.replace(/\\/g, '/')
-		// Strip docs path leaving only content collection file ID.
-		// Example: /Users/houston/repo/src/content/docs/en/guide.md => en/guide.md
-		.replace(docsDir.pathname, '');
+	// Format path to unix style path.
+	path = path?.replace(/\\/g, '/');
+	// Ensure that the page path starts with a slash if the docs directory also does,
+	// which makes stripping the docs path in the next step work on Windows, too.
+	if (path && !path.startsWith('/') && docsDir.pathname.startsWith('/')) path = '/' + path;
+	// Strip docs path leaving only content collection file ID.
+	// Example: /Users/houston/repo/src/content/docs/en/guide.md => en/guide.md
+	const slug = path?.replace(docsDir.pathname, '');
 	return slugToLocale(slug, starlightConfig.locales);
 }

package/integrations/virtual-user-config.ts

@@ -22,6 +22,13 @@ export function vitePluginStarlightUserConfig(
 	const resolveId = (id: string) =>
 		JSON.stringify(id.startsWith('.') ? resolve(fileURLToPath(root), id) : id);
 
+	const virtualComponentModules = Object.fromEntries(
+		Object.entries(opts.components).map(([name, path]) => [
+			`virtual:starlight/components/${name}`,
+			`export { default } from ${resolveId(path)};`,
+		])
+	);
+
 	/** Map of virtual module names to their code contents as strings. */
 	const modules = {
 		'virtual:starlight/user-config': `export default ${JSON.stringify(opts)}`,
@@ -41,9 +48,7 @@ export function vitePluginStarlightUserConfig(
 						opts.logo.light
 				  )}; export const logos = { dark, light };`
 			: 'export const logos = {};',
-		'virtual:starlight/components': Object.entries(opts.components)
-			.map(([name, path]) => `export { default as ${name} } from ${resolveId(path)};`)
-			.join(''),
+		...virtualComponentModules,
 	} satisfies Record<string, string>;
 
 	/** Mapping names prefixed with `\0` to their original form. */

package/internal.ts

@@ -0,0 +1 @@
+export { useTranslations } from './utils/translations';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.15.4",
+  "version": "0.17.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -150,6 +150,7 @@
       "types": "./components/Search.astro.tsx",
       "import": "./components/Search.astro"
     },
+    "./internal": "./internal.ts",
     "./props": "./props.ts",
     "./schema": "./schema.ts",
     "./types": "./types.ts",
@@ -165,7 +166,7 @@
     "@astrojs/markdown-remark": "^4.0.1",
     "@types/node": "^18.16.19",
     "@vitest/coverage-v8": "^0.33.0",
-    "astro": "^4.0.1",
+    "astro": "^4.2.1",
     "vitest": "^0.33.0"
   },
   "dependencies": {
@@ -174,7 +175,7 @@
     "@pagefind/default-ui": "^1.0.3",
     "@types/hast": "^3.0.3",
     "@types/mdast": "^4.0.3",
-    "astro-expressive-code": "^0.31.0",
+    "astro-expressive-code": "^0.32.2",
     "bcp-47": "^2.1.0",
     "hast-util-select": "^6.0.2",
     "hastscript": "^8.0.0",

package/style/markdown.css

@@ -1,14 +1,14 @@
 .sl-markdown-content
 	:not(a, strong, em, del, span, input, code)
 	+ :not(a, strong, em, del, span, input, code, :where(.not-content *)) {
-	margin-top: 1.5rem;
+	margin-top: 1rem;
 }
 
 /* Headings after non-headings have more spacing. */
 .sl-markdown-content
 	:not(h1, h2, h3, h4, h5, h6)
 	+ :is(h1, h2, h3, h4, h5, h6):not(:where(.not-content *)) {
-	margin-top: 2.5rem;
+	margin-top: 1.5em;
 }
 
 .sl-markdown-content li + li:not(:where(.not-content *)),

package/user-components/LinkCard.astro

@@ -10,7 +10,7 @@ interface Props extends Omit<HTMLAttributes<'a'>, 'title'> {
 const { title, description, ...attributes } = Astro.props;
 ---
 
-<div>
+<div class="sl-link-card">
 	<span class="sl-flex stack">
 		<a {...attributes}>
 			<span class="title" set:html={title} />
@@ -21,7 +21,7 @@ const { title, description, ...attributes } = Astro.props;
 </div>
 
 <style>
-	div {
+	.sl-link-card {
 		display: grid;
 		grid-template-columns: 1fr auto;
 		gap: 0.5rem;
@@ -34,6 +34,7 @@ const { title, description, ...attributes } = Astro.props;
 
 	a {
 		text-decoration: none;
+		line-height: var(--sl-line-height-headings);
 	}
 
 	/* a11y fix for https://github.com/withastro/starlight/issues/487 */
@@ -52,7 +53,6 @@ const { title, description, ...attributes } = Astro.props;
 		color: var(--sl-color-white);
 		font-weight: 600;
 		font-size: var(--sl-text-lg);
-		line-height: var(--sl-line-height-headings);
 	}
 
 	.description {
@@ -65,12 +65,12 @@ const { title, description, ...attributes } = Astro.props;
 	}
 
 	/* Hover state */
-	div:hover {
+	.sl-link-card:hover {
 		background: var(--sl-color-gray-7, var(--sl-color-gray-6));
 		border-color: var(--sl-color-gray-2);
 	}
 
-	div:hover .icon {
+	.sl-link-card:hover .icon {
 		color: var(--sl-color-white);
 	}
 </style>

package/utils/navigation.ts

@@ -1,4 +1,3 @@
-import { basename, dirname } from 'node:path';
 import config from 'virtual:starlight/user-config';
 import type { Badge } from '../schemas/badge';
 import type { PrevNextLinkConfig } from '../schemas/prevNextLink';
@@ -11,11 +10,12 @@ import type {
 import { createPathFormatter } from './createPathFormatter';
 import { formatPath } from './format-path';
 import { pickLang } from './i18n';
-import { ensureLeadingSlash } from './path';
+import { ensureLeadingSlash, ensureTrailingSlash, stripLeadingAndTrailingSlashes } from './path';
 import { getLocaleRoutes, type Route } from './routing';
 import { localeToLang, slugToPathname } from './slugs';
 
 const DirKey = Symbol('DirKey');
+const SlugKey = Symbol('SlugKey');
 
 export interface Link {
 	type: 'link';
@@ -44,14 +44,16 @@ export type SidebarEntry = Link | Group;
  */
 interface Dir {
 	[DirKey]: undefined;
+	[SlugKey]: string;
 	[item: string]: Dir | Route;
 }
 
 /** Create a new directory object. */
-function makeDir(): Dir {
+function makeDir(slug: string): Dir {
 	const dir = {} as Dir;
-	// Add DirKey as a non-enumerable property so that `Object.entries(dir)` ignores it.
+	// Add DirKey and SlugKey as non-enumerable properties so that `Object.entries(dir)` ignores them.
 	Object.defineProperty(dir, DirKey, { enumerable: false });
+	Object.defineProperty(dir, SlugKey, { value: slug, enumerable: false });
 	return dir;
 }
 
@@ -157,37 +159,48 @@ function getBreadcrumbs(path: string, baseDir: string): string[] {
 	// Index paths will match `baseDir` and don’t include breadcrumbs.
 	if (pathWithoutExt === baseDir) return [];
 	// Ensure base directory ends in a trailing slash.
-	if (!baseDir.endsWith('/')) baseDir += '/';
+	baseDir = ensureTrailingSlash(baseDir);
 	// Strip base directory from path if present.
 	const relativePath = pathWithoutExt.startsWith(baseDir)
 		? pathWithoutExt.replace(baseDir, '')
 		: pathWithoutExt;
-	let dir = dirname(relativePath);
-	// Return no breadcrumbs for items in the root directory.
-	if (dir === '.') return [];
-	return dir.split('/');
+
+	return relativePath.split('/');
 }
 
 /** Turn a flat array of routes into a tree structure. */
 function treeify(routes: Route[], baseDir: string): Dir {
-	const treeRoot: Dir = makeDir();
+	const treeRoot: Dir = makeDir(baseDir);
 	routes
 		// Remove any entries that should be hidden
 		.filter((doc) => !doc.entry.data.sidebar.hidden)
+		// Sort by depth, to build the tree depth first.
+		.sort((a, b) => b.id.split('/').length - a.id.split('/').length)
+		// Build the tree
 		.forEach((doc) => {
-			const breadcrumbs = getBreadcrumbs(doc.id, baseDir);
-
-			// Walk down the route’s path to generate the tree.
-			let currentDir = treeRoot;
-			breadcrumbs.forEach((dir) => {
-				// Create new folder if needed.
-				if (typeof currentDir[dir] === 'undefined') currentDir[dir] = makeDir();
-				// Go into the subdirectory.
-				currentDir = currentDir[dir] as Dir;
+			const parts = getBreadcrumbs(doc.id, baseDir);
+			let currentNode = treeRoot;
+
+			parts.forEach((part, index) => {
+				const isLeaf = index === parts.length - 1;
+
+				// Handle directory index pages by renaming them to `index`
+				if (isLeaf && currentNode.hasOwnProperty(part)) {
+					currentNode = currentNode[part] as Dir;
+					part = 'index';
+				}
+
+				// Recurse down the tree if this isn’t the leaf node.
+				if (!isLeaf) {
+					const path = currentNode[SlugKey];
+					currentNode[part] ||= makeDir(stripLeadingAndTrailingSlashes(path + '/' + part));
+					currentNode = currentNode[part] as Dir;
+				} else {
+					currentNode[part] = doc;
+				}
 			});
-			// We’ve walked through the path. Register the route in this directory.
-			currentDir[basename(doc.slug)] = doc;
 		});
+
 	return treeRoot;
 }
 
@@ -212,24 +225,16 @@ function getOrder(routeOrDir: Route | Dir): number {
 		: // If no order value is found, set it to the largest number possible.
 		  routeOrDir.entry.data.sidebar.order ?? Number.MAX_VALUE;
 }
-/** Get the comparison ID for a given route to sort them alphabetically. */
-function getComparisonId(id: string) {
-	const filename = stripExtension(basename(id));
-	return filename === 'index' ? '' : filename;
-}
 
 /** Sort a directory’s entries by user-specified order or alphabetically if no order specified. */
 function sortDirEntries(dir: [string, Dir | Route][]): [string, Dir | Route][] {
 	const collator = new Intl.Collator(localeToLang(undefined));
-	return dir.sort(([keyA, a], [keyB, b]) => {
+	return dir.sort(([_keyA, a], [_keyB, b]) => {
 		const [aOrder, bOrder] = [getOrder(a), getOrder(b)];
 		// Pages are sorted by order in ascending order.
 		if (aOrder !== bOrder) return aOrder < bOrder ? -1 : 1;
 		// If two pages have the same order value they will be sorted by their slug.
-		return collator.compare(
-			isDir(a) ? keyA : getComparisonId(a.id),
-			isDir(b) ? keyB : getComparisonId(b.id)
-		);
+		return collator.compare(isDir(a) ? a[SlugKey] : a.slug, isDir(b) ? b[SlugKey] : b.slug);
 	});
 }
 

package/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(

package/virtual.d.ts

@@ -24,39 +24,118 @@ declare module 'virtual:starlight/user-images' {
 	};
 }
 
-declare module 'virtual:starlight/components' {
-	export const Banner: typeof import('./components/Banner.astro').default;
-	export const ContentPanel: typeof import('./components/ContentPanel.astro').default;
-	export const PageTitle: typeof import('./components/PageTitle.astro').default;
-	export const FallbackContentNotice: typeof import('./components/FallbackContentNotice.astro').default;
-
-	export const Footer: typeof import('./components/Footer.astro').default;
-	export const LastUpdated: typeof import('./components/LastUpdated.astro').default;
-	export const Pagination: typeof import('./components/Pagination.astro').default;
-	export const EditLink: typeof import('./components/EditLink.astro').default;
-
-	export const Header: typeof import('./components/Header.astro').default;
-	export const LanguageSelect: typeof import('./components/LanguageSelect.astro').default;
-	export const Search: typeof import('./components/Search.astro').default;
-	export const SiteTitle: typeof import('./components/SiteTitle.astro').default;
-	export const SocialIcons: typeof import('./components/SocialIcons.astro').default;
-	export const ThemeSelect: typeof import('./components/ThemeSelect.astro').default;
-
-	export const Head: typeof import('./components/Head.astro').default;
-	export const Hero: typeof import('./components/Hero.astro').default;
-	export const MarkdownContent: typeof import('./components/MarkdownContent.astro').default;
-
-	export const PageSidebar: typeof import('./components/PageSidebar.astro').default;
-	export const TableOfContents: typeof import('./components/TableOfContents.astro').default;
-	export const MobileTableOfContents: typeof import('./components/MobileTableOfContents.astro').default;
-
-	export const Sidebar: typeof import('./components/Sidebar.astro').default;
-	export const SkipLink: typeof import('./components/SkipLink.astro').default;
-	export const ThemeProvider: typeof import('./components/ThemeProvider.astro').default;
-
-	export const PageFrame: typeof import('./components/PageFrame.astro').default;
-	export const MobileMenuToggle: typeof import('./components/MobileMenuToggle.astro').default;
-	export const MobileMenuFooter: typeof import('./components/MobileMenuFooter.astro').default;
-
-	export const TwoColumnContent: typeof import('./components/TwoColumnContent.astro').default;
+declare module 'virtual:starlight/components/Banner' {
+	const Banner: typeof import('./components/Banner.astro').default;
+	export default Banner;
+}
+declare module 'virtual:starlight/components/ContentPanel' {
+	const ContentPanel: typeof import('./components/ContentPanel.astro').default;
+	export default ContentPanel;
+}
+declare module 'virtual:starlight/components/PageTitle' {
+	const PageTitle: typeof import('./components/PageTitle.astro').default;
+	export default PageTitle;
+}
+declare module 'virtual:starlight/components/FallbackContentNotice' {
+	const FallbackContentNotice: typeof import('./components/FallbackContentNotice.astro').default;
+	export default FallbackContentNotice;
+}
+
+declare module 'virtual:starlight/components/Footer' {
+	const Footer: typeof import('./components/Footer.astro').default;
+	export default Footer;
+}
+declare module 'virtual:starlight/components/LastUpdated' {
+	const LastUpdated: typeof import('./components/LastUpdated.astro').default;
+	export default LastUpdated;
+}
+declare module 'virtual:starlight/components/Pagination' {
+	const Pagination: typeof import('./components/Pagination.astro').default;
+	export default Pagination;
+}
+declare module 'virtual:starlight/components/EditLink' {
+	const EditLink: typeof import('./components/EditLink.astro').default;
+	export default EditLink;
+}
+
+declare module 'virtual:starlight/components/Header' {
+	const Header: typeof import('./components/Header.astro').default;
+	export default Header;
+}
+declare module 'virtual:starlight/components/LanguageSelect' {
+	const LanguageSelect: typeof import('./components/LanguageSelect.astro').default;
+	export default LanguageSelect;
+}
+declare module 'virtual:starlight/components/Search' {
+	const Search: typeof import('./components/Search.astro').default;
+	export default Search;
+}
+declare module 'virtual:starlight/components/SiteTitle' {
+	const SiteTitle: typeof import('./components/SiteTitle.astro').default;
+	export default SiteTitle;
+}
+declare module 'virtual:starlight/components/SocialIcons' {
+	const SocialIcons: typeof import('./components/SocialIcons.astro').default;
+	export default SocialIcons;
+}
+declare module 'virtual:starlight/components/ThemeSelect' {
+	const ThemeSelect: typeof import('./components/ThemeSelect.astro').default;
+	export default ThemeSelect;
+}
+
+declare module 'virtual:starlight/components/Head' {
+	const Head: typeof import('./components/Head.astro').default;
+	export default Head;
+}
+declare module 'virtual:starlight/components/Hero' {
+	const Hero: typeof import('./components/Hero.astro').default;
+	export default Hero;
+}
+declare module 'virtual:starlight/components/MarkdownContent' {
+	const MarkdownContent: typeof import('./components/MarkdownContent.astro').default;
+	export default MarkdownContent;
+}
+
+declare module 'virtual:starlight/components/PageSidebar' {
+	const PageSidebar: typeof import('./components/PageSidebar.astro').default;
+	export default PageSidebar;
+}
+declare module 'virtual:starlight/components/TableOfContents' {
+	const TableOfContents: typeof import('./components/TableOfContents.astro').default;
+	export default TableOfContents;
+}
+declare module 'virtual:starlight/components/MobileTableOfContents' {
+	const MobileTableOfContents: typeof import('./components/MobileTableOfContents.astro').default;
+	export default MobileTableOfContents;
+}
+
+declare module 'virtual:starlight/components/Sidebar' {
+	const Sidebar: typeof import('./components/Sidebar.astro').default;
+	export default Sidebar;
+}
+declare module 'virtual:starlight/components/SkipLink' {
+	const SkipLink: typeof import('./components/SkipLink.astro').default;
+	export default SkipLink;
+}
+declare module 'virtual:starlight/components/ThemeProvider' {
+	const ThemeProvider: typeof import('./components/ThemeProvider.astro').default;
+	export default ThemeProvider;
+}
+
+declare module 'virtual:starlight/components/PageFrame' {
+	const PageFrame: typeof import('./components/PageFrame.astro').default;
+	export default PageFrame;
+}
+declare module 'virtual:starlight/components/MobileMenuToggle' {
+	const MobileMenuToggle: typeof import('./components/MobileMenuToggle.astro').default;
+	export default MobileMenuToggle;
+}
+declare module 'virtual:starlight/components/MobileMenuFooter' {
+	const MobileMenuFooter: typeof import('./components/MobileMenuFooter.astro').default;
+	export default MobileMenuFooter;
+}
+
+declare module 'virtual:starlight/components/TwoColumnContent' {
+	const TwoColumnContent: typeof import('./components/TwoColumnContent.astro').default;
+	export default TwoColumnContent;
 }