Content collections in Astro

This chapter follows Routing in Astro.

You can put Markdown files straight into src/pages/, and each becomes a page. That stops scaling once you need a list page, tag pages, a required pubDate, or the same posts in an RSS feed. Content collections separate the content from the routes: you describe the data once, Astro validates every entry, and pages query it like a small typed database.

Define a collection

Collections live in src/content.config.ts. Each one has a loader that finds entries and a schema that validates them:

1
import { defineCollection } from 'astro:content';
2
import { glob } from 'astro/loaders';
3
import { z } from 'astro/zod';
4

5
const blog = defineCollection({
6
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
7
  schema: z.object({
8
    title: z.string(),
9
    description: z.string(),
10
    pubDate: z.coerce.date(),
11
    draft: z.boolean().default(false),
12
    tags: z.array(z.string()).default([]),
13
  }),
14
});
15

16
export const collections = { blog };

The files can live anywhere; base tells the loader where to look. This knowledgebase defines a single articles collection with the same glob loader over src/content/articles, and a custom generateId so that each article’s ID is its filename.

Validate frontmatter with a schema

The schema is a Zod object. If an entry’s frontmatter does not match, the dev server and the build fail with the file name and the failing field, so a missing description never reaches production silently.

1
---
2
title: First post
3
description: Why this blog exists.
4
pubDate: 2026-11-01
5
tags:
6
  - astro
7
---
8

9
The body is regular Markdown.

Schemas can do more than check types. z.coerce.date() turns a YAML date into a Date. .default() fills missing fields. .refine() and .superRefine() enforce rules across fields; this site uses superRefine to require series and seriesOrder together. For images in frontmatter, pass a function to schema and use its image() helper, which validates the path and makes the file usable with <Image />:

1
schema: ({ image }) =>
2
  z.object({
3
    title: z.string(),
4
    cover: image().optional(),
5
  }),

Loaders: files, data, and remote sources

1
import { defineCollection } from 'astro:content';
2
import { file } from 'astro/loaders';
3
import { z } from 'astro/zod';
4

5
const authors = defineCollection({
6
  loader: file('src/data/authors.json'),
7
  schema: z.object({
8
    id: z.string(),
9
    name: z.string(),
10
    url: z.string().url().optional(),
11
  }),
12
});

A loader can also be an async function that returns an array of entries, which is the quickest way to pull data from an API into the same typed query interface. Loaded data is cached between builds.

Query entries

getCollection returns every entry, optionally filtered. getEntry returns one by ID. Each entry has an id, typed data, and for Markdown a body.

1
---
2
import { getCollection } from 'astro:content';
3

4
const posts = (await getCollection('blog', ({ data }) => !data.draft)).sort(
5
  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf(),
6
);
7
---
8
<ul>
9
  {posts.map((post) => (
10
    <li>
11
      <a href={`/blog/${post.id}/`}>{post.data.title}</a>
12
      <time datetime={post.data.pubDate.toISOString()}>
13
        {post.data.pubDate.toLocaleDateString('en-US')}
14
      </time>
15
    </li>
16
  ))}
17
</ul>

Collections have no built-in sort order, so sort explicitly. Filtering drafts in the query, as above, is the usual way to keep them out of production lists.

Render an entry as a page

Combine a collection with a dynamic route. getStaticPaths creates one path per entry, and render() turns the Markdown into a component:

1
---
2
import { getCollection, render } from 'astro:content';
3
import BaseLayout from '../../layouts/BaseLayout.astro';
4

5
export async function getStaticPaths() {
6
  const posts = await getCollection('blog', ({ data }) => !data.draft);
7
  return posts.map((post) => ({ params: { id: post.id }, props: { post } }));
8
}
9

10
const { post } = Astro.props;
11
const { Content, headings } = await render(post);
12
---
13
<BaseLayout title={post.data.title}>
14
  <h1>{post.data.title}</h1>
15
  <Content />
16
</BaseLayout>

headings lists every heading with its depth, slug, and text, which is how a sidebar table of contents is built. This site builds its article sidebar from the ## and ### entries in that list.

Reference other entries

reference() links one collection to another by ID and validates that the target exists:

1
import { defineCollection, reference } from 'astro:content';
2
import { glob } from 'astro/loaders';
3
import { z } from 'astro/zod';
4

5
const blog = defineCollection({
6
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
7
  schema: z.object({
8
    title: z.string(),
9
    author: reference('authors'),
10
    related: z.array(reference('blog')).default([]),
11
  }),
12
});

In frontmatter you write author: ada. In a page, resolve it with await getEntry(post.data.author), or many at once with getEntries(post.data.related). A typo in an author ID now fails the build instead of rendering an empty byline.

Next: Islands and client directives.