Apply suggestions from code review

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

.changeset/quick-onions-leave.md

@@ -22,11 +22,11 @@ In order to achieve backwards compatibility with existing `data` collections, th
 - Entries have an ID that is not slugified
 - `getDataEntryById` is supported
 
-While this backwards compatibility implementation is able to emulate most of the features of legacy collections, there are some differences and limitations that may cause breaking changes to existing collections:
+While this backwards compatibility implementation is able to emulate most of the features of legacy collections, **there are some differences and limitations that may cause breaking changes to existing collections**:
 
-- In previous versions of Astro, collexctions would be generated for all folders in `src/content`, even if they were not defined in `src/content/config.ts`. This behavior is now deprecated, and collections should always be defined in `src/content/config.ts`. For existing collections, these can just be empty declarations: e.g.`const blog = defineCollection({})`. To make it easier to migrate, for now Astro will still generate collections for folders without config, but *only* if no other collections use the new `loader()` syntax. A warning will be logged if this fallback behavior is used, and it will be removed in a future version.
+- In previous versions of Astro, collections would be generated for all folders in `src/content/`, even if they were not defined in `src/content/config.ts`. This behavior is now deprecated, and collections should always be defined in `src/content/config.ts`. For existing collections, these can just be empty declarations (e.g. `const blog = defineCollection({})`) and Astro will implicitly define your legacy collection for you in a way that is compatible with the new loading behavior.
 - The special `layout` field is not supported in Markdown collection entries. This property is intended only for standalone page files located in `src/pages/` and not likely to be in your collection entries. However, if you were using this property, you must now create dynamic routes that include your page styling.
-- Sort order of generated collections is non-deterministic and platform-dependent. This means that if you are calling `getCollection`, the order in which they are returned may be different than before. If you need a specific order, you should sort the collection entries yourself.
+- Sort order of generated collections is non-deterministic and platform-dependent. This means that if you are calling `getCollection()`, the order in which entries are returned may be different than before. If you need a specific order, you should sort the collection entries yourself.
 - `image().refine()` is not supported. If you need to validate the properties of an image you will need to do this at runtime in your page or component.
 - the `key` argument of `getEntry(collection, key)` is typed as `string`, rather than having types for every entry.
 

packages/astro/src/types/public/config.ts

@@ -1550,13 +1550,37 @@ export interface AstroUserConfig {
 		 * @version 5.0.0
 		 * @description
 		 * Enable legacy behavior for content collections.
-		 * If enabled, data and content collections are handled using the legacy code instead of Content Layer API. 
-		 * Any collections with a loader defined will still use the Content Layer API. When enabled, you cannot use 
-		 * the glob loader for any collections in the `src/content` directory, and they will instead be handled by
-		 * the legacy code.
+		 * 
+		 * ```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:
 		 *
-		 * To migrate to the new Content Layer API, you should remove this flag and define a collection for any 
-		 * directories in `src/content` that you want to use as a collection.
+		 * - 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 };
+		 * ```
+		 *
+
 		 */
 		collections?: boolean;
 	};