content-collection

Astro Content Collections

Use this skill when creating or refactoring structured content in Astro, such as blogs, docs, changelogs, case studies, team data, or other schema-driven content.

If astro-best-practices is available, apply it alongside this skill for naming, accessibility, and performance defaults.

Workflow

1. Decide whether the collection is build-time or live

Most content sites should use build-time collections in src/content.config.*. Only reach for live collections in src/live.config.* when the data truly needs request-time freshness.

Before coding, decide:

• which collections exist
• which fields are required
• which relationships need references
• whether assets such as images should be validated

Favor a schema that reflects how the site queries content, not just how frontmatter currently looks.

2. Define collections in src/content.config.*

Use the current Content Layer API. For build-time collections:

• define them in src/content.config.ts (or .js / .mjs)
• give every collection a loader
• import z from astro/zod
• do not use type: 'content' or type: 'data'

Example:

import { defineCollection, reference } from 'astro:content'
import { glob } from 'astro/loaders'
import { z } from 'astro/zod'

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: ({ image }) => z.object({
    title: z.string(),
    description: z.string(),
    publishDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    author: reference('authors'),
    cover: image().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
})

const authors = defineCollection({
  loader: glob({ base: './src/data/authors', pattern: '**/*.json' }),
  schema: z.object({
    name: z.string(),
    email: z.email().optional(),
    avatar: z.url().optional(),
  }),
})

export const collections = { blog, authors }

Useful patterns: