Astro 6 support

.changeset/agile-eyes-fold.md

@@ -0,0 +1,27 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds support for Astro v6, drops support for Astro v5.
+
+#### Upgrade Astro and dependencies
+
+⚠️ **BREAKING CHANGE:** Astro v5 is no longer supported. Make sure you [update Astro](https://docs.astro.build/en/guides/upgrade-to/v6/) and any other official integrations at the same time as updating Starlight:
+
+```sh
+npx @astrojs/upgrade
+```
+
+_Community Starlight plugins and Astro integrations may also need to be manually updated to work with Astro v6. If you encounter any issues, please reach out to the plugin or integration author to see if it is a known issue or if an updated version is being worked on._
+
+#### Update your collections
+
+⚠️ **BREAKING CHANGE:** Drops support for content collections backwards compatibility.
+
+In Astro 5.x, projects could delay upgrading to the new Content Layer API introduced for content collections because of some existing automatic backwards compatibility that was not previously behind a flag. This meant that it was possible to upgrade from Astro 4 to Astro 5 without updating your content collections, even if you had not enabled the `legacy.collections` flag. Projects would continue to build, and no errors or warnings would be displayed.
+
+Astro v6.0 now removes this automatic legacy content collections support, along with the `legacy.collections` flag.
+
+If you experience content collections errors after updating to v6, [check your project for any removed legacy features](https://docs.astro.build/en/guides/upgrade-to/v6/#if-you-have) that may need updating to the Content Layer API. See [the Starlight v0.30.0 upgrade guide](https://github.com/withastro/starlight/blob/main/packages/starlight/CHANGELOG.md#0300) for detailed instructions on upgrading legacy collections to the new Content Layer API.
+
+If you are unable to make any changes to your collections at this time, including Starlight's default `docs` and `i18n` collections, you can enable the [`legacy.collectionsBackwardsCompat` flag](https://docs.astro.build/en/reference/legacy-flags/#collectionsbackwardscompat) to upgrade to v6 without updating your collections. This temporary flag preserves some legacy v4 content collections features, and will allow you to keep your collections in their current state until the legacy flag is no longer supported.

.changeset/dry-bikes-beg.md

@@ -0,0 +1,11 @@
+---
+'@astrojs/starlight-markdoc': minor
+---
+
+⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now 0.38.0
+
+Please use the `@astrojs/upgrade` command to upgrade your project:
+
+```sh
+npx @astrojs/upgrade
+```

.changeset/hot-dryers-drop.md

@@ -0,0 +1,11 @@
+---
+'@astrojs/starlight-tailwind': major
+---
+
+⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now 0.38.0
+
+Please use the `@astrojs/upgrade` command to upgrade your project:
+
+```sh
+npx @astrojs/upgrade
+```

.changeset/spicy-moons-sell.md

@@ -0,0 +1,12 @@
+---
+'@astrojs/starlight-docsearch': minor
+---
+
+⚠️ **BREAKING CHANGE:** The minimum supported version of Starlight is now 0.38.0
+
+Please use the `@astrojs/upgrade` command to upgrade your project:
+
+```sh
+npx @astrojs/upgrade
+```
+

.devcontainer/Dockerfile

@@ -1,5 +1,5 @@
 # Based on https://github.com/withastro/astro/blob/main/.devcontainer/Dockerfile
-FROM mcr.microsoft.com/devcontainers/javascript-node:0-18
+FROM mcr.microsoft.com/devcontainers/javascript-node:0-22
 
 # We uninstall pnpm here, since we enable the corepack version in the postCreateCommand
 # This ensures we respect the "packageManager" version in package.json

.github/ISSUE_TEMPLATE/---01-bug-report.yml

@@ -9,7 +9,7 @@ body:
         Thank you for taking the time to file a bug report! Please fill out this form as completely as possible.
 
         ✅ I am using the **latest versions of Starlight and Astro**.
-        ✅ I am using a version of Node that supports ESM (`v14.18.0+`, or `v16.12.0+`).
+        ✅ I am using a compatible version of Node.js (`v22.12.0+`).
   - type: input
     id: starlight-version
     attributes:

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  NODE_VERSION: 18
+  NODE_VERSION: 22
   ASTRO_TELEMETRY_DISABLED: true
 
 jobs:
@@ -69,9 +69,6 @@ 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 }})'

.github/workflows/file-icons.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
-          node-version: 18.20.8
+          node-version: 22.12.0
           cache: 'pnpm'
 
       - name: Install Dependencies

.github/workflows/format.yml

@@ -18,7 +18,7 @@ jobs:
       - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
       - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
-          node-version: 18.20.8
+          node-version: 22.12.0
           cache: 'pnpm'
       - run: pnpm i
       - name: Format with Prettier

.github/workflows/lunaria.yml

@@ -32,7 +32,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
-          node-version: 20.19.4
+          node-version: 22.12.0
           cache: pnpm
 
       - name: Install dependencies

.github/workflows/size-limit.yml

@@ -9,6 +9,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event_name == 'pull_request_target' && github.head_ref || github.ref }}
   cancel-in-progress: true
 
+env:
+  NODE_VERSION: 22
+
 jobs:
   # This basic check runs size-limit for the current branch.
   # It will fail if the branch pushes the size over the specified budget.
@@ -19,6 +22,11 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+      - name: Setup Node
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
       - run: pnpm i
       - run: 'pnpm build:examples'
       - run: pnpm size
@@ -32,6 +40,11 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4.2.0
+      - name: Setup Node
+        uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
       - name: Run size-limit
         uses: andresz1/size-limit-action@94bc357df29c36c8f8d50ea497c3e225c3c95d1d # v1.8.0
         with:

docs/__a11y__/test-utils.ts

@@ -9,7 +9,7 @@ import Sitemapper from 'sitemapper';
 
 // We use the Lunaria config to get the list of languages rather than the Astro config as importing
 // the latter does not play well with Playwright.
-import lunariaConfig from '../lunaria.config.json' assert { type: 'json' };
+import lunariaConfig from '../lunaria.config.json' with { type: 'json' };
 
 export { expect, type Locator } from '@playwright/test';
 
@@ -72,7 +72,11 @@ export const test = baseTest.extend<{
 
 // A Playwright test fixture accessible from within all tests.
 class DocsSite {
-	constructor(private readonly page: Page) {}
+	private readonly page: Page;
+
+	constructor(page: Page) {
+		this.page = page;
+	}
 
 	async getAllUrls() {
 		const sitemap = new Sitemapper({ url: config.sitemap.url });
@@ -142,18 +146,29 @@ class DocsSite {
 }
 
 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);
+	// Ignore some `landmark-unique` violations.
+	return (
+		/**
+		 * Asides: 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
+		 */
+		!/^<aside[^>]* class="starlight-aside[^>]*>$/.test(node.html) &&
+		/**
+		 * Expressive Code `<pre>` blocks: EC 0.41.3 introduced a change adding the `region` role to
+		 * scrollable code blocks. The best action to fix this violation would potentially to switch to
+		 * another role, e.g. `group`, and adding `aria-label` or `aria-labelledby` to provide a generic
+		 * label, e.g. `'Horizontally scrollable code'`.
+		 *
+		 * @see https://github.com/expressive-code/expressive-code/pull/343
+		 * @see https://github.com/expressive-code/expressive-code/pull/348
+		 */
+		!/^<pre[^>]* data-language[^>]* role="region"[^>]*>$/.test(node.html)
+	);
 }
 
 interface Config {

docs/package.json

@@ -16,16 +16,16 @@
     "grammars": "node grammars/generate.mjs"
   },
   "dependencies": {
-    "@astro-community/astro-embed-youtube": "^0.5.6",
+    "@astro-community/astro-embed-youtube": "^0.5.10",
     "@astrojs/starlight": "workspace:*",
     "@lunariajs/core": "^0.1.1",
     "@types/culori": "^2.1.1",
-    "astro": "^5.6.1",
+    "astro": "^6.0.1",
     "culori": "^4.0.1",
     "sharp": "^0.34.2"
   },
   "devDependencies": {
-    "@playwright/test": "^1.45.0",
+    "@playwright/test": "^1.57.0",
     "axe-playwright": "^2.0.3",
     "sitemapper": "^3.2.12",
     "starlight-links-validator": "^0.14.0"

docs/src/content.config.ts

@@ -1,4 +1,5 @@
-import { defineCollection, z } from 'astro:content';
+import { defineCollection } from 'astro:content';
+import { z } from 'astro/zod';
 import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
 import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
 

docs/src/content/docs/guides/i18n.mdx

@@ -259,7 +259,8 @@ In the following example, a new, optional `custom.label` key is added to the def
 
 ```diff lang="js"
 // src/content.config.ts
-import { defineCollection, z } from 'astro:content';
+import { defineCollection } from 'astro:content';
+import { z } from 'astro/zod';
 import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
 import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
 

docs/src/content/docs/guides/sidebar.mdx

@@ -191,7 +191,7 @@ The configuration above generates the following sidebar:
 Starlight can automatically generate a group in your sidebar based on a directory of your docs.
 This is helpful when you do not want to manually enter each sidebar item in a group.
 
-By default, pages are sorted in alphabetical order according to the file [`slug`](/reference/route-data/#slug).
+By default, pages are sorted in alphabetical order according to the file [`id`](/reference/route-data/#id).
 
 Add an autogenerated group using an object with `label` and `autogenerate` properties. Your `autogenerate` configuration must specify the `directory` to use for sidebar entries. For example, with the following configuration:
 

docs/src/content/docs/manual-setup.mdx

@@ -77,8 +77,8 @@ export const collections = {
 };
 ```
 
-Starlight also supports the [`legacy.collections` flag](https://docs.astro.build/en/reference/legacy-flags/) where collections are handled using the legacy content collections implementation.
-This is useful if you have an existing Astro project and are unable to make any changes to collections at this time to use a loader.
+Starlight also supports the [`legacy.collectionsBackwardsCompat` flag](https://docs.astro.build/en/reference/legacy-flags/#collectionsbackwardscompat) which preserves some legacy v4 content collections features.
+This is useful if you have an existing Astro project and are unable to make any changes to collections at this time to migrate to the Content Layer API introduced in v5.0.
 
 ### Add content
 
@@ -132,3 +132,5 @@ In the future, we plan to support this use case better to avoid the need for the
 To enable SSR, follow the [“On-demand Rendering Adapters”](https://docs.astro.build/en/guides/on-demand-rendering/) guide in Astro’s docs to add a server adapter to your Starlight project.
 
 Documentation pages generated by Starlight are pre-rendered by default regardless of your project's output mode. To opt out of pre-rendering your Starlight pages, set the [`prerender` config option](/reference/configuration/#prerender) to `false`.
+
+If you are using the [Cloudflare adapter](https://docs.astro.build/en/guides/integrations-guide/cloudflare/) to enable server-rendering in your documentation project, make sure to also [add the `nodejs_compat` compatibility flag to your Wrangler configuration file](https://developers.cloudflare.com/workers/runtime-apis/nodejs/#get-started).

docs/src/content/docs/reference/frontmatter.md

@@ -428,9 +428,10 @@ The value should be a [Zod schema](https://docs.astro.build/en/guides/content-co
 
 In the following example, we provide a stricter type for `description` to make it required and add a new optional `category` field:
 
-```ts {10-15}
+```ts {11-16}
 // src/content.config.ts
-import { defineCollection, z } from 'astro:content';
+import { defineCollection } from 'astro:content';
+import { z } from 'astro/zod';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
 
@@ -451,9 +452,10 @@ export const collections = {
 
 To take advantage of the [Astro `image()` helper](https://docs.astro.build/en/guides/images/#images-in-content-collections), use a function that returns your schema extension:
 
-```ts {10-15}
+```ts {11-16}
 // src/content.config.ts
-import { defineCollection, z } from 'astro:content';
+import { defineCollection } from 'astro:content';
+import { z } from 'astro/zod';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
 

docs/src/content/docs/reference/route-data.mdx

@@ -62,20 +62,11 @@ The site title for this page’s locale.
 The value for the site title’s `href` attribute, linking back to the homepage, e.g. `/`.
 For multilingual sites this will include the current locale, e.g. `/en/` or `/zh-cn/`.
 
-### `slug`
-
-**Type:** `string`
-
-The slug for this page generated from the content filename.
-
-This property is deprecated and will be removed in a future version of Starlight.
-Migrate to the new Content Layer API by using [Starlight’s `docsLoader`](/manual-setup/#configure-content-collections) and use the [`id`](#id) property instead.
-
 ### `id`
 
 **Type:** `string`
 
-The slug for this page or the unique ID for this page based on the content filename if using the [`legacy.collections`](https://docs.astro.build/en/reference/legacy-flags/#collections) flag.
+The slug for this page.
 
 ### `isFallback`
 

examples/basics/package.json

@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@astrojs/starlight": "^0.37.7",
-    "astro": "^5.6.1",
+    "astro": "^6.0.1",
     "sharp": "^0.34.2"
   }
 }

examples/markdoc/package.json

@@ -11,10 +11,10 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@astrojs/markdoc": "^0.13.3",
+    "@astrojs/markdoc": "^1.0.0",
     "@astrojs/starlight": "^0.37.7",
     "@astrojs/starlight-markdoc": "^0.5.1",
-    "astro": "^5.6.1",
+    "astro": "^6.0.1",
     "sharp": "^0.34.2"
   }
 }

examples/tailwind/package.json

@@ -13,9 +13,9 @@
   "dependencies": {
     "@astrojs/starlight": "^0.37.7",
     "@astrojs/starlight-tailwind": "^4.0.2",
-    "@tailwindcss/vite": "^4.0.7",
-    "astro": "^5.6.1",
+    "@tailwindcss/vite": "^4.1.18",
+    "astro": "^6.0.1",
     "sharp": "^0.34.2",
-    "tailwindcss": "^4.0.7"
+    "tailwindcss": "^4.1.18"
   }
 }