@astrojs/starlight 0.36.2 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @astrojs/starlight
 
+## 0.37.0
+
+### Minor Changes
+
+- [#3491](https://github.com/withastro/starlight/pull/3491) [`28810f0`](https://github.com/withastro/starlight/commit/28810f085faf017f3fedd1407e741bdf6c232848) Thanks [@JusticeMatthew](https://github.com/JusticeMatthew)! - Changes text overflow styling in Markdown content
+
+  ⚠️ **Potentially breaking change:** This release switches the [`overflow-wrap`](https://developer.mozilla.org/en-US/docs/Web/CSS/overflow-wrap) CSS style for common elements to `break-word`. In most cases, there should be little visual impact, but this change can impact how layouts with implicit sizing (such as tables) look, improving legibility in how words wrap.
+
+  If you want to preserve the previous styling, you can add the following [custom CSS](https://starlight.astro.build/guides/css-and-tailwind/#custom-css-styles) to your site:
+
+  ```css
+  p, h1, h2, h3, h4, h5, h6, code {
+    overflow-wrap: anywhere;
+  }
+  ```
+
+- [#3351](https://github.com/withastro/starlight/pull/3351) [`239698c`](https://github.com/withastro/starlight/commit/239698c53625f5411792e314994d20c20f9ede77) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Ensures that Starlight CSS layer order is predictable in custom pages using the `<StarlightPage>` component.
+
+  Previously, due to how [import order](https://docs.astro.build/en/guides/styling/#import-order) works in Astro, the `<StarlightPage>` component had to be the first import in custom pages to set up [cascade layers](https://starlight.astro.build/guides/css-and-tailwind/#cascade-layers) used internally by Starlight to manage the order of its styles.
+
+  With this change, this restriction no longer applies and Starlight’s styles will be applied correctly regardless of the import order of the `<StarlightPage>` component.
+
+- [#3521](https://github.com/withastro/starlight/pull/3521) [`ca7b771`](https://github.com/withastro/starlight/commit/ca7b771e5bd4da3fe500bbad562e69d5880690ea) Thanks [@shubham-padia](https://github.com/shubham-padia)! - Fixes an issue where a vertical scrollbar could be displayed on the Starlight `<Tabs>` component when zooming the page
+
+  ⚠️ **Potentially breaking change:** The `<Tabs>` component no longer uses `margin-bottom` and `border-bottom` to highlight the current tab. This is now done with a `box-shadow`. If you have custom styling for your tabs, you may need to update it.
+
+  If you want to preserve the previous styling, you can add the following custom CSS to your site:
+
+  ```css
+  starlight-tabs .tab {
+    margin-bottom: -2px;
+  }
+
+  starlight-tabs .tab > [role='tab'] {
+    border-bottom: 2px solid var(--sl-color-gray-5);
+    box-shadow: none;
+  }
+
+  starlight-tabs .tab [role='tab'][aria-selected='true'] {
+    border-color: var(--sl-color-text-accent);
+  }
+  ```
+
+- [#3549](https://github.com/withastro/starlight/pull/3549) [`1cf50eb`](https://github.com/withastro/starlight/commit/1cf50ebb18c0232be581cf0aff0c192e4c421e55) Thanks [@jacobdalamb](https://github.com/jacobdalamb)! - Updates the default sans-serif system font stack, dropping support for the `-apple-system` and `BlinkMacSystemFont` font names used in older browsers. These are no longer needed in [browsers officially supported by Starlight](https://browsersl.ist/#q=%3E+0.5%25%2C+not+dead%2C+Chrome+%3E%3D+105%2C+Edge+%3E%3D+105%2C+Firefox+%3E%3D+121%2C+Safari+%3E%3D+15.4%2C+iOS+%3E%3D+15.4%2C+not+op_mini+all).
+
+  If you still need to support older browsers, you can add the following custom CSS to your site:
+
+  ```css
+  :root {
+    --sl-font-system: ui-sans-serif, system-ui, -apple-system,
+      BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial,
+      'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
+      'Segoe UI Symbol', 'Noto Color Emoji';
+  }
+  ```
+
+- [#3332](https://github.com/withastro/starlight/pull/3332) [`f61f99d`](https://github.com/withastro/starlight/commit/f61f99dc09c59d26761ffebc611969e20b866191) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Adds a new [`markdown.processedDirs`](https://starlight.astro.build/reference/configuration/#processeddirs) configuration option to specify additional directories where files should be processed by Starlight’s Markdown pipeline.
+
+  By default, Starlight’s processing only applies to Markdown and MDX content loaded using Starlight’s `docsLoader()`. This new option allows to extend this processing to other directories, which can be useful if you are rendering content from a custom content collection using the `<StarlightPage>` component and expect Starlight’s Markdown processing to be applied to that content as well.
+
+## 0.36.3
+
+### Patch Changes
+
+- [#3555](https://github.com/withastro/starlight/pull/3555) [`547dc30`](https://github.com/withastro/starlight/commit/547dc30558b388bfc0505ab0fd8269cecaed462a) Thanks [@Its-Just-Nans](https://github.com/Its-Just-Nans)! - Improves the error message thrown when using a file in the `public/` directory with Starlight’s `customCss` configuration option
+
+- [#3496](https://github.com/withastro/starlight/pull/3496) [`b78fda4`](https://github.com/withastro/starlight/commit/b78fda45be17be7a260309251e82504f9ac8e97a) Thanks [@delucis](https://github.com/delucis)! - Fixes invalid `<head>` output when configuration is missing:
+
+  - Omits `<meta property="og:description" />` if Starlight’s `description` option is unset
+  - Omits `<link rel="canonical" />` and `<meta property="og:url" />` if Astro’s `site` option is unset
+
+- [#3511](https://github.com/withastro/starlight/pull/3511) [`8727df1`](https://github.com/withastro/starlight/commit/8727df1a1b1c82f1303613226000afd53ffe4e36) Thanks [@astrobot-houston](https://github.com/astrobot-houston)! - Updates the `seti:gitlab` icon to match latest version from Seti UI Icons
+
 ## 0.36.2
 
 ### Patch Changes
@@ -30,7 +103,7 @@
 
 - [#3427](https://github.com/withastro/starlight/pull/3427) [`c3b2d0f`](https://github.com/withastro/starlight/commit/c3b2d0fc37bb9b7b6abc6c11b760a4114690ccd4) Thanks [@delucis](https://github.com/delucis)! - Fixes styling of labels that wrap across multiple lines in `<Tabs>` component
 
-  ⚠️ **Potentially breaking change:** Tab labels now have a narrower line-height and additional vertical padding. If you have custom CSS targetting the `<Tabs>` component, you may want to double check the visual appearance of your tabs when updating.
+  ⚠️ **Potentially breaking change:** Tab labels now have a narrower line-height and additional vertical padding. If you have custom CSS targeting the `<Tabs>` component, you may want to double check the visual appearance of your tabs when updating.
 
   If you want to preserve the previous styling, you can add the following custom CSS to your site:
 
@@ -182,7 +255,7 @@
 
 - [#3181](https://github.com/withastro/starlight/pull/3181) [`449c822`](https://github.com/withastro/starlight/commit/449c8229effaab19ece3c0a34e32595809c33cc8) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes an issue where all headings in Markdown and MDX content were rendered with a [clickable anchor link](https://starlight.astro.build/reference/configuration/#headinglinks), even in non-Starlight pages.
 
-- [#3168](https://github.com/withastro/starlight/pull/3168) [`ca693fe`](https://github.com/withastro/starlight/commit/ca693feb4b6aa9f26b3d536d284288773b788ac6) Thanks [@jsparkdev](https://github.com/jsparkdev)! - Updates Korean langage support with improvements and missing translations
+- [#3168](https://github.com/withastro/starlight/pull/3168) [`ca693fe`](https://github.com/withastro/starlight/commit/ca693feb4b6aa9f26b3d536d284288773b788ac6) Thanks [@jsparkdev](https://github.com/jsparkdev)! - Updates Korean language support with improvements and missing translations
 
 ## 0.34.2
 

package/index.ts

@@ -13,11 +13,16 @@ import { AstroError } from 'astro/errors';
 import { spawn } from 'node:child_process';
 import { dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { starlightAsides, starlightDirectivesRestorationIntegration } from './integrations/asides';
+import {
+	starlightRehypePlugins,
+	starlightRemarkPlugins,
+	type RemarkRehypePluginOptions,
+} from './integrations/remark-rehype';
+import { starlightDirectivesRestorationIntegration } from './integrations/asides';
 import { starlightExpressiveCode } from './integrations/expressive-code/index';
 import { starlightSitemap } from './integrations/sitemap';
+import { vitePluginStarlightCssLayerOrder } from './integrations/vite-layer-order';
 import { vitePluginStarlightUserConfig } from './integrations/virtual-user-config';
-import { rehypeRtlCodeSupport } from './integrations/code-rtl-support';
 import {
 	injectPluginTranslationsTypes,
 	runPlugins,
@@ -26,7 +31,6 @@ import {
 } from './utils/plugins';
 import { processI18nConfig } from './utils/i18n';
 import type { StarlightConfig } from './types';
-import { starlightAutolinkHeadings } from './integrations/heading-links';
 
 export default function StarlightIntegration(
 	userOpts: StarlightUserConfigWithPlugins
@@ -115,31 +119,23 @@ export default function StarlightIntegration(
 				const selfIndex = config.integrations.findIndex((i) => i.name === '@astrojs/starlight');
 				config.integrations.splice(selfIndex + 1, 0, ...integrations);
 
+				const remarkRehypeOptions: RemarkRehypePluginOptions = {
+					starlightConfig,
+					astroConfig: config,
+					useTranslations,
+					absolutePathToLang,
+				};
+
 				updateConfig({
 					vite: {
 						plugins: [
+							vitePluginStarlightCssLayerOrder(),
 							vitePluginStarlightUserConfig(command, starlightConfig, config, pluginTranslations),
 						],
 					},
 					markdown: {
-						remarkPlugins: [
-							...starlightAsides({
-								starlightConfig,
-								astroConfig: config,
-								useTranslations,
-								absolutePathToLang,
-							}),
-						],
-						rehypePlugins: [
-							rehypeRtlCodeSupport({ astroConfig: config }),
-							// Process headings and add anchor links.
-							...starlightAutolinkHeadings({
-								starlightConfig,
-								astroConfig: config,
-								useTranslations,
-								absolutePathToLang,
-							}),
-						],
+						remarkPlugins: [...starlightRemarkPlugins(remarkRehypeOptions)],
+						rehypePlugins: [...starlightRehypePlugins(remarkRehypeOptions)],
 					},
 					scopedStyleStrategy: 'where',
 					// If not already configured, default to prefetching all links on hover.

package/integrations/asides.ts

@@ -1,6 +1,6 @@
 /// <reference types="mdast-util-directive" />
 
-import type { AstroConfig, AstroIntegration, AstroUserConfig } from 'astro';
+import type { AstroIntegration } from 'astro';
 import { h as _h, s as _s, type Properties, type Result } from 'hastscript';
 import type { Node, Paragraph as P, Parent, PhrasingContent, Root } from 'mdast';
 import {
@@ -11,23 +11,15 @@ import {
 } from 'mdast-util-directive';
 import { toMarkdown } from 'mdast-util-to-markdown';
 import { toString } from 'mdast-util-to-string';
-import remarkDirective from 'remark-directive';
 import type { Plugin, Transformer } from 'unified';
 import { visit } from 'unist-util-visit';
-import type { HookParameters, StarlightConfig, StarlightIcon } from '../types';
-import { getRemarkRehypeDocsCollectionPath, shouldTransformFile } from './remark-rehype-utils';
+import type { RemarkRehypePluginOptions } from './remark-rehype';
+import type { StarlightIcon } from '../types';
 import { Icons } from '../components/Icons';
 import { fromHtml } from 'hast-util-from-html';
 import type { Element } from 'hast';
 import { throwInvalidAsideIconError } from './asides-error';
 
-interface AsidesOptions {
-	starlightConfig: Pick<StarlightConfig, 'defaultLocale' | 'locales'>;
-	astroConfig: { root: AstroConfig['root']; srcDir: AstroConfig['srcDir'] };
-	useTranslations: HookParameters<'config:setup'>['useTranslations'];
-	absolutePathToLang: HookParameters<'config:setup'>['absolutePathToLang'];
-}
-
 /** Hacky function that generates an mdast HTML tree ready for conversion to HTML by rehype. */
 function h(el: string, attrs: Properties = {}, children: unknown[] = []): P {
 	const { tagName, properties } = _h(el, attrs);
@@ -132,7 +124,7 @@ function makeSvgChildNodes(children: Result['children']): P[] {
  * </aside>
  * ```
  */
-function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
+export function remarkAsides(options: RemarkRehypePluginOptions): Plugin<[], Root> {
 	type Variant = 'note' | 'tip' | 'caution' | 'danger';
 	const variants = new Set(['note', 'tip', 'caution', 'danger']);
 	const isAsideVariant = (s: string): s is Variant => variants.has(s);
@@ -169,11 +161,7 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 		],
 	};
 
-	const docsCollectionPath = getRemarkRehypeDocsCollectionPath(options.astroConfig.srcDir);
-
 	const transformer: Transformer<Root> = (tree, file) => {
-		if (!shouldTransformFile(file, docsCollectionPath)) return;
-
 		const lang = options.absolutePathToLang(file.path);
 		const t = options.useTranslations(lang);
 		visit(tree, (node, index, parent) => {
@@ -253,12 +241,6 @@ function remarkAsides(options: AsidesOptions): Plugin<[], Root> {
 	};
 }
 
-type RemarkPlugins = NonNullable<NonNullable<AstroUserConfig['markdown']>['remarkPlugins']>;
-
-export function starlightAsides(options: AsidesOptions): RemarkPlugins {
-	return [remarkDirective, remarkAsides(options)];
-}
-
 export function remarkDirectivesRestoration() {
 	return function transformer(tree: Root) {
 		visit(tree, (node, index, parent) => {

package/integrations/code-rtl-support.ts

@@ -1,12 +1,7 @@
-import type { AstroConfig } from 'astro';
 import type { Root } from 'hast';
 import { CONTINUE, SKIP, visit } from 'unist-util-visit';
-import type { VFile } from 'vfile';
-import { getRemarkRehypeDocsCollectionPath, shouldTransformFile } from './remark-rehype-utils';
-
-interface RtlCodeSupportOptions {
-	astroConfig: Pick<AstroConfig, 'srcDir'>;
-}
+import type { Transformer } from 'unified';
+import type { RemarkRehypePluginOptions } from './remark-rehype';
 
 /**
  * rehype plugin that adds `dir` attributes to `<code>` and `<pre>`
@@ -22,13 +17,9 @@ interface RtlCodeSupportOptions {
  * - `<code>` is often LTR, but could also be RTL. `dir="auto"` ensures the bidirectional
  *   algorithm treats the contents of `<code>` in isolation and gives its best guess.
  */
-export function rehypeRtlCodeSupport({ astroConfig }: RtlCodeSupportOptions) {
-	const docsCollectionPath = getRemarkRehypeDocsCollectionPath(astroConfig.srcDir);
-
-	return () => (root: Root, file: VFile) => {
-		if (!shouldTransformFile(file, docsCollectionPath)) return;
-
-		visit(root, 'element', (el) => {
+export function rehypeRtlCodeSupport(_options: RemarkRehypePluginOptions) {
+	const transformer: Transformer<Root> = (tree) => {
+		visit(tree, 'element', (el) => {
 			if (el.tagName === 'pre' || el.tagName === 'code') {
 				el.properties ||= {};
 				if (!('dir' in el.properties)) {
@@ -39,4 +30,8 @@ export function rehypeRtlCodeSupport({ astroConfig }: RtlCodeSupportOptions) {
 			return CONTINUE;
 		});
 	};
+
+	return function attacher() {
+		return transformer;
+	};
 }

package/integrations/expressive-code/themes/night-owl-dark.jsonc

@@ -896,7 +896,7 @@
 			},
 		},
 		{
-			"name": "Backtics(``) in Template Strings",
+			"name": "Backticks(``) in Template Strings",
 			"scope": "string.template punctuation.definition.string",
 			"settings": {
 				"foreground": "#d6deeb",
@@ -934,14 +934,14 @@
 			},
 		},
 		{
-			"name": "CoffeScript Variable Assignment",
+			"name": "CoffeeScript Variable Assignment",
 			"scope": "variable.assignment.coffee",
 			"settings": {
 				"foreground": "#31e1eb",
 			},
 		},
 		{
-			"name": "CoffeScript Parameter Function",
+			"name": "CoffeeScript Parameter Function",
 			"scope": "variable.parameter.function.coffee",
 			"settings": {
 				"foreground": "#d6deeb",
@@ -1781,7 +1781,7 @@
 				"keyword.operator.type",
 				"keyword.operator",
 				"keyword",
-				"punctuation.definintion.string",
+				"punctuation.definition.string",
 				"punctuation",
 				"variable.other.readwrite.js",
 				"storage.type",

package/integrations/expressive-code/themes/night-owl-light.jsonc

@@ -839,7 +839,7 @@
 			},
 		},
 		{
-			"name": "Backtics(``) in Template Strings",
+			"name": "Backticks(``) in Template Strings",
 			"scope": "string.template punctuation.definition.string",
 			"settings": {
 				"foreground": "#403f53",
@@ -876,14 +876,14 @@
 			},
 		},
 		{
-			"name": "CoffeScript Variable Assignment",
+			"name": "CoffeeScript Variable Assignment",
 			"scope": "variable.assignment.coffee",
 			"settings": {
 				"foreground": "#31e1eb",
 			},
 		},
 		{
-			"name": "CoffeScript Parameter Function",
+			"name": "CoffeeScript Parameter Function",
 			"scope": "variable.parameter.function.coffee",
 			"settings": {
 				"foreground": "#403f53",
@@ -1680,7 +1680,7 @@
 				"keyword.operator.type",
 				"keyword.operator",
 				"keyword",
-				"punctuation.definintion.string",
+				"punctuation.definition.string",
 				"punctuation",
 				"variable.other.readwrite.js",
 				"storage.type",

package/integrations/heading-links.ts

@@ -1,12 +1,9 @@
-import { rehypeHeadingIds } from '@astrojs/markdown-remark';
-import type { AstroConfig, AstroUserConfig } from 'astro';
 import type { Nodes, Root } from 'hast';
 import { toString } from 'hast-util-to-string';
 import { h } from 'hastscript';
 import type { Transformer } from 'unified';
 import { SKIP, visit } from 'unist-util-visit';
-import type { HookParameters, StarlightConfig } from '../types';
-import { getRemarkRehypeDocsCollectionPath, shouldTransformFile } from './remark-rehype-utils';
+import type { RemarkRehypePluginOptions } from './remark-rehype';
 
 const AnchorLinkIcon = h(
 	'span',
@@ -24,16 +21,13 @@ const AnchorLinkIcon = h(
 /**
  * Add anchor links to headings.
  */
-export default function rehypeAutolinkHeadings(
-	docsCollectionPath: string,
-	useTranslationsForLang: AutolinkHeadingsOptions['useTranslations'],
-	absolutePathToLang: AutolinkHeadingsOptions['absolutePathToLang']
-) {
+export default function rehypeAutolinkHeadings({
+	absolutePathToLang,
+	useTranslations,
+}: RemarkRehypePluginOptions) {
 	const transformer: Transformer<Root> = (tree, file) => {
-		if (!shouldTransformFile(file, docsCollectionPath)) return;
-
 		const pageLang = absolutePathToLang(file.path);
-		const t = useTranslationsForLang(pageLang);
+		const t = useTranslations(pageLang);
 
 		visit(tree, 'element', function (node, index, parent) {
 			if (!headingRank(node) || !node.properties.id || typeof index !== 'number' || !parent) {
@@ -69,36 +63,6 @@ export default function rehypeAutolinkHeadings(
 	};
 }
 
-interface AutolinkHeadingsOptions {
-	starlightConfig: Pick<StarlightConfig, 'markdown'>;
-	astroConfig: Pick<AstroConfig, 'srcDir'> & {
-		experimental: Pick<AstroConfig['experimental'], 'headingIdCompat'>;
-	};
-	useTranslations: HookParameters<'config:setup'>['useTranslations'];
-	absolutePathToLang: HookParameters<'config:setup'>['absolutePathToLang'];
-}
-type RehypePlugins = NonNullable<NonNullable<AstroUserConfig['markdown']>['rehypePlugins']>;
-
-export const starlightAutolinkHeadings = ({
-	starlightConfig,
-	astroConfig,
-	useTranslations,
-	absolutePathToLang,
-}: AutolinkHeadingsOptions): RehypePlugins =>
-	starlightConfig.markdown.headingLinks
-		? [
-				[
-					rehypeHeadingIds,
-					{ experimentalHeadingIdCompat: astroConfig.experimental?.headingIdCompat },
-				],
-				rehypeAutolinkHeadings(
-					getRemarkRehypeDocsCollectionPath(astroConfig.srcDir),
-					useTranslations,
-					absolutePathToLang
-				),
-			]
-		: [];
-
 // This utility is inlined from https://github.com/syntax-tree/hast-util-heading-rank
 // Copyright (c) 2020 Titus Wormer <tituswormer@gmail.com>
 // MIT License: https://github.com/syntax-tree/hast-util-heading-rank/blob/main/license

package/integrations/remark-rehype.ts

@@ -0,0 +1,126 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { AstroConfig } from 'astro';
+import { rehypeHeadingIds } from '@astrojs/markdown-remark';
+import type { Root as RehypeRoot } from 'hast';
+import type { Root as RemarkRoot } from 'mdast';
+import remarkDirective from 'remark-directive';
+import type { Plugin } from 'unified';
+import type { VFile } from 'vfile';
+import { resolveCollectionPath } from '../utils/collection-fs';
+import type { HookParameters, StarlightConfig } from '../types';
+import { remarkAsides } from './asides';
+import { rehypeRtlCodeSupport } from './code-rtl-support';
+import rehypeAutolinkHeadings from './heading-links';
+
+/** List of remark plugins to apply. */
+export function starlightRemarkPlugins(options: RemarkRehypePluginOptions): RemarkPlugin[] {
+	return [remarkDirective, remarkPlugins(options)];
+}
+
+/** List of rehype plugins to apply. */
+export function starlightRehypePlugins(options: RemarkRehypePluginOptions): RehypePlugin[] {
+	return [
+		...(options.starlightConfig.markdown.headingLinks
+			? [
+					[
+						rehypeHeadingIds,
+						{ experimentalHeadingIdCompat: options.astroConfig.experimental?.headingIdCompat },
+					],
+				]
+			: []),
+		rehypePlugins(options),
+	] as RehypePlugin[];
+}
+
+/** Remark plugin applying other Starlight remark plugins if necessary. */
+function remarkPlugins(options: RemarkRehypePluginOptions): RemarkPlugin {
+	const remarkRehypePaths = getRemarkRehypePaths(options);
+
+	return function attacher(this) {
+		const remarkAsidesTransformer = remarkAsides(options).call(this)!;
+
+		return async function transformer(...args) {
+			const [, file] = args;
+
+			if (!shouldTransformFile(file, remarkRehypePaths)) return;
+
+			await remarkAsidesTransformer(...args);
+		};
+	};
+}
+
+/** Rehype plugin applying other Starlight rehype plugins if necessary. */
+function rehypePlugins(options: RemarkRehypePluginOptions): RehypePlugin {
+	const remarkRehypePaths = getRemarkRehypePaths(options);
+
+	return function attacher(this) {
+		const rehypeRtlCodeSupportTransformer = rehypeRtlCodeSupport(options).call(this);
+		const rehypeAutolinkHeadingsTransformer = rehypeAutolinkHeadings(options).call(this);
+
+		return async function transformer(...args) {
+			const [, file] = args;
+
+			if (!shouldTransformFile(file, remarkRehypePaths)) return;
+
+			await rehypeRtlCodeSupportTransformer(...args);
+
+			if (options.starlightConfig.markdown.headingLinks) {
+				await rehypeAutolinkHeadingsTransformer(...args);
+			}
+		};
+	};
+}
+
+/**
+ * Returns the paths to the Starlight docs collection and any additional paths defined in the
+ * `starlightConfig.markdown.processedDirs` option that can be used with the
+ * `shouldTransformFile()` utility to determine if a file should be transformed by a plugin or not.
+ */
+function getRemarkRehypePaths(options: RemarkRehypePluginOptions): string[] {
+	const paths = [normalizePath(resolveCollectionPath('docs', options.astroConfig.srcDir))];
+
+	for (const processedDir of options.starlightConfig.markdown.processedDirs) {
+		paths.push(normalizePath(resolve(fileURLToPath(options.astroConfig.root), processedDir)));
+	}
+
+	return paths;
+}
+
+/**
+ * Determines if a file should be transformed by a remark/rehype plugin, e.g. files without a known
+ * path or files that are not part of the allowed remark/rehype paths are skipped.
+ */
+function shouldTransformFile(file: VFile, remarkRehypePaths: string[]) {
+	// If the content is rendered using the content loader `renderMarkdown()` API, a file path
+	// is not provided.
+	// In that case, we skip the file.
+	if (!file?.path) return false;
+
+	const normalizedPath = normalizePath(file.path);
+
+	// If the document is not part of the allowed remark/rehype paths, skip it.
+	return remarkRehypePaths.some((path) => normalizedPath.startsWith(path));
+}
+
+/**
+ * File path separators seems to be inconsistent on Windows between remark/rehype plugins used on
+ * Markdown vs MDX files.
+ * For the time being, we normalize all paths to unix style paths.
+ */
+const backSlashRegex = /\\/g;
+function normalizePath(path: string) {
+	return path.replace(backSlashRegex, '/');
+}
+
+export interface RemarkRehypePluginOptions {
+	starlightConfig: Pick<StarlightConfig, 'defaultLocale' | 'locales' | 'markdown'>;
+	astroConfig: Pick<AstroConfig, 'root' | 'srcDir'> & {
+		experimental: Pick<AstroConfig['experimental'], 'headingIdCompat'>;
+	};
+	useTranslations: HookParameters<'config:setup'>['useTranslations'];
+	absolutePathToLang: HookParameters<'config:setup'>['absolutePathToLang'];
+}
+
+type RemarkPlugin = Plugin<[], RemarkRoot>;
+type RehypePlugin = Plugin<[], RehypeRoot>;

package/integrations/vite-layer-order.ts

@@ -0,0 +1,66 @@
+import type { ViteUserConfig } from 'astro';
+import MagicString from 'magic-string';
+
+const starlightPageImportSource = '@astrojs/starlight/components/StarlightPage.astro';
+
+/**
+ * Vite plugin that ensures the StarlightPage component is always imported first when imported in
+ * an Astro file.
+ *
+ * This is necessary to ensure a predictable CSS layer order which is defined by the `<Page />`
+ * imported by the `<StarlightPage />` component. If a user imports any other component using
+ * cascade layers before the `<StarlightPage />` component, it will result in undesired layers
+ * being created before we explicitly set the expected layer order.
+ */
+export function vitePluginStarlightCssLayerOrder(): VitePlugin {
+	return {
+		name: 'vite-plugin-starlight-css-layer-order',
+		enforce: 'pre',
+		transform(code, id) {
+			if (
+				!id.endsWith('.astro') ||
+				id.endsWith(starlightPageImportSource) ||
+				code.indexOf('StarlightPage.astro') === -1
+			) {
+				return;
+			}
+
+			let ast: ReturnType<typeof this.parse>;
+
+			try {
+				ast = this.parse(code);
+			} catch {
+				return;
+			}
+
+			let hasStarlightPageImport = false;
+
+			for (const node of ast.body) {
+				if (node.type !== 'ImportDeclaration') continue;
+				if (node.source.value !== starlightPageImportSource) continue;
+
+				const importDefaultSpecifier = node.specifiers.find(
+					(specifier) => specifier.type === 'ImportDefaultSpecifier'
+				);
+				if (!importDefaultSpecifier) continue;
+
+				hasStarlightPageImport = true;
+				break;
+			}
+
+			if (!hasStarlightPageImport) return;
+
+			// Format path to unix style path.
+			const filename = id.replace(/\\/g, '/');
+			const ms = new MagicString(code, { filename });
+			ms.prepend(`import "${starlightPageImportSource}";\n`);
+
+			return {
+				code: ms.toString(),
+				map: ms.generateMap({ hires: 'boundary' }),
+			};
+		},
+	};
+}
+
+type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.36.2",
+  "version": "0.37.0",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -204,6 +204,7 @@
     "i18next": "^23.11.5",
     "js-yaml": "^4.1.0",
     "klona": "^2.0.6",
+    "magic-string": "^0.30.17",
     "mdast-util-directive": "^3.0.0",
     "mdast-util-to-markdown": "^2.1.0",
     "mdast-util-to-string": "^4.0.0",
@@ -223,6 +224,8 @@
     "test": "vitest",
     "test:legacy": "LEGACY_COLLECTIONS=true vitest",
     "test:coverage": "vitest run --coverage",
-    "test:e2e": "playwright install --with-deps chromium && playwright test"
+    "test:e2e": "pnpm test:e2e:chrome",
+    "test:e2e:chrome": "playwright install --with-deps chromium && playwright test --project chrome",
+    "test:e2e:firefox": "playwright install --with-deps firefox && playwright test --project firefox"
   }
 }

package/schemas/i18n.ts

@@ -104,7 +104,7 @@ function starlightI18nSchema() {
 			'sidebarNav.accessibleLabel': z
 				.string()
 				.describe(
-					'Accessible label for the main sidebar `<nav>` element to distinguish it fom other `<nav>` landmarks on the page.'
+					'Accessible label for the main sidebar `<nav>` element to distinguish it from other `<nav>` landmarks on the page.'
 				),
 
 			'tableOfContents.onThisPage': z

package/style/props.css

@@ -84,9 +84,9 @@
 		--sl-line-height: 1.75;
 		--sl-line-height-headings: 1.2;
 
-		--sl-font-system: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI',
-			Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji',
-			'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+		--sl-font-system: ui-sans-serif, system-ui, 'Segoe UI', Roboto, 'Helvetica Neue', Arial,
+			'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol',
+			'Noto Color Emoji';
 		--sl-font-system-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
 			'Courier New', monospace;
 		--__sl-font: var(--sl-font, var(--sl-font-system)), var(--sl-font-system);

package/style/reset.css

@@ -41,7 +41,7 @@
 	h5,
 	h6,
 	code {
-		overflow-wrap: anywhere;
+		overflow-wrap: break-word;
 	}
 
 	code {

package/user-components/Tabs.astro

@@ -116,23 +116,23 @@ if (isSynced) {
 
 		.tab {
 			display: flex;
-			margin-bottom: -2px;
 		}
 		.tab > [role='tab'] {
+			--sl-tab-color-border: var(--sl-color-gray-5);
 			display: flex;
 			align-items: center;
 			gap: 0.5rem;
 			line-height: var(--sl-line-height-headings);
 			padding: 0.275rem 1.25rem;
 			text-decoration: none;
-			border-bottom: 2px solid var(--sl-color-gray-5);
+			box-shadow: 0 2px 0 var(--sl-tab-color-border);
 			color: var(--sl-color-gray-3);
 			outline-offset: var(--sl-outline-offset-inside);
 			overflow-wrap: initial;
 		}
 		.tab [role='tab'][aria-selected='true'] {
+			--sl-tab-color-border: var(--sl-color-text-accent);
 			color: var(--sl-color-white);
-			border-color: var(--sl-color-text-accent);
 			font-weight: 600;
 		}
 

package/user-components/file-tree-icons.ts

@@ -750,7 +750,7 @@ export const FileIcons = {
 	'seti:firefox':
 		'<path d="M23.928 10.888L23.886 10.594Q23.718 9.544 23.634 8.998L23.634 8.998L23.214 9.880L23.130 9.880Q23.550 6.058 20.946 3.790L20.946 3.790L20.862 4.000Q20.442 3.454 19.434 2.740L19.434 2.740Q19.308 3.118 19.644 3.454L19.644 3.454Q20.862 4.546 21.576 5.806L21.576 5.806L21.702 6.016Q21.282 5.428 20.232 4.420L20.232 4.420L19.812 4.000Q18.636 2.740 16.746 2.152L16.746 2.152L16.200 1.984L16.662 2.404Q17.544 3.076 17.964 3.454L17.964 3.454Q18.468 3.958 18.909 4.525Q19.350 5.092 19.392 5.302L19.392 5.302Q18.342 4.462 17.376 4.378L17.376 4.378Q19.980 6.730 19.686 10.132L19.686 10.132Q19.308 9.418 18.720 9.040L18.720 9.040L18.888 10.636Q19.014 11.854 18.888 12.484L18.888 12.484L18.636 13.618L18.342 13.030L18.216 13.618Q17.964 14.542 17.838 15.004L17.838 15.004Q17.544 16.054 16.872 16.684L16.872 16.684Q16.704 16.810 16.494 16.936L16.494 16.936Q16.452 16.978 16.368 16.978L16.368 16.978L16.284 16.978L16.284 16.684L16.200 16.684Q16.074 16.684 16.032 16.726L16.032 16.726Q15.864 16.894 15.696 17.062L15.696 17.062Q15.402 17.482 14.898 17.776L14.898 17.776L14.982 17.440L13.890 17.692Q13.218 17.818 12.882 17.860L12.882 17.860Q12.336 17.944 11.874 17.860L11.874 17.860Q11.160 17.734 10.824 17.356L10.824 17.356L11.538 17.356Q11.412 17.230 11.286 17.188L11.286 17.188L10.026 16.894Q9.438 16.726 9.165 16.558Q8.892 16.390 8.430 15.886L8.430 15.886L8.346 15.802Q7.044 14.542 7.338 12.484L7.338 12.484Q7.422 11.854 7.506 11.560L7.506 11.560Q7.674 11.098 8.052 10.804L8.052 10.804Q7.632 10.510 7.170 10.510L7.170 10.510Q6.498 10.468 5.910 10.909Q5.322 11.350 5.112 12.022L5.112 12.022Q4.566 13.618 5.742 15.172L5.742 15.172L5.868 15.340Q5.112 14.710 4.839 13.639Q4.566 12.568 4.986 11.602L4.986 11.602Q5.322 10.804 6.015 10.405Q6.708 10.006 7.485 10.132Q8.262 10.258 8.850 10.846L8.850 10.846L9.060 11.098Q9.186 10.720 9.165 10.237Q9.144 9.754 8.934 9.460L8.934 9.460Q7.884 8.032 8.199 6.457Q8.514 4.882 9.774 3.664L9.774 3.664L9.942 3.496Q9.060 3.286 8.094 3.874Q7.128 4.462 6.204 5.722L6.204 5.722L6.372 4.714L6.036 4.672Q4.104 4.420 2.634 5.638L2.634 5.638Q1.206 6.772 0.576 8.830L0.576 8.830L0.072 10.636L0.114 10.636L0.450 10.132Q0.282 11.056 0.198 12.148Q0.114 13.240 0.156 13.786L0.156 13.786L0.408 13.030Q0.954 17.062 3.516 19.750L3.516 19.750Q4.776 21.052 6.855 22.249Q8.934 23.446 9.858 23.362L9.858 23.362L9.396 23.068Q9.648 23.110 10.110 23.236L10.110 23.236L10.530 23.320L11.916 23.656L12.672 23.656L12.294 23.320L13.596 23.236Q15.528 23.110 17.418 22.438L17.418 22.438Q17.964 22.270 18.468 21.808L18.468 21.808Q18.804 21.472 19.266 20.884L19.266 20.884Q19.434 20.632 19.644 20.506L19.644 20.506Q21.492 19.498 22.542 17.608L22.542 17.608Q23.046 16.726 22.794 15.592L22.794 15.592Q22.752 15.382 22.836 15.172L22.836 15.172L23.088 14.584Q23.382 13.996 23.487 13.681Q23.592 13.366 23.760 12.694L23.760 12.694L23.928 12.064L23.928 10.888ZM8.178 12.946L7.800 12.694Q7.632 13.618 8.052 14.542Q8.472 15.466 9.270 15.928L9.270 15.928Q9.354 15.970 9.480 15.970L9.480 15.970Q11.412 16.096 12.798 14.962L12.798 14.962L13.092 14.710Q13.470 14.374 14.058 14.458L14.058 14.458Q14.268 14.500 14.373 14.395Q14.478 14.290 14.436 14.080L14.436 14.080Q14.352 13.618 13.932 13.366L13.932 13.366Q12.630 12.694 11.412 13.366L11.412 13.366Q11.076 13.576 10.740 13.660L10.740 13.660Q9.942 13.870 9.018 13.408L9.018 13.408Q8.766 13.282 8.178 12.946L8.178 12.946ZM3.894 4.126L3.978 4.084Q4.062 4.000 4.104 3.958L4.104 3.958Q8.430-0.074 14.100 1.102L14.100 1.102Q15.024 1.312 16.830 1.858L16.830 1.858L18.006 2.194Q15.822 0.682 13.134 0.409Q10.446 0.136 7.905 1.018Q5.364 1.900 3.558 3.832L3.558 3.832L3.894 4.126ZM11.664 7.234L11.664 7.234Q11.706 6.982 11.622 6.898Q11.538 6.814 11.328 6.772L11.328 6.772Q10.908 6.730 10.026 6.730L10.026 6.730L9.816 6.730Q9.438 6.688 9.270 6.646L9.270 6.646Q8.934 6.604 8.724 6.352L8.724 6.352Q8.472 6.940 8.682 7.864Q8.892 8.788 9.354 9.208L9.354 9.208L9.858 8.914Q10.614 8.494 11.034 8.284L11.034 8.284Q11.622 7.990 11.664 7.234ZM3.642 4.420L3.642 4.420Q2.844 3.748 2.760 2.614L2.760 2.614Q2.130 3.286 1.836 4.168L1.836 4.168Q1.626 4.882 1.584 5.890L1.584 5.890Q2.550 4.882 3.642 4.420Z"/>',
 	'seti:gitlab':
-		'<path d="M8.048 9.283L12.000 23.799L15.952 9.283L8.048 9.283ZM2.538 9.283L12.000 23.799L8.048 9.283L2.538 9.283ZM12.000 23.799L2.538 9.283L1.360 13.691Q1.284 13.995 1.360 14.299Q1.436 14.603 1.664 14.793L1.664 14.793L12.000 23.799ZM4.932 0.543L2.538 9.283L8.048 9.283L5.692 0.543Q5.616 0.201 5.312 0.201Q5.008 0.201 4.932 0.543L4.932 0.543ZM21.462 9.283L12.000 23.799L15.952 9.283L21.462 9.283ZM12.000 23.799L21.462 9.283L22.640 13.691Q22.716 13.995 22.640 14.299Q22.564 14.603 22.336 14.793L22.336 14.793L12.000 23.799ZM19.068 0.543L21.462 9.283L15.952 9.283L18.308 0.543Q18.384 0.201 18.688 0.201Q18.992 0.201 19.068 0.543L19.068 0.543Z"/>',
+		'<path d="M23.424 9.639L23.424 9.639L23.382 9.555L20.190 1.155Q20.064 0.903 19.833 0.756Q19.602 0.609 19.329 0.630Q19.056 0.651 18.846 0.819Q18.636 0.987 18.552 1.239L18.552 1.239L16.410 7.875L7.590 7.875L5.448 1.239Q5.364 0.987 5.154 0.819Q4.944 0.651 4.671 0.630Q4.398 0.609 4.167 0.756Q3.936 0.903 3.852 1.155L3.852 1.155L0.576 9.597Q-0.138 11.487 0.408 13.398Q0.954 15.309 2.550 16.527L2.550 16.527L7.506 20.223L11.412 23.163Q11.664 23.373 12.000 23.373Q12.336 23.373 12.588 23.163L12.588 23.163L21.450 16.527Q23.046 15.309 23.592 13.398Q24.138 11.487 23.424 9.639Z"/>',
 	'seti:grunt':
 		'<path d="M19.485 12.265L19.485 12.265Q19.596 12.228 19.855 12.117L19.855 12.117Q20.632 11.747 21.002 11.488L21.002 11.488Q21.483 11.118 21.668 10.637Q21.853 10.156 21.668 9.712Q21.483 9.268 21.002 9.046L21.002 9.046Q20.706 8.898 20.521 8.343L20.521 8.343Q20.373 7.344 20.891 6.493L20.891 6.493Q21.483 5.642 21.113 5.013Q20.743 4.384 19.596 4.310L19.596 4.310L19.485 4.310L19.374 4.199L19.374 4.125Q19.263 3.607 19.300 3.385L19.300 3.385Q19.374 2.978 19.818 2.682L19.818 2.682Q20.077 2.571 20.743 2.349L20.743 2.349Q21.002 2.238 21.335 2.238L21.335 2.238Q21.335 2.090 21.224 2.090L21.224 2.090L21.224 2.090Q20.669 1.461 19.818 1.202L19.818 1.202Q19.078 0.980 18.227 1.054L18.227 1.054Q17.265 1.165 16.488 1.646L16.488 1.646Q15.896 2.016 15.193 2.793L15.193 2.793Q15.045 3.126 14.638 2.904L14.638 2.904Q14.416 2.793 14.416 2.571L14.416 2.571Q14.416 2.460 14.471 2.220Q14.527 1.979 14.527 1.868L14.527 1.868L14.860 1.165Q14.453 1.165 14.046 1.350L14.046 1.350Q13.824 1.461 13.343 1.757L13.343 1.757L13.121 1.868Q12.862 1.461 12.843 1.091Q12.825 0.721 13.010 0.240L13.010 0.240Q12.159 0.536 11.715 0.906L11.715 0.906Q11.197 1.387 11.049 2.090L11.049 2.090Q10.864 1.942 10.827 1.646L10.827 1.646Q10.790 1.461 10.790 1.128L10.790 1.128L10.827 0.832L10.716 0.832Q10.642 0.832 10.586 0.888Q10.531 0.943 10.457 0.943L10.457 0.943Q9.606 1.646 9.421 2.571L9.421 2.571Q9.421 2.645 9.365 2.756Q9.310 2.867 9.310 2.904L9.310 2.904Q9.273 2.867 9.143 2.812Q9.014 2.756 8.977 2.682L8.977 2.682Q8.755 2.497 8.292 2.109Q7.830 1.720 7.571 1.535L7.571 1.535Q6.535 0.943 5.554 0.925Q4.574 0.906 3.538 1.424L3.538 1.424L2.613 2.349Q2.835 2.460 3.297 2.571Q3.760 2.682 3.982 2.793L3.982 2.793Q4.611 2.978 4.777 3.348Q4.944 3.718 4.685 4.421L4.685 4.421Q4.574 4.421 4.352 4.477Q4.130 4.532 3.982 4.532L3.982 4.532Q3.390 4.717 3.131 5.106Q2.872 5.494 2.946 6.049L2.946 6.049Q3.020 6.197 3.186 6.549Q3.353 6.900 3.427 7.085L3.427 7.085Q3.427 7.122 3.482 7.252Q3.538 7.381 3.538 7.418L3.538 7.418L3.538 8.602Q3.538 8.824 3.057 9.268L3.057 9.268L2.872 9.453Q2.465 9.823 2.391 10.082L2.391 10.082Q2.132 10.489 2.317 10.970Q2.502 11.451 2.946 11.821L2.946 11.821Q3.538 12.265 4.463 12.635L4.463 12.635Q5.388 13.079 5.388 14.004L5.388 14.004Q5.388 15.299 5.277 15.965L5.277 15.965Q5.277 16.076 5.203 16.372L5.203 16.372Q5.166 16.705 5.166 16.890L5.166 16.890Q4.574 16.446 4.259 15.984Q3.945 15.521 3.871 14.929L3.871 14.929Q2.835 15.817 2.835 16.779L2.835 16.779Q2.650 18.000 3.168 18.962L3.168 18.962Q3.723 19.998 5.055 20.479L5.055 20.479Q5.166 20.479 5.388 20.738L5.388 20.738Q6.424 22.440 8.496 22.810L8.496 22.810Q8.755 22.810 8.755 22.921L8.755 22.921Q9.643 23.476 10.642 23.661L10.642 23.661Q11.530 23.809 12.677 23.735L12.677 23.735Q13.417 23.624 13.787 23.513L13.787 23.513Q14.342 23.365 14.749 23.032L14.749 23.032Q14.823 22.995 14.989 22.921Q15.156 22.847 15.193 22.810L15.193 22.810Q17.117 22.477 18.227 20.849L18.227 20.849L18.560 20.479Q19.707 20.109 20.188 19.332L20.188 19.332Q20.595 18.777 20.743 18.000L20.743 18.000Q20.854 17.334 20.780 16.668L20.780 16.668Q20.669 16.187 20.428 15.799Q20.188 15.410 19.707 14.929L19.707 14.929Q19.559 15.558 19.263 16.021Q18.967 16.483 18.449 16.890L18.449 16.890Q18.338 15.854 18.338 13.893L18.338 13.893Q18.523 13.227 18.782 12.839Q19.041 12.450 19.485 12.265ZM14.971 18.407L9.791 18.407L14.971 18.407Z"/>',
 	'seti:gulp':

package/utils/head.ts

@@ -33,7 +33,9 @@ export function getHead(
 			attrs: { name: 'viewport', content: 'width=device-width, initial-scale=1' },
 		},
 		{ tag: 'title', content: `${data.title} ${config.titleDelimiter} ${siteTitle}` },
-		{ tag: 'link', attrs: { rel: 'canonical', href: canonicalHref } },
+		...(canonicalHref !== undefined
+			? ([{ tag: 'link', attrs: { rel: 'canonical', href: canonicalHref } }] as const)
+			: []),
 		{ tag: 'meta', attrs: { name: 'generator', content: context.generator } },
 		{
 			tag: 'meta',
@@ -51,9 +53,13 @@ export function getHead(
 		// OpenGraph Tags
 		{ tag: 'meta', attrs: { property: 'og:title', content: data.title } },
 		{ tag: 'meta', attrs: { property: 'og:type', content: 'article' } },
-		{ tag: 'meta', attrs: { property: 'og:url', content: canonicalHref } },
+		...(canonicalHref !== undefined
+			? ([{ tag: 'meta', attrs: { property: 'og:url', content: canonicalHref } }] as const)
+			: []),
 		{ tag: 'meta', attrs: { property: 'og:locale', content: lang } },
-		{ tag: 'meta', attrs: { property: 'og:description', content: description } },
+		...(description !== undefined
+			? ([{ tag: 'meta', attrs: { property: 'og:description', content: description } }] as const)
+			: []),
 		{ tag: 'meta', attrs: { property: 'og:site_name', content: siteTitle } },
 		// Twitter Tags
 		{

package/utils/i18n.ts

@@ -11,7 +11,7 @@ import type { StarlightConfig } from './user-config';
  */
 const wellKnownRTL = ['ar', 'fa', 'he', 'prs', 'ps', 'syc', 'ug', 'ur'];
 
-/** Informations about the built-in default locale used as a fallback when no locales are defined. */
+/** Information about the built-in default locale used as a fallback when no locales are defined. */
 export const BuiltInDefaultLocale = { ...getLocaleInfo('en'), lang: 'en' };
 
 /**
@@ -135,7 +135,7 @@ function getStarlightI18nConfig(
 	};
 }
 
-/** Infer Starlight locale informations based on a locale from an Astro i18n configuration. */
+/** Infer Starlight locale information based on a locale from an Astro i18n configuration. */
 function inferStarlightLocaleFromAstroLocale(astroLocale: AstroLocale) {
 	const lang = isAstroLocaleExtendedConfig(astroLocale) ? astroLocale.codes[0] : astroLocale;
 	return { ...getLocaleInfo(lang), lang };
@@ -159,7 +159,7 @@ function isAstroLocaleExtendedConfig(locale: AstroLocale): locale is AstroLocale
 	return typeof locale !== 'string';
 }
 
-/** Returns the locale informations such as a label and a direction based on a BCP-47 tag. */
+/** Returns the locale information such as a label and a direction based on a BCP-47 tag. */
 function getLocaleInfo(lang: string) {
 	try {
 		const locale = new Intl.Locale(lang);
@@ -171,7 +171,7 @@ function getLocaleInfo(lang: string) {
 		};
 	} catch {
 		throw new AstroError(
-			`Failed to get locale informations for the '${lang}' locale.`,
+			`Failed to get locale information for the '${lang}' locale.`,
 			'Make sure to provide a valid BCP-47 tags (e.g. en, ar, or zh-CN).'
 		);
 	}

package/utils/starlight-page.ts

@@ -44,7 +44,7 @@ const StarlightPageFrontmatterSchema = async (context: SchemaContext) => {
 		 * `pick`.
 		 *
 		 * This transformer only sets the `editUrl` default value and removes the `sidebar` property
-		 * from the validated output but does not appply any changes to the input schema type itself so
+		 * from the validated output but does not apply any changes to the input schema type itself so
 		 * this needs to be done manually.
 		 *
 		 * @see StarlightPageFrontmatter

package/utils/user-config.ts

@@ -163,7 +163,24 @@ const UserConfigSchema = z.object({
 	 *  customCss: ['/src/custom-styles.css', '@fontsource/roboto'],
 	 * })
 	 */
-	customCss: z.string().array().optional().default([]),
+	customCss: z
+		.string()
+		.array()
+		.optional()
+		.default([])
+		.superRefine((paths, ctx) => {
+			const invalidPathRegex = /^\.?\/public\/.+$/;
+			const invalidPaths = paths.filter((path) => invalidPathRegex.test(path));
+			if (invalidPaths.length > 0) {
+				ctx.addIssue({
+					code: 'custom',
+					message:
+						`These paths in your Starlight \`customCss\` config are invalid: ${invalidPaths.map((path) => `\`"${path}"\``).join(', ')}\n\n` +
+						`CSS files specified in \`customCss\` should be in the \`src/\` directory, not the \`public/\` directory.\n\n` +
+						`You should move these CSS files into the \`src/\` directory and update the path in \`customCss\` to match.`,
+				});
+			}
+		}),
 
 	/** Define if the last update date should be visible in the page footer. */
 	lastUpdated: z
@@ -255,6 +272,19 @@ const UserConfigSchema = z.object({
 				.describe(
 					'Define whether headings in content should be rendered with clickable anchor links. Default: `true`.'
 				),
+			/**
+			 * Define additional directories where files should be processed by Starlight’s Markdown pipeline.
+			 *
+			 * Supports local directories relative to the root of your project, e.g. './src/data/comments/'.
+			 * Content of the `docs` content collection is always processed by Starlight’s Markdown pipeline.
+			 */
+			processedDirs: z
+				.string()
+				.array()
+				.default([])
+				.describe(
+					'Define additional directories where files should be processed by Starlight’s Markdown pipeline. Default: `[]`.'
+				),
 		})
 		.default({})
 		.describe('Configure features that impact Starlight’s Markdown processing.'),

package/integrations/remark-rehype-utils.ts

@@ -1,38 +0,0 @@
-import type { AstroConfig } from 'astro';
-import type { VFile } from 'vfile';
-import { resolveCollectionPath } from '../utils/collection-fs';
-
-/**
- * Returns the path to the Starlight docs collection ready to be used in remark/rehype plugins,
- * e.g. with the `shouldTransformFile()` utility to determine if a file should be transformed
- * by a plugin or not.
- */
-export function getRemarkRehypeDocsCollectionPath(srcDir: AstroConfig['srcDir']) {
-	return normalizePath(resolveCollectionPath('docs', srcDir));
-}
-
-/**
- * Determines if a file should be transformed by a remark/rehype plugin, e.g. files without a known
- * path or files that are not part of the Starlight docs collection should be skipped.
- */
-export function shouldTransformFile(file: VFile, docsCollectionPath: string) {
-	// If the content is rendered using the content loader `renderMarkdown()` API, a file path
-	// is not provided.
-	// In that case, we skip the file.
-	if (!file?.path) return false;
-
-	// If the document is not part of the Starlight docs collection, skip it.
-	if (!normalizePath(file.path).startsWith(docsCollectionPath)) return false;
-
-	return true;
-}
-
-/**
- * File path separators seems to be inconsistent on Windows between remark/rehype plugins used on
- * Markdown vs MDX files.
- * For the time being, we normalize all paths to unix style paths.
- */
-const backSlashRegex = /\\/g;
-function normalizePath(path: string) {
-	return path.replace(backSlashRegex, '/');
-}