Content Collections

          
            ## Guidelines for Astro Content Collections

1.  Purpose: Use Content Collections to organize, query, and type-check sets of related content (e.g., blog posts, projects, products) that share a similar data structure. Collections provide type safety and dedicated APIs.

2.  Location: Store collection content files (Markdown, MDX, JSON, YAML, etc.) in the `src/content/` directory, organized into subdirectories named after each collection (e.g., `src/content/blog/`, `src/content/projects/`). Do NOT place collection content directly in `src/pages/`.

3.  Configuration (`src/content/config.ts`):

    - Define each collection using `defineCollection` imported from `astro:content`.
    - Specify a `type` (`'content'` for Markdown/MDX or `'data'` for JSON/YAML).
    - Define a `schema` using Zod (`z` imported from `astro:content`) to validate the frontmatter or data structure of each entry and provide TypeScript types.
    - Use `reference()` within schemas to link entries between different collections (e.g., linking an author entry to a blog post).

4.  Querying Content:

    - Use `getCollection('collectionName', filterCallback?)` to fetch multiple entries. The filter callback receives `{ id, slug, body, collection, data }`.
    - Use `getEntry('collectionName', 'entryId')` or `getEntryBySlug('collectionName', 'entrySlug')` to fetch a single entry.
    - To fetch referenced entries (defined using `reference()` in the schema), use `getEntry()` or `getEntries()` on the reference object(s) returned in the `data` property of the initial entry.

5.  Rendering Content:

    - For Markdown/MDX entries (`type: 'content'`), import `render` from `astro:content`.
    - Call `const { Content } = await render(entry);` to get a component that renders the entry's main content.
    - Render the component in your template: `<Content />`.

6.  Generating Routes/Pages:

    - Collections do not automatically create pages. You must create dynamic routes in `src/pages/` to display collection entries.
    - Static Sites (Default): Use `getStaticPaths` within a dynamic route file (e.g., `src/pages/blog/[...slug].astro`). Call `getCollection` inside `getStaticPaths`, map the results to return `{ params: { slug: entry.slug }, props: { entry } }`. Use `Astro.props.entry` in the page template.
    - SSR: Inside the dynamic route file, retrieve the `slug` or `id` from `Astro.params`. Use `getEntryBySlug` or `getEntry` to fetch the specific entry needed for the request. Redirect to 404 if the entry isn't found.

7.  When to Use: Ideal for multiple pieces of content sharing a structure, requiring validation, type safety, and benefiting from Astro's content APIs. Suitable for scaling to large amounts of content.

8.  When NOT to Use:
    - Single, unique pages (use standard `.astro` pages in `src/pages/`).
    - Static assets like PDFs or images not processed by Astro (use the `public/` directory).
    - Data requiring real-time updates (collections are typically processed at build time).
    - When a specific SDK for a data source is preferred and doesn't integrate with the Content Layer API.

Reference: [Astro Content Collections Docs](mdc:https:/docs.astro.build/en/guides/content-collections)