Astro 5 + collection loaders + legacy collections support (#2612)

Co-authored-by: Chris Swithinbank <[email protected]>
Co-authored-by: Chris Swithinbank <[email protected]>
Co-authored-by: Sarah Rainsberger <[email protected]>

.changeset/green-suns-drive.md

@@ -0,0 +1,56 @@
+---
+"@astrojs/starlight": minor
+---
+
+Adds support for Astro v5, drops support for Astro v4.
+
+#### Upgrade Astro and dependencies
+
+⚠️ **BREAKING CHANGE:** Astro v4 is no longer supported. Make sure you [update Astro](https://docs.astro.build/en/guides/upgrade-to/v5/) 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 v5. 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:** Starlight's internal [content collections](https://docs.astro.build/en/guides/content-collections/), which organize, validate, and render your content, have been updated to use Astro's new Content Layer API and require configuration changes in your project.
+
+1. **Move the content config file.** This file no longer lives within the `src/content/config.ts` folder and should now exist at `src/content.config.ts`.
+
+
+1. **Edit the collection definition(s).** To update the `docs` collection, a `loader` is now required:
+
+   ```diff
+    // src/content.config.ts
+    import { defineCollection } from "astro:content";
+   +import { docsLoader } from "@astrojs/starlight/loaders";
+    import { docsSchema } from "@astrojs/starlight/schema";
+
+    export const collections = {
+   -  docs: defineCollection({ schema: docsSchema() }),
+   +  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+    };
+   ```
+
+   If you are using the [`i18n` collection](https://starlight.astro.build/guides/i18n/#translate-starlights-ui) to provide translations for additional languages you support or override our default labels, you will need to update the collection definition in a similar way and remove the collection `type` which is no longer available:
+
+   ```diff
+    // src/content.config.ts
+    import { defineCollection } from "astro:content";
+   +import { docsLoader, i18nLoader } from "@astrojs/starlight/loaders";
+    import { docsSchema, i18nSchema } from "@astrojs/starlight/schema";
+
+    export const collections = {
+   -  docs: defineCollection({ schema: docsSchema() }),
+   +  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+   -  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
+   +  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
+    };
+   ```
+
+1. **Update other collections.** To update any other collections you may have, follow the [“Updating existing collections”](https://docs.astro.build/en/guides/upgrade-to/v5/#updating-existing-collections) section in the Astro 5 upgrade guide.
+
+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.collections` flag](https://docs.astro.build/en/reference/legacy-flags/) to upgrade to v5 without updating your collections. This legacy flag exists to provide temporary backwards compatibility, and will allow you to keep your collections in their current state until the legacy flag is no longer supported.

.changeset/polite-snails-sip.md

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

.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 }})'
@@ -149,6 +152,4 @@ jobs:
 
       - name: Build docs site and check links
         working-directory: ./docs
-        run: pnpm build
-        env:
-          CHECK_LINKS: true
+        run: pnpm linkcheck

.gitignore

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

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.
 

docs/astro.config.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
 import starlightLinksValidator from 'starlight-links-validator';

docs/package.json

@@ -10,6 +10,7 @@
     "build": "astro build",
     "preview": "astro preview",
     "typecheck": "tsc --noEmit",
+    "linkcheck": "CHECK_LINKS=true pnpm build --force",
     "astro": "astro",
     "lunaria:build": "lunaria build",
     "grammars": "node grammars/generate.mjs"
@@ -19,7 +20,7 @@
     "@astrojs/starlight": "workspace:*",
     "@lunariajs/core": "^0.1.1",
     "@types/culori": "^2.1.1",
-    "astro": "^4.16.10",
+    "astro": "^5.0.2",
     "culori": "^4.0.1",
     "sharp": "^0.32.5"
   },

docs/src/content/config.ts → docs/src/content.config.ts

@@ -1,10 +1,14 @@
 import { defineCollection, z } from 'astro:content';
+import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
 import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
 
 export const collections = {
-	docs: defineCollection({ schema: docsSchema() }),
+	docs: defineCollection({
+		loader: docsLoader(),
+		schema: docsSchema(),
+	}),
 	i18n: defineCollection({
-		type: 'data',
+		loader: i18nLoader(),
 		schema: i18nSchema({
 			extend: z.object({
 				'component.preview': z.string().optional(),

docs/src/content/docs/components/code.mdx

@@ -85,14 +85,14 @@ You can then pass this imported string to the `<Code>` component to include it o
 # src/content/docs/example.mdx
 
 import { Code } from '@astrojs/starlight/components';
-import importedCode from '/src/env.d.ts?raw';
+import importedCode from '/tsconfig.json?raw';
 
-<Code code={importedCode} lang="ts" title="src/env.d.ts" />
+<Code code={importedCode} lang="json" title="tsconfig.json" />
 ```
 
-import importedCode from '/src/env.d.ts?raw';
+import importedCode from '../../../../../examples/basics/tsconfig.json?raw';
 
-<Code slot="preview" code={importedCode} lang="ts" title="src/env.d.ts" />
+<Code slot="preview" code={importedCode} lang="json" title="tsconfig.json" />
 
 </Preview>
 

docs/src/content/docs/components/using-components.mdx

@@ -9,7 +9,7 @@ Components let you easily reuse a piece of UI or styling consistently.
 Examples might include a link card or a YouTube embed.
 Starlight supports the use of components in [MDX](https://mdxjs.com/) and [Markdoc](https://markdoc.dev/) files and provides some common components for you to use.
 
-[Learn more about building components in the Astro Docs](https://docs.astro.build/en/core-concepts/astro-components/).
+[Learn more about building components in the Astro Docs](https://docs.astro.build/en/basics/astro-components/).
 
 ## Using a component in MDX
 
@@ -30,7 +30,7 @@ import CustomCard from '../../components/CustomCard.astro';
 <CustomCard>Components can also contain **nested content**.</CustomCard>
 ```
 
-Because Starlight is powered by Astro, you can add support for components built with any [supported UI framework (React, Preact, Svelte, Vue, Solid, and Alpine)](https://docs.astro.build/en/core-concepts/framework-components/) in your MDX files.
+Because Starlight is powered by Astro, you can add support for components built with any [supported UI framework (React, Preact, Svelte, Vue, Solid, and Alpine)](https://docs.astro.build/en/guides/framework-components/) in your MDX files.
 Learn more about [using components in MDX](https://docs.astro.build/en/guides/integrations-guide/mdx/#using-components-in-mdx) in the Astro docs.
 
 ## Using a component in Markdoc

docs/src/content/docs/de/components/code.mdx

@@ -85,14 +85,14 @@ Du kannst diese importierte Zeichenfolge dann an die Komponente `<Code>` überge
 # src/content/docs/example.mdx
 
 import { Code } from '@astrojs/starlight/components';
-import importedCode from '/src/env.d.ts?raw';
+import importedCode from '/tsconfig.json?raw';
 
-<Code code={importedCode} lang="ts" title="src/env.d.ts" />
+<Code code={importedCode} lang="json" title="tsconfig.json" />
 ```
 
-import importedCode from '/src/env.d.ts?raw';
+import importedCode from '../../../../../../examples/basics/tsconfig.json?raw';
 
-<Code slot="preview" code={importedCode} lang="ts" title="src/env.d.ts" />
+<Code slot="preview" code={importedCode} lang="json" title="tsconfig.json" />
 
 </Preview>
 

docs/src/content/docs/environmental-impact.md

@@ -137,6 +137,6 @@ These tests with the [Website Carbon Calculator][wcc] compare similar pages buil
 [sf]: https://www.sciencefocus.com/science/what-is-the-carbon-footprint-of-the-internet/
 [bbc]: https://www.bbc.com/future/article/20200305-why-your-internet-habits-are-not-as-clean-as-you-think
 [http]: https://httparchive.org/reports/state-of-the-web
-[assets]: https://docs.astro.build/en/guides/assets/
+[assets]: https://docs.astro.build/en/guides/images/
 [islands]: https://docs.astro.build/en/concepts/islands/
 [wcc]: https://www.websitecarbon.com/

docs/src/content/docs/es/components/code.mdx

@@ -85,14 +85,14 @@ Puedes pasar este string importado al componente `<Code>` para incluirlo en tu p
 # src/content/docs/example.mdx
 
 import { Code } from '@astrojs/starlight/components';
-import importedCode from '/src/env.d.ts?raw';
+import importedCode from '/tsconfig.json?raw';
 
-<Code code={importedCode} lang="ts" title="src/env.d.ts" />
+<Code code={importedCode} lang="json" title="tsconfig.json" />
 ```
 
-import importedCode from '/src/env.d.ts?raw';
+import importedCode from '../../../../../../examples/basics/tsconfig.json?raw';
 
-<Code slot="preview" code={importedCode} lang="ts" title="src/env.d.ts" />
+<Code slot="preview" code={importedCode} lang="json" title="tsconfig.json" />
 
 </Preview>
 

docs/src/content/docs/fr/components/code.mdx

@@ -85,14 +85,14 @@ Vous pouvez ensuite passer cette chaîne importée au composant `<Code>` pour l'
 # src/content/docs/example.mdx
 
 import { Code } from '@astrojs/starlight/components';
-import importedCode from '/src/env.d.ts?raw';
+import importedCode from '/tsconfig.json?raw';
 
-<Code code={importedCode} lang="ts" title="src/env.d.ts" />
+<Code code={importedCode} lang="json" title="tsconfig.json" />
 ```
 
-import importedCode from '/src/env.d.ts?raw';
+import importedCode from '../../../../../../examples/basics/tsconfig.json?raw';
 
-<Code slot="preview" code={importedCode} lang="ts" title="src/env.d.ts" />
+<Code slot="preview" code={importedCode} lang="json" title="tsconfig.json" />
 
 </Preview>
 

docs/src/content/docs/guides/authoring-content.mdx

@@ -45,7 +45,7 @@ You can highlight `inline code` with backticks.
 
 ## Images
 
-Images in Starlight use [Astro’s built-in optimized asset support](https://docs.astro.build/en/guides/assets/).
+Images in Starlight use [Astro’s built-in optimized asset support](https://docs.astro.build/en/guides/images/).
 
 Markdown and MDX support the Markdown syntax for displaying images that includes alt-text for screen readers and assistive technology.
 

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

@@ -188,16 +188,16 @@ You can provide translations for additional languages you support — or overrid
 
 <Steps>
 
-1. Configure the `i18n` data collection in `src/content/config.ts` if it isn’t configured already:
+1. Configure the `i18n` data collection in `src/content.config.ts` if it isn’t configured already:
 
-   ```diff lang="js" ins=/, (i18nSchema)/
-   // src/content/config.ts
-   import { defineCollection } from 'astro:content';
+   ```diff lang="js" ins=/, (i18nLoader|i18nSchema)/
+   // src/content.config.ts
+   import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
    import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
 
    export const collections = {
-   	docs: defineCollection({ schema: docsSchema() }),
-   +	i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
+   	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+   +	i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
    };
    ```
 
@@ -257,14 +257,15 @@ Add custom keys to your site’s translation dictionaries by setting `extend` in
 In the following example, a new, optional `custom.label` key is added to the default keys:
 
 ```diff lang="js"
-// src/content/config.ts
+// src/content.config.ts
 import { defineCollection, z } from 'astro:content';
+import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
 import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
 
 export const collections = {
-	docs: defineCollection({ schema: docsSchema() }),
+	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
 	i18n: defineCollection({
-		type: 'data',
+		loader: i18nLoader(),
 		schema: i18nSchema({
 +			extend: z.object({
 +				'custom.label': z.string().optional(),
@@ -274,7 +275,7 @@ export const collections = {
 };
 ```
 
-Learn more about content collection schemas in [“Defining a collection schema”](https://docs.astro.build/en/guides/content-collections/#defining-a-collection-schema) in the Astro docs.
+Learn more about content collection schemas in [“Defining a collection schema”](https://docs.astro.build/en/guides/content-collections/#defining-the-collection-schema) in the Astro docs.
 
 ## Using UI translations
 

docs/src/content/docs/guides/overriding-components.mdx

@@ -84,7 +84,7 @@ import Default from '@astrojs/starlight/components/SocialIcons.astro';
 When rendering a built-in component inside a custom component:
 
 - Spread `Astro.props` into it. This makes sure that it receives all the data it needs to render.
-- Add a [`<slot />`](https://docs.astro.build/en/core-concepts/astro-components/#slots) inside the default component. This makes sure that if the component is passed any child elements, Astro knows where to render them.
+- Add a [`<slot />`](https://docs.astro.build/en/basics/astro-components/#slots) inside the default component. This makes sure that if the component is passed any child elements, Astro knows where to render them.
 
 If you are reusing the [`PageFrame`](/reference/overrides/#pageframe) or [`TwoColumnContent`](/reference/overrides/#twocolumncontent) components which contain [named slots](https://docs.astro.build/en/basics/astro-components/#named-slots), you also need to [transfer](https://docs.astro.build/en/basics/astro-components/#transferring-slots) these slots as well.
 
@@ -155,4 +155,4 @@ const isHomepage = Astro.props.slug === '';
 }
 ```
 
-Learn more about conditional rendering in [Astro’s Template Syntax guide](https://docs.astro.build/en/core-concepts/astro-syntax/#dynamic-html).
+Learn more about conditional rendering in [Astro’s Template Syntax guide](https://docs.astro.build/en/basics/astro-syntax/#dynamic-html).

docs/src/content/docs/guides/project-structure.mdx

@@ -5,12 +5,12 @@ description: Learn how to organize files in your Starlight project.
 
 This guide will show you how a Starlight project is organized and what the different files in your project do.
 
-Starlight projects generally follow the same file and directory structure as other Astro projects. See [Astro’s project structure documentation](https://docs.astro.build/en/core-concepts/project-structure/) for more detail.
+Starlight projects generally follow the same file and directory structure as other Astro projects. See [Astro’s project structure documentation](https://docs.astro.build/en/basics/project-structure/) for more detail.
 
 ## Files and directories
 
 - `astro.config.mjs` — The Astro configuration file; includes the Starlight integration and configuration.
-- `src/content/config.ts` — Content collections configuration file; adds Starlight’s frontmatter schemas to your project.
+- `src/content.config.ts` — Content collections configuration file; adds Starlight’s frontmatter schemas to your project.
 - `src/content/docs/` — Content files. Starlight turns each `.md`, `.mdx` or `.mdoc` file in this directory into a page on your site.
 - `src/content/i18n/` (optional) — Translation data to support [internationalization](/guides/i18n/).
 - `src/` — Other source code and files (components, styles, images, etc.) for your project.
@@ -39,8 +39,7 @@ import { FileTree } from '@astrojs/starlight/components';
         - 01-getting-started.md
         - 02-advanced.md
       - index.mdx
-    - config.ts
-  - env.d.ts
+  - content.config.ts
 - astro.config.mjs
 - package.json
 - tsconfig.json

docs/src/content/docs/guides/site-search.mdx

@@ -124,18 +124,19 @@ Add translations of the modal UI for your language using Starlight’s built-in
 
 <Steps>
 
-1. Extend Starlight’s `i18n` content collection definition with the DocSearch schema in `src/content/config.ts`:
+1. Extend Starlight’s `i18n` content collection definition with the DocSearch schema in `src/content.config.ts`:
 
-   ```js ins={4} ins=/{ extend: .+ }/
-   // src/content/config.ts
+   ```js ins={5} ins=/{ extend: .+ }/
+   // src/content.config.ts
    import { defineCollection } from 'astro:content';
+   import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
    import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
    import { docSearchI18nSchema } from '@astrojs/starlight-docsearch/schema';
 
    export const collections = {
-   	docs: defineCollection({ schema: docsSchema() }),
+   	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
    	i18n: defineCollection({
-   		type: 'data',
+   		loader: i18nLoader(),
    		schema: i18nSchema({ extend: docSearchI18nSchema() }),
    	}),
    };