Merge branch 'main' into support-custom-icons

HiDeoo · HiDeoo · commit 84f8780bcbf6 · 2025-07-16T14:35:03.000+02:00
* main: Exclude banner content from Pagefind indexing (#3276) Restrict remark/rehype plugins usage (#3274) [ci] release (#3307) Fix Astro i18n default locale regression (#3306) i18n(de): translate `plugins.mdx` and `community-content.mdx` (#3304)
diff --git a/.changeset/moody-donkeys-applaud.md b/.changeset/moody-donkeys-applaud.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Prevents Starlight remark and rehype plugins from transforming Markdown and MDX content when using the Astro [`renderMarkdown()`](https://docs.astro.build/en/reference/content-loader-reference/#rendermarkdown) content loader API.
diff --git a/.changeset/smooth-pillows-decide.md b/.changeset/smooth-pillows-decide.md
@@ -0,0 +1,9 @@
+---
+'@astrojs/starlight': minor
+---
+
+Excludes banner content from search results
+
+Previously, content set in [`banner`](https://starlight.astro.build/reference/frontmatter/#banner) in page frontmatter was indexed by Starlight’s default search provider Pagefind. This could cause unexpected search results, especially for sites setting a common banner content on multiple pages. Starlight’s default `Banner` component is now excluded from search indexing.
+
+This change does not impact `Banner` overrides using custom components.
diff --git a/.changeset/unlucky-bananas-accept.md b/.changeset/unlucky-bananas-accept.md
@@ -0,0 +1,11 @@
+---
+'@astrojs/starlight': minor
+---
+
+Fixes an issue where some Starlight remark and rehype plugins were transforming Markdown and MDX content in non-Starlight pages.
+
+⚠️ **BREAKING CHANGE:**
+
+Previously, some of Starlight’s remark and rehype plugins, most notably the plugin transforming Starlight's custom Markdown syntax for [rendering asides](https://starlight.astro.build/guides/authoring-content/#asides), were applied to all Markdown and MDX content. This included content from [individual Markdown pages](https://docs.astro.build/en/guides/markdown-content/#individual-markdown-pages) and content from [content collections](https://docs.astro.build/en/guides/content-collections/) other than the `docs` collection used by Starlight.
+
+This change restricts the application of Starlight’s remark and rehype plugins to only Markdown and MDX content loaded using Starlight's [`docsLoader()`](https://starlight.astro.build/reference/configuration/#docsloader). If you were relying on this behavior, please let us know about your use case in the dedicated `#starlight` channel in the [Astro Discord](https://astro.build/chat/) or by [opening an issue](https://github.com/withastro/starlight/issues/new?template=---01-bug-report.yml).
diff --git a/docs/src/content/docs/de/resources/community-content.mdx b/docs/src/content/docs/de/resources/community-content.mdx
@@ -109,6 +109,11 @@ Erkunde die von der Community erstellten Inhalte, die von Starlight-Benutzern ge
 		title="Starlight Beispiele"
 		description="Eine Sammlung von StackBlitz-Einbettungen, die zeigen, wie man in Starlight-Dokumentations&shy;websites praktische Dinge tun kann."
 	/>
+	<LinkCard
+		href="https://hideoo.dev/notebooks/starlight-plugins-by-example"
+		title="Starlight-Plugins anhand von Beispielen"
+		description="Eine Sammlung von Notizen und Beispielen zu Starlight-Plugins und gängigen Mustern, die zum Erstellen dieser Plugins verwendet werden."
+	/>
 </CardGrid>
 
 ## Video-Inhalte
diff --git a/docs/src/content/docs/de/resources/plugins.mdx b/docs/src/content/docs/de/resources/plugins.mdx
@@ -222,4 +222,9 @@ Diese Community-Tools und Integrationen können verwendet werden, um deiner Star
 		title="astro-mermaid"
 		description="Rendere Mermaid-Inhalte in Markdown-Code-Blöcken auf der Client-Seite."
 	/>
+	<LinkCard
+		href="https://github.com/HiDeoo/astro-d2"
+		title="astro-d2"
+		description="D2 Markdown-Code-Blöcke in Diagramme umwandeln."
+	/>
 </CardGrid>
diff --git a/examples/basics/package.json b/examples/basics/package.json
@@ -11,7 +11,7 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@astrojs/starlight": "^0.34.7",
+    "@astrojs/starlight": "^0.34.8",
     "astro": "^5.6.1",
     "sharp": "^0.34.2"
   }
diff --git a/examples/markdoc/package.json b/examples/markdoc/package.json
@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@astrojs/markdoc": "^0.13.3",
-    "@astrojs/starlight": "^0.34.7",
+    "@astrojs/starlight": "^0.34.8",
     "@astrojs/starlight-markdoc": "^0.4.0",
     "astro": "^5.6.1",
     "sharp": "^0.34.2"
diff --git a/examples/tailwind/package.json b/examples/tailwind/package.json
@@ -11,7 +11,7 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@astrojs/starlight": "^0.34.7",
+    "@astrojs/starlight": "^0.34.8",
     "@astrojs/starlight-tailwind": "^4.0.1",
     "@tailwindcss/vite": "^4.0.7",
     "astro": "^5.6.1",
diff --git a/packages/starlight/CHANGELOG.md b/packages/starlight/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @astrojs/starlight
 
+## 0.34.8
+
+### Patch Changes
+
+- [#3306](https://github.com/withastro/starlight/pull/3306) [`21fcd94`](https://github.com/withastro/starlight/commit/21fcd944d528557b89fc8b351579beabdcc06ff6) Thanks [@HiDeoo](https://github.com/HiDeoo)! - Fixes a regression in Starlight version `0.34.5` that caused multilingual sites with a default locale explicitly set to `root` to report a configuration error.
+
 ## 0.34.7
 
 ### Patch Changes
diff --git a/packages/starlight/__e2e__/components.test.ts b/packages/starlight/__e2e__/components.test.ts
@@ -408,6 +408,41 @@ test.describe('anchor headings', () => {
 	});
 });
 
+test.describe('asides', () => {
+	test('does not render Markdown asides for individual Markdown pages and entries not part of the `docs` collection', async ({
+		getProdServer,
+		page,
+	}) => {
+		const starlight = await getProdServer();
+
+		// Individual Markdown page
+		await starlight.goto('/markdown-page');
+		await expect(page.locator('.starlight-aside')).not.toBeAttached();
+		await page.pause();
+
+		// Content entry from the `reviews` content collection
+		await starlight.goto('/reviews/alice');
+		await expect(page.locator('.starlight-aside')).not.toBeAttached();
+	});
+});
+
+test.describe('RTL support', () => {
+	test('does not add RTL support to code and preformatted text elements for individual Markdown pages and entries not part of the `docs` collection', async ({
+		getProdServer,
+		page,
+	}) => {
+		const starlight = await getProdServer();
+
+		// Individual Markdown page
+		await starlight.goto('/markdown-page');
+		await expect(page.locator('code[dir="auto"]')).not.toBeAttached();
+
+		// Content entry from the `reviews` content collection
+		await starlight.goto('/reviews/alice');
+		await expect(page.locator('code[dir="auto"]')).not.toBeAttached();
+	});
+});
+
 test.describe('head propagation', () => {
 	/**
 	 * Due to a head propagation issue in development mode, dynamic routes alphabetically sorted
diff --git a/packages/starlight/__e2e__/fixtures/basics/src/content/reviews/alice.mdx b/packages/starlight/__e2e__/fixtures/basics/src/content/reviews/alice.mdx
@@ -9,4 +9,10 @@ This is a review from Alice.
 ## Description
 
 This content collection entry is not part of the Starlight `docs` collection.
-It is used to test that anchor links for headings are not generated for non-docs collection entries.
+It is used to test that various remark/rehype plugins are not transforming non-docs collection entries.
+
+:::note
+This is a note using Starlight Markdown aside syntax.
+:::
+
+This is an `inline code` example.
diff --git a/packages/starlight/__e2e__/fixtures/basics/src/pages/markdown-page.md b/packages/starlight/__e2e__/fixtures/basics/src/pages/markdown-page.md
@@ -7,4 +7,10 @@ title: Individual Markdown Page
 ## Description
 
 This page is an [individual Markdown page](https://docs.astro.build/en/guides/markdown-content/#individual-markdown-pages).
-It is used to test that anchor links for headings are not generated for individual Markdown pages.
+It is used to test that various remark/rehype plugins are not transforming individual Markdown pages.
+
+:::note
+This is a note using Starlight Markdown aside syntax.
+:::
+
+This is an `inline code` example.
diff --git a/packages/starlight/__tests__/i18n-root-default-locale/i18n.test.ts b/packages/starlight/__tests__/i18n-root-default-locale/i18n.test.ts
@@ -0,0 +1,39 @@
+import { assert, describe, expect, test } from 'vitest';
+import config from 'virtual:starlight/user-config';
+import { processI18nConfig } from '../../utils/i18n';
+
+describe('processI18nConfig', () => {
+	test('returns Astro i18n config for a multilingual site with a root default locale', () => {
+		const { astroI18nConfig, starlightConfig } = processI18nConfig(config, undefined);
+
+		// The default locale matches the root locale's `lang` property.
+		expect(astroI18nConfig.defaultLocale).toBe('fr');
+		expect(astroI18nConfig.locales).toMatchInlineSnapshot(`
+			[
+			  {
+			    "codes": [
+			      "fr",
+			    ],
+			    "path": "fr",
+			  },
+			  {
+			    "codes": [
+			      "en-US",
+			    ],
+			    "path": "en",
+			  },
+			  {
+			    "codes": [
+			      "ar",
+			    ],
+			    "path": "ar",
+			  },
+			]
+		`);
+		assert(typeof astroI18nConfig.routing !== 'string');
+		expect(astroI18nConfig.routing?.prefixDefaultLocale).toBe(false);
+
+		// The Starlight configuration should not be modified.
+		expect(config).toStrictEqual(starlightConfig);
+	});
+});
diff --git a/packages/starlight/__tests__/i18n-root-default-locale/vitest.config.ts b/packages/starlight/__tests__/i18n-root-default-locale/vitest.config.ts
@@ -0,0 +1,11 @@
+import { defineVitestConfig } from '../test-config';
+
+export default defineVitestConfig({
+	title: 'i18n with root default locale',
+	defaultLocale: 'root',
+	locales: {
+		root: { label: 'French', lang: 'fr' },
+		en: { label: 'English', lang: 'en-US' },
+		ar: { label: 'Arabic', dir: 'rtl' },
+	},
+});
diff --git a/packages/starlight/__tests__/remark-rehype/anchor-links.test.ts b/packages/starlight/__tests__/remark-rehype/anchor-links.test.ts
@@ -86,3 +86,16 @@ test('localizes accessible label for the current language', async () => {
 	);
 	expect(res.code).includes('<span class="sr-only">Section intitulée « Some text »</span>');
 });
+
+test('does not generate anchor links for documents without a file path', async () => {
+	const res = await processor.render(
+		`
+## Some text
+`,
+		// Rendering Markdown content using the content loader `renderMarkdown()` API does not provide
+		// a `fileURL` option.
+		{}
+	);
+
+	expect(res.code).not.includes('Section titled');
+});
diff --git a/packages/starlight/__tests__/remark-rehype/asides.test.ts b/packages/starlight/__tests__/remark-rehype/asides.test.ts
@@ -408,3 +408,19 @@ test('does not transform back directive nodes with data', async () => {
 		`"<p>This method is available in the <span class="api">thing</span> API.</p>"`
 	);
 });
+
+test('does not generate asides for documents without a file path', async () => {
+	const res = await processor.render(
+		`
+:::note
+Some text
+:::
+`,
+		// Rendering Markdown content using the content loader `renderMarkdown()` API does not provide
+		// a `fileURL` option.
+		{}
+	);
+
+	expect(res.code).not.includes(`aside`);
+	expect(res.code).not.includes(`</svg>Note</p>`);
+});
diff --git a/packages/starlight/__tests__/remark-rehype/code-rtl-support.test.ts b/packages/starlight/__tests__/remark-rehype/code-rtl-support.test.ts
@@ -1,12 +1,29 @@
 import { rehype } from 'rehype';
+import { VFile } from 'vfile';
 import { expect, test } from 'vitest';
 import { rehypeRtlCodeSupport } from '../../integrations/code-rtl-support';
 
-const processor = rehype().data('settings', { fragment: true }).use(rehypeRtlCodeSupport());
+const astroConfig = {
+	root: new URL(import.meta.url),
+	srcDir: new URL('./_src/', import.meta.url),
+};
+
+const processor = rehype()
+	.data('settings', { fragment: true })
+	.use(rehypeRtlCodeSupport({ astroConfig }));
+
+function renderMarkdown(content: string, options: { fileURL?: URL } = {}) {
+	return processor.process(
+		new VFile({
+			path: options.fileURL ?? new URL(`./_src/content/docs/index.md`, import.meta.url),
+			value: content,
+		})
+	);
+}
 
 test('applies `dir="auto"` to inline code', async () => {
 	const input = `<p>Some text with <code>inline code</code>.</p>`;
-	const output = String(await processor.process(input));
+	const output = String(await renderMarkdown(input));
 	expect(output).not.toEqual(input);
 	expect(output).includes('dir="auto"');
 	expect(output).toMatchInlineSnapshot(
@@ -16,10 +33,24 @@ test('applies `dir="auto"` to inline code', async () => {
 
 test('applies `dir="ltr"` to code blocks', async () => {
 	const input = `<p>Some text in a paragraph:</p><pre><code>console.log('test')</code></pre>`;
-	const output = String(await processor.process(input));
+	const output = String(await renderMarkdown(input));
 	expect(output).not.toEqual(input);
 	expect(output).includes('dir="ltr"');
 	expect(output).toMatchInlineSnapshot(
 		`"<p>Some text in a paragraph:</p><pre dir="ltr"><code>console.log('test')</code></pre>"`
 	);
 });
+
+test('does not transform documents without a file path', async () => {
+	const input = `<p>Some text with <code>inline code</code>.</p>`;
+	const output = String(
+		await processor.process(
+			new VFile({
+				// Rendering Markdown content using the content loader `renderMarkdown()` API does not
+				// provide a `path` option.
+				value: input,
+			})
+		)
+	);
+	expect(output).toEqual(input);
+});
diff --git a/packages/starlight/components/Banner.astro b/packages/starlight/components/Banner.astro
@@ -2,7 +2,7 @@
 const { banner } = Astro.locals.starlightRoute.entry.data;
 ---
 
-{banner && <div class="sl-banner" set:html={banner.content} />}
+{banner && <div class="sl-banner" data-pagefind-ignore set:html={banner.content} />}
 
 <style>
 	@layer starlight.core {
diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
@@ -129,7 +129,7 @@ export default function StarlightIntegration(
 							}),
 						],
 						rehypePlugins: [
-							rehypeRtlCodeSupport(),
+							rehypeRtlCodeSupport({ astroConfig: config }),
 							// Process headings and add anchor links.
 							...starlightAutolinkHeadings({
 								starlightConfig,
diff --git a/packages/starlight/integrations/asides.ts b/packages/starlight/integrations/asides.ts
@@ -15,6 +15,7 @@ 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 { Icons } from '../components/Icons';
 import { fromHtml } from 'hast-util-from-html';
 import type { Element } from 'hast';
@@ -166,7 +167,11 @@ 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) => {
diff --git a/packages/starlight/integrations/code-rtl-support.ts b/packages/starlight/integrations/code-rtl-support.ts
@@ -1,5 +1,12 @@
+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'>;
+}
 
 /**
  * rehype plugin that adds `dir` attributes to `<code>` and `<pre>`
@@ -15,8 +22,12 @@ import { CONTINUE, SKIP, visit } from 'unist-util-visit';
  * - `<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() {
-	return () => (root: Root) => {
+export function rehypeRtlCodeSupport({ astroConfig }: RtlCodeSupportOptions) {
+	const docsCollectionPath = getRemarkRehypeDocsCollectionPath(astroConfig.srcDir);
+
+	return () => (root: Root, file: VFile) => {
+		if (!shouldTransformFile(file, docsCollectionPath)) return;
+
 		visit(root, 'element', (el) => {
 			if (el.tagName === 'pre' || el.tagName === 'code') {
 				el.properties ||= {};
diff --git a/packages/starlight/integrations/heading-links.ts b/packages/starlight/integrations/heading-links.ts
diff --git a/packages/starlight/integrations/remark-rehype-utils.ts b/packages/starlight/integrations/remark-rehype-utils.ts
diff --git a/packages/starlight/package.json b/packages/starlight/package.json
diff --git a/packages/starlight/utils/i18n.ts b/packages/starlight/utils/i18n.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@astrojs/starlight': patch
 +---
++
 +Prevents Starlight remark and rehype plugins from transforming Markdown and MDX content when using the Astro [`renderMarkdown()`](https://docs.astro.build/en/reference/content-loader-reference/#rendermarkdown) content loader API.
Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@`
`11`	`11`	`"astro": "astro"`
`12`	`12`	`},`
`13`	`13`	`"dependencies": {`
`14`		`- "@astrojs/starlight": "^0.34.7",`
	`14`	`+ "@astrojs/starlight": "^0.34.8",`
`15`	`15`	`"astro": "^5.6.1",`
`16`	`16`	`"sharp": "^0.34.2"`
`17`	`17`	`}`