Merge branch 'main' into hd-feat-cascade-layers

* main: (493 commits)
  i18n(de): update `sidebar.mdx` (withastro#2900)
  Adding all samples for badges in sidebar as example (withastro#2881)
  i18n(fr): fix highlighting in `reference/plugins.md` (withastro#2898)
  i18n(fr): update `reference/plugins` & `guides/i18n` (withastro#2886)
  i18n(fr): update `reference/overrides` & `guides/sidebar` (withastro#2887)
  i18n(fr): add `guides/route-data` and `reference/route-data` (withastro#2884)
  i18n(fr): update `guides/overriding-components` (withastro#2885)
  i18n(fr): update `reference/configuration` (withastro#2888)
  i18n(de): update German translation with withastro#2578 (withastro#2882)
  [ci] format
  i18n(ru): update some translations (withastro#2895)
  i18n(de): update `reference/configuration.mdx` (withastro#2883)
  [ci] format
  i18n(ko-KR): update `configuration.mdx` (withastro#2892)
  i18n(ko-KR): update `overrides.md` (withastro#2893)
  i18n(ko-KR): update `overriding-components.mdx` (withastro#2890)
  i18n(ko-KR): update `i18n.mdx` and `plugins.md` (withastro#2889)
  [ci] format
  i18n(ko-KR): create `guides/route-data.mdx` and `reference/route-data.mdx` (withastro#2896)
  i18n(ko-KR): update `/resources/plugins.mdx` (withastro#2894)
  ...

.github/DISCUSSION_TEMPLATE/docs-suggestions.yml

@@ -0,0 +1,39 @@
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for getting in touch! Please fill out this form as completely as possible.
+
+        Want to report a problem with the Starlight docs? [Open a new issue](https://github.com/withastro/starlight/issues/new?assignees=&labels=&projects=&template=---02-docs-issue.yml)
+        Want to chat before posting? [Join us in the `#starlight` channel on Discord](https://astro.build/chat)
+  - type: textarea
+    id: summary
+    attributes:
+      label: What is your idea?
+      description: A brief, one or two sentence description of your idea for how to improve the Starlight docs.
+    validations:
+      required: true
+  - type: textarea
+    id: background
+    attributes:
+      label: Why is this important?
+      description: Explain why this idea is valuable. What problems would it solve? Which users would it help?
+    validations:
+      required: true
+  - type: textarea
+    id: prior-art
+    attributes:
+      label: How does your idea relate to existing docs content?
+      description: Are there specific pages you would like to change? Or existing pages that are related to your proposal?
+      placeholder: |
+        - Example
+        - Example
+        - Example
+  - type: checkboxes
+    id: will-pr
+    attributes:
+      label: Participation
+      description: Let us know if your interested in contributing this feature yourself.
+      options:
+        - label: I am willing to submit a pull request for this feature.
+          required: false

.github/ISSUE_TEMPLATE/---02-docs-issue.yml

@@ -0,0 +1,45 @@
+name: "\U0001F4DA Docs Issue"
+description: Report an issue with the Starlight documentation
+labels: []
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to let us know something is wrong! Please fill out this form as completely as possible.
+  - type: input
+    id: docs-page
+    attributes:
+      label: What page of the docs did you find an issue on?
+      description: If this issue applies to multiple pages, include additional pages in your bug description.
+      placeholder: https://starlight.astro.build/...
+    validations:
+      required: true
+  - type: textarea
+    id: bug-description
+    attributes:
+      label: Describe the issue
+      description: A clear and concise description of what the issue is.
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: What operating system are you using?
+      placeholder: Mac, Windows, Linux
+    validations:
+      required: true
+  - type: input
+    id: browser
+    attributes:
+      label: What browser are you using?
+      placeholder: Chrome, Firefox, Safari
+    validations:
+      required: true
+  - type: checkboxes
+    id: will-pr
+    attributes:
+      label: Participation
+      options:
+        - label: I am willing to submit a pull request for this issue.
+          required: false

.github/labeler.yml

@@ -26,6 +26,9 @@ i18n:
 '🌟 tailwind':
   - packages/tailwind/**
 
+'🌟 docsearch':
+  - packages/docsearch/**
+
 '🌟 markdoc':
   - packages/markdoc/**
 

.github/workflows/ci.yml

@@ -50,6 +50,9 @@ jobs:
       - run: pnpm i
       - name: Test packages
         run: pnpm -r test:coverage
+      - name: Test legacy collections support
+        working-directory: packages/starlight
+        run: pnpm test:legacy
 
   e2e-test:
     name: 'Run E2E tests (${{ matrix.os }})'
@@ -88,7 +91,7 @@ jobs:
       - name: Type check packages
         run: pnpm typecheck
 
-  pa11y:
+  a11y:
     name: Check for accessibility issues
     runs-on: ubuntu-latest
     steps:
@@ -107,12 +110,6 @@ jobs:
       - name: Install Dependencies
         run: pnpm i
 
-      - name: Build docs site
-        working-directory: ./docs
-        run: pnpm build
-        env:
-          NO_GRADIENTS: true
-
       - name: Run accessibility audit
         working-directory: ./docs
         run: pnpm t
@@ -155,6 +152,4 @@ jobs:
 
       - name: Build docs site and check links
         working-directory: ./docs
-        run: pnpm build
-        env:
-          CHECK_LINKS: true
+        run: pnpm linkcheck

.github/workflows/release.yml

@@ -10,6 +10,9 @@ jobs:
     name: Release
     if: ${{ github.repository_owner == 'withastro' }}
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
     steps:
       - name: Checkout Repo
         uses: actions/checkout@v4

.gitignore

@@ -22,6 +22,3 @@ test-results/
 
 # Vercel output
 .vercel
-
-# Created by @astrojs/check
-/src/

.npmrc

@@ -1,3 +1,4 @@
 prefer-workspace-packages=true
 link-workspace-packages=true
 shell-emulator=true
+auto-install-peers=false

.prettierignore

@@ -17,3 +17,6 @@ pnpm-lock.yaml
 
 # https://github.com/withastro/prettier-plugin-astro/issues/337
 packages/starlight/user-components/Tabs.astro
+
+# Malformed YAML file used for testing
+packages/starlight/__tests__/i18n/malformed-yaml-src/content/i18n/*.yml

CONTRIBUTING.md

@@ -121,11 +121,11 @@ You should then be able to open <http://localhost:4321> and see your changes.
 When adding or translating content in the Starlight docs site, you can check all internal links are valid.
 All GitHub PRs are checked this way automatically, but testing locally can help if you want to confirm changes are correct before committing them.
 
-To do this, move into the `docs/` directory from the root of the repo and then build the site with the `CHECK_LINKS` environment variable:
+To do this, move into the `docs/` directory from the root of the repo and then run `pnpm linkcheck`:
 
 ```sh
 cd docs
-CHECK_LINKS=true pnpm build
+pnpm linkcheck
 ```
 
 If there are any broken links, the build will fail and log which pages need to be fixed.
@@ -200,7 +200,7 @@ pnpm test:e2e
 
 #### Test fixtures
 
-Each subdirectory of `packages/starlight/__e2e__/fixtures` should contain the basic files needed to run Starlight (`package.json`, `astro.config.mjs`, a content collection configuration in `src/content/config.ts` and some content to render in `src/content/docs/`).
+Each subdirectory of `packages/starlight/__e2e__/fixtures` should contain the basic files needed to run Starlight (`package.json`, `astro.config.mjs`, a content collection configuration in `src/content.config.ts` and some content to render in `src/content/docs/`).
 
 The `testFactory()` helper can be used in a test file to define the fixture which will be built and loaded in a preview server during a set of tests.
 
@@ -251,7 +251,7 @@ To add a language, you will need its BCP-47 tag and a label. See [“Adding a ne
 - Add your language to the `locales` config in `docs/astro.config.mjs`
 - Add your language to the `locales` config in `docs/lunaria.config.json`
 - Add your language’s subtag to the i18n label config in `.github/labeler.yml`
-- Add your language to the `pa11y` script’s `--sitemap-exclude` flag in `package.json`
+- Add your language to the `config.sitemap.exclude` option in `docs/__a11y__/test-utils.ts`
 - Create the first translated page for your language.
   This must be the Starlight landing page: `docs/src/content/docs/{language}/index.mdx`.
 - Open a pull request on GitHub to add your changes to Starlight!

docs/__a11y__/docs.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from './test-utils';
+
+test('does not report accessibility violations on the docs site', async ({ docsSite }) => {
+	let violationsCount = 0;
+
+	const urls = await docsSite.getAllUrls();
+
+	for (const url of urls) {
+		const violations = await docsSite.testPage(url);
+
+		if (violations.length > 0) {
+			violationsCount += violations.length;
+		}
+
+		await docsSite.reportPageViolations(violations);
+	}
+
+	expect(
+		violationsCount,
+		`Found ${violationsCount} accessibility violations. Check the errors above for more details.`
+	).toBe(0);
+});

docs/__a11y__/test-utils.ts

@@ -0,0 +1,155 @@
+import { test as baseTest, type Page } from '@playwright/test';
+import {
+	DefaultTerminalReporter,
+	getViolations,
+	injectAxe,
+	reportViolations,
+} from 'axe-playwright';
+import Sitemapper from 'sitemapper';
+
+export { expect, type Locator } from '@playwright/test';
+
+const config: Config = {
+	axe: {
+		// https://www.deque.com/axe/core-documentation/api-documentation/#axecore-tags
+		runOnly: {
+			type: 'tag',
+			values: ['wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'wcag22aa', 'best-practice'],
+		},
+	},
+	// A list of violation to ignore.
+	ignore: [{ id: 'landmark-unique', nodeMatcher: landmarkUniqueNodeMatcher }],
+	sitemap: {
+		url: 'http://localhost:4321/sitemap-index.xml',
+		exclude: {
+			// A pattern to exclude URLs from the sitemap.
+			pattern: /\/(de|zh-cn|fr|es|pt-br|pt-pt|it|id|ko|ru|tr|hi|da|uk)\/.*/,
+			// A list of slugs to exclude from the sitemap after processing the pattern.
+			slugs: [
+				'components/using-components',
+				'getting-started',
+				'guides/customization',
+				'guides/i18n',
+				'guides/overriding-components',
+				'guides/pages',
+				'guides/project-structure',
+				'guides/site-search',
+				'manual-setup',
+				'reference/frontmatter',
+				'reference/overrides',
+				'reference/plugins',
+			],
+		},
+		replace: {
+			query: 'https://starlight.astro.build',
+			value: 'http://localhost:4321',
+		},
+	},
+};
+
+process.env.ASTRO_TELEMETRY_DISABLED = 'true';
+process.env.ASTRO_DISABLE_UPDATE_CHECK = 'true';
+
+export const test = baseTest.extend<{
+	docsSite: DocsSite;
+}>({
+	docsSite: async ({ page }, use) => use(new DocsSite(page)),
+});
+
+// A Playwright test fixture accessible from within all tests.
+class DocsSite {
+	constructor(private readonly page: Page) {}
+
+	async getAllUrls() {
+		const sitemap = new Sitemapper({ url: config.sitemap.url });
+		const { sites } = await sitemap.fetch();
+
+		if (sites.length === 0) {
+			throw new Error('No URLs found in sitemap.');
+		}
+
+		const urls: string[] = [];
+
+		for (const site of sites) {
+			const url = site.replace(config.sitemap.replace.query, config.sitemap.replace.value);
+			if (config.sitemap.exclude.pattern.test(url)) continue;
+			if (config.sitemap.exclude.slugs.some((slug) => url.endsWith(`/${slug}/`))) continue;
+			urls.push(url);
+		}
+
+		return urls;
+	}
+
+	async testPage(url: string) {
+		await this.page.goto(url);
+		await injectAxe(this.page);
+		await this.page.waitForLoadState('networkidle');
+		const violations = await getViolations(this.page, undefined, config.axe);
+		return this.#filterViolations(violations);
+	}
+
+	async reportPageViolations(violations: Awaited<ReturnType<typeof this.testPage>>) {
+		const url = this.page.url().replace(config.sitemap.replace.value, '');
+
+		if (violations.length > 0) {
+			console.error(`> Found ${violations.length} violations on ${url}\n`);
+			await reportViolations(violations, new DefaultTerminalReporter(true, true, false));
+			console.error('\n');
+		} else {
+			console.log(`> Found no violations on ${url}`);
+		}
+	}
+
+	#filterViolations(violations: Awaited<ReturnType<typeof getViolations>>) {
+		return violations.filter((violation) => {
+			return !config.ignore.some((ignore) => {
+				if (typeof ignore === 'string') return violation.id === ignore;
+				if (violation.id !== ignore.id) return false;
+				if (!ignore.nodeMatcher) return true;
+				return !violation.nodes.some(ignore.nodeMatcher);
+			});
+		});
+	}
+}
+
+function landmarkUniqueNodeMatcher(node: ViolationNode) {
+	/**
+	 * Ignore the `landmark-unique` violation only if the node HTML is an aside.
+	 *
+	 * The best action to fix this violation would be to remove the landmark altogether as it's not
+	 * necessary in this case and switch to the `note` role. Although, this is not possible at the
+	 * moment due to an issue with NVDA not announcing it and also skipping the associated label for
+	 * a role not supported.
+	 *
+	 * @see https://github.com/nvaccess/nvda/issues/10439
+	 * @see https://github.com/withastro/starlight/pull/2503
+	 */
+	return !/^<aside[^>]* class="starlight-aside[^>]*>$/.test(node.html);
+}
+
+interface Config {
+	axe: Parameters<typeof getViolations>[2];
+	ignore: Array<
+		| string
+		| {
+				id: string;
+				// A function called for each node to evaluate if it should be ignored or not.
+				// Return `true` if the node should be considered for the violation, `false` otherwise.
+				nodeMatcher?: (node: ViolationNode) => boolean;
+		  }
+	>;
+	sitemap: {
+		url: string;
+		exclude: {
+			pattern: RegExp;
+			slugs: string[];
+		};
+		replace: {
+			query: string;
+			value: string;
+		};
+	};
+}
+
+type Violations = Awaited<ReturnType<typeof getViolations>>;
+type ViolationNode = Violations[number]['nodes'][number];