Astro Content Collections

Astro Content Collections

Type-safe, schema-validated content management built into Astro — no CMS required for structured Markdown, MDX, and data files.

When to Use

• You are organizing Markdown, MDX, YAML, or JSON content files in src/content/
• You need frontmatter validation with helpful error messages (not silent failures)
• You want TypeScript types auto-generated from your content schema
• You are querying multiple content entries (blog posts, docs pages, team members) and need filtering and sorting
• You want to render Markdown content with <Content /> and get full type safety on the rendered entry

Instructions

1. Create a collection config at src/content/config.ts. This is the single source of truth for all collections.

2. Define each collection with defineCollection() and a Zod schema. Every frontmatter field should be declared:

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content', // 'content' for .md/.mdx, 'data' for .json/.yaml
  schema: z.object({
    title: z.string(),
    description: z.string().max(160),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    heroImage: z.string().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

const authors = defineCollection({
  type: 'data',
  schema: z.object({
    name: z.string(),
    email: z.string().email(),
    avatar: z.string().url(),
  }),
});

export const collections = { blog, authors };

3. Place content files under src/content/<collection-name>/. The directory name must match the collection key exported from config.ts.

4. Use getCollection() to fetch all entries. Apply filters inline — do not load all entries and filter in the template:

// src/pages/blog/index.astro
---
import { getCollection } from 'astro:content';

// Exclude drafts in production
const posts = await getCollection('blog', ({ data }) => {
  return import.meta.env.PROD ? !data.draft : true;
});

// Sort by date descending
const sorted = posts.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---

5. Use getEntry() to fetch a single entry by collection name and slug:

const post = await getEntry('blog', 'my-first-post');
if (!post) return Astro.redirect('/404');
const { Content } = await post.render();

6. Render Markdown/MDX content with the <Content /> component returned from entry.render():

---
const { Content, headings, remarkPluginFrontmatter } = await post.render();
---
<article>
  <Content />
</article>

7. Use z.coerce.date() for date fields in frontmatter — raw frontmatter dates are strings, and coercion converts them to Date objects automatically.

8. Reference images in frontmatter using the image() helper for build-time optimization integration:

import { defineCollection, z, reference } from 'astro:content';
schema: ({ image }) =>
  z.object({
    cover: image(), // local image, processed by astro:assets
    author: reference('authors'), // type-safe cross-collection reference
  });

Details

Content Collections were introduced in Astro 2.0 to solve the problem of unstructured, unvalidated frontmatter. Without collections, a typo in a date field or a missing required property would either silently pass or cause a runtime error deep in your template. With collections, Astro validates every entry at build time using Zod and surfaces clear errors.

The type distinction:

• type: 'content' — for .md and .mdx files. Entries have body (raw Markdown string), render() method, and slug (auto-derived from filename).
• type: 'data' — for .json and .yaml files. Entries have only data (the parsed object). No render() or slug.

Generated types:

Astro generates .astro/types.d.ts from your collection config. This gives you full IntelliSense on entry.data.title, entry.data.pubDate, etc., without manual type declarations.

Slugs and IDs:

• entry.slug — the path relative to the collection directory, without the extension. For src/content/blog/2024/my-post.md, the slug is 2024/my-post.
• entry.id — same as slug but with the extension included. Primarily used for data collections.

Cross-collection references:

Use reference('collectionName') in a Zod schema to create typed cross-collection references. Astro validates that the referenced entry exists at build time. Resolve references with getEntry(entry.data.author).

Content Layer API (Astro 5+):

Astro 5 introduced the Content Layer API, which extends collections to support external data sources (remote APIs, databases, CMSes). Use loader in defineCollection():

const products = defineCollection({
  loader: async () => {
    const res = await fetch('https://api.example.com/products');
    return res.json(); // array of objects with an `id` field
  },
  schema: z.object({ id: z.string(), name: z.string(), price: z.number() }),
});

Performance: getCollection() reads from the file system at build time (SSG) or at request time (SSR). In SSG, results are used to generate static pages via getStaticPaths(). In SSR, consider caching results if collections are large.

Source

https://docs.astro.build/en/guides/content-collections

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.