support for legacy content collections removed (#12376)

Co-authored-by: Matt Kane <[email protected]>
Co-authored-by: Armand Philippot <[email protected]>
Co-authored-by: Yan <[email protected]>

Author: 4 people

src/content/docs/en/guides/upgrade-to/v6.mdx

@@ -161,6 +161,137 @@ The following features have now been entirely removed from the code base and can
 
 Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features.
 
+
+### Removed: legacy content collections
+
+<SourcePR number="14407" title="fix: remove legacy content collections"/>
+
+In Astro 5.x, it was still possible to use [the original Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/), either through a `legacy` configuration flag or via built-in backwards compatibility. These methods allowed you to upgrade to Astro v5 even if you were not yet ready or able to update your existing content collections to those powered by the new Content Layer API.
+
+**Astro v6.0 removes this previously deprecated Content Collections API support entirely, including the `legacy.collections` flag.** All content collections must now use [the Content Layer API introduced in Astro v5.0](https://astro.build/blog/content-layer-deep-dive/) that powers all content collections. No backwards compatibility support is available.
+
+#### What should I do?
+
+If you had previously enabled the legacy flag, you must remove it.
+
+```ts title="astro.config.mjs" del={5}
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  legacy: {
+    collections: true,
+  }
+})
+```
+
+Additionally, if you did not upgrade your collections for Astro v5.0, ensure that your content collections are **fully updated** for the new API.
+
+Astro v5.x included some automatic backwards compatibility to allow content collections to continue to work even if they had not been updated to use the new API. Therefore, your v5 collections may contain one or more legacy features that need updating to the newer API for v6, even if your project was previously error-free.
+
+If you have [content collections errors](/en/reference/error-reference/#content-collection-errors) or warnings after upgrading to v6, use the following list to help you identify and upgrade any legacy features that may exist in your code.
+
+##### If you have...
+
+<details>
+<summary>no content collections configuration file</summary>
+Create `src/content.config.ts` and [define your collections](/en/guides/content-collections/#defining-collections) in it.
+</details>
+
+<details>
+<summary>a configuration file located at `src/content/config.ts` / ([`LegacyContentConfigError`](/en/reference/errors/legacy-content-config-error/))</summary>
+Rename and move this file to `src/content.config.ts`
+</details>
+
+<details>
+<summary>a collection that does not define a `loader`/ ([`ContentCollectionMissingALoaderError`](/en/reference/errors/content-collection-missing-loader/))</summary>
+
+Import [Astro's built-in `glob()` loader](/en/guides/content-collections/#built-in-loaders) and define the `pattern` and `base` for your collection entries:
+
+```ts ins={3,6}
+// src/content.config.ts
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+const blog = defineCollection({
+  loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    pubDate: z.coerce.date(),
+    updatedDate: z.coerce.date().optional(),
+  }),
+});
+```
+</details>
+
+<details>
+<summary>a collection that defines a collection type (`type: 'content'` or `type: 'data'`) / ([`ContentCollectionInvalidTypeError`](/en/reference/errors/content-collection-invalid-type/))</summary>
+There are no longer different types of collections. This must be deleted from your collection definition.
+
+```ts del={7}
+// src/content.config.ts
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+const blog = defineCollection({
+  // For content layer you no longer define a `type`
+  type: 'content',
+  loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
+  schema: z.object({
+    title: z.string(),
+    description: z.string(),
+    pubDate: z.coerce.date(),
+    updatedDate: z.coerce.date().optional(),
+  }),
+});
+```
+</details>
+
+<details>
+<summary>legacy collection querying methods `getDataEntryById()` and `getEntryBySlug()` / ([`GetEntryDeprecationError`](/en/reference/errors/get-entry-deprecation-error/))</summary>
+Replace both methods with [`getEntry()`](/en/reference/modules/astro-content/#getentry).
+
+</details>
+
+<details>
+<summary>legacy collection querying and rendering methods that depend on a `slug` property / ([`ContentSchemaContainsSlugError`](/en/reference/errors/content-schema-contains-slug-error/))</summary>
+Previously, the `id` was based on the filename, and there was a `slug` property that could be used in a URL. Now the [CollectionEntry](/en/reference/modules/astro-content/#collectionentry) `id` is a slug. If you need access to the filename (previously available as the `id`), use the `filePath` property. Replace instances of `slug` with `id`:
+
+```astro ins={6} del={5} title="src/pages/[slug].astro"
+---
+export async function getStaticPaths() {
+  const posts = await getCollection('blog');
+  return posts.map((post) => ({
+    params: { slug: post.slug },
+    params: { slug: post.id },
+    props: post,
+  }));
+}
+---
+```
+</details>
+
+<details>
+<summary>content rendered using `entry.render()`</summary>
+Collection entries no longer have a `render()` method. Instead, import the `render()` function from `astro:content` and use `render(entry)`:
+
+```astro title="src/pages/index.astro" ins=", render" del={6} ins={7}
+---
+import { getEntry, render } from 'astro:content';
+
+const post = await getEntry('pages', 'homepage');
+
+const { Content, headings } = await post.render();
+const { Content, headings } = await render(post);
+---
+<Content />
+```
+
+</details>
+
+<ReadMore> See [the Astro v5 upgrade guide](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about backwards compatibility of legacy collections in Astro v5 and full step-by-step instructions for upgrading legacy collections to the new Content Layer API.</ReadMore>
+
+
 ### Removed: `<ViewTransitions />` component
 
 <SourcePR number="14400" title="Remove deprecated ViewTransitions component"/>

src/content/docs/en/reference/errors/content-collection-invalid-type.mdx

@@ -0,0 +1,23 @@
+---
+# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs'
+# Do not make edits to it directly, they will be overwritten.
+# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
+# Translators, please remove this note and the <DontEditWarning/> component.
+
+title: Content collection invalid type.
+i18nReady: true
+githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
+---
+
+import DontEditWarning from '~/components/DontEditWarning.astro'
+
+<DontEditWarning />
+
+
+> Invalid collection type "data". Remove the type from your collection definition in your content config file.
+
+### What went wrong?
+
+Content collections should no longer have a type field. Remove this field from your content config file.
+
+See the [Astro 6 migration guide](/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information.

src/content/docs/en/reference/errors/content-collection-missing-loader.mdx

@@ -0,0 +1,24 @@
+---
+# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs'
+# Do not make edits to it directly, they will be overwritten.
+# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
+# Translators, please remove this note and the <DontEditWarning/> component.
+
+title: Content collection missing loader.
+i18nReady: true
+githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
+---
+
+import DontEditWarning from '~/components/DontEditWarning.astro'
+
+<DontEditWarning />
+
+
+> Collections must have a loader defined. Check your collection definitions in your content config file.
+
+### What went wrong?
+
+A content collection is missing a loader definition. Make sure that each collection in your content config file has a loader.
+
+**See Also:**
+-  [Content collections configuration](/en/guides/content-collections/#defining-the-collection-loader)

src/content/docs/en/reference/errors/legacy-content-config-error.mdx

@@ -0,0 +1,26 @@
+---
+# NOTE: This file is auto-generated from 'scripts/error-docgen.mjs'
+# Do not make edits to it directly, they will be overwritten.
+# Instead, change this file: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
+# Translators, please remove this note and the <DontEditWarning/> component.
+
+title: Legacy content config error.
+i18nReady: true
+githubURL: https://github.com/withastro/astro/blob/main/packages/astro/src/core/errors/errors-data.ts
+---
+
+import DontEditWarning from '~/components/DontEditWarning.astro'
+
+<DontEditWarning />
+
+
+> Legacy content config file found.
+
+### What went wrong?
+
+A legacy content config file was found. Move the file to `src/content.config.ts` and update any collection definitions if needed.
+
+See the [Astro 6 migration guide](/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information.
+
+**See Also:**
+-  [Content collections configuration](/en/guides/content-collections/#the-collection-config-file)

src/content/docs/en/reference/legacy-flags.mdx

@@ -3,49 +3,11 @@ title: Legacy flags
 i18nReady: true
 ---
 
+import Since from '~/components/Since.astro'
+
 To help some users migrate between versions of Astro, we occasionally introduce `legacy` flags.
 
 These flags allow you to opt in to some deprecated or otherwise outdated behavior of Astro
 in the latest version, so that you can continue to upgrade and take advantage of new Astro releases until you are able to fully update your project code.
 
-import Since from '~/components/Since.astro'
-
-## Collections
-
-<p>
-
-**Type:** `boolean`<br />
-**Default:** `false`<br />
-<Since v="5.0.0" />
-</p>
-
-Enable legacy behavior for content collections (as used in Astro v2 through v4)
-
-```js
-// astro.config.mjs
-import { defineConfig } from 'astro/config';
-export default defineConfig({
-  legacy: {
-    collections: true
-  }
-});
-```
-
-If enabled, `data` and `content` collections (only) are handled using the legacy content collections implementation. Collections with a `loader` (only) will continue to use the Content Layer API instead. Both kinds of collections may exist in the same project, each using their respective implementations.
- 
- The following limitations continue to exist:
-
-- Any legacy (`type: 'content'` or `type: 'data'`) collections must continue to be located in the `src/content/` directory.
-- These legacy collections will not be transformed to implicitly use the `glob()` loader, and will instead be handled by legacy code.
-- Collections using the Content Layer API (with a `loader` defined) are forbidden in `src/content/`, but may exist anywhere else in your project. 
-
-When you are ready to remove this flag and migrate to the new Content Layer API for your legacy collections, you must define a collection for any directories in `src/content/` that you want to continue to use as a collection. It is sufficient to declare an empty collection, and Astro will implicitly generate an appropriate definition for your legacy collections:
- 
-```js
-// src/content/config.ts
-import { defineCollection, z } from 'astro:content';
-
-const blog = defineCollection({ })
- 
-export const collections = { blog };
-```
+There are currently no legacy flags available. When new legacy flags become available, instructions for removing them and upgrading to the latest features of Astro will be listed below.