Content collections

Astro's typed wrapper around content files. Originally a fixed filesystem-glob model, now generalized into the Content Layer API with pluggable loaders.

Purpose

Provide a single API (getCollection, getEntry, getEntries) for reading typed, validated content from the filesystem (markdown, MDX, JSON, YAML) or from arbitrary external sources (CMSes, databases, APIs).

Key files

File	Purpose
packages/astro/src/content/config.ts	Schema definitions, defineCollection, type helpers.
packages/astro/src/content/content-layer.ts	The Content Layer runtime. Coordinates loaders, watchers, and the data store.
packages/astro/src/content/loaders/	Built-in loaders (glob, file) and the loader interface.
packages/astro/src/content/data-store.ts, mutable-data-store.ts	The on-disk + in-memory store backing collections.
packages/astro/src/content/types-generator.ts	Produces .astro/content.d.ts. 2,031 lines — the largest file in content/.
packages/astro/src/content/runtime.ts	The runtime API consumed by user code (getCollection etc.).
packages/astro/src/content/runtime-assets.ts	Image/asset bridging from content frontmatter.
packages/astro/src/content/instance.ts	Holds the global ContentLayer singleton.
packages/astro/src/content/server-listeners.ts	Dev-only watchers that re-run loaders on file change.
packages/astro/src/content/utils.ts	Schema helpers, glob expansion, error reporting.
packages/astro/src/content/vite-plugin-content-imports.ts	Resolves astro:content import side.
packages/astro/src/content/vite-plugin-content-virtual-mod.ts	Emits the astro:content virtual module.
packages/astro/src/content/vite-plugin-content-assets.ts	Bridges content frontmatter to astro:assets.
packages/astro/src/content/watcher.ts	Filesystem watcher used by content-layer.ts.

Public API is exported from astro/content/runtime, astro/content/runtime-assets, and astro/loaders.

Anatomy of a collection

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

export const collections = {
  blog: defineCollection({
    loader: glob({ pattern: '**/*.md', base: './src/blog' }),
    schema: z.object({
      title: z.string(),
      pubDate: z.coerce.date(),
      draft: z.boolean().default(false),
    }),
  }),
};

The loader is anything matching the Loader interface from astro/loaders: a function that yields entries plus a name and an incremental: boolean. schema is a Zod object validating each entry's frontmatter.

How it works

graph TD
    A[src/content/config.ts] -->|loaders + schemas| B[ContentLayer]
    B --> C[runs loaders]
    C --> D[validates with Zod]
    D --> E[(MutableDataStore)]
    E --> F[astro:content virtual module]
    F --> G[Page or component runtime]
    H[astro sync] -->|reads store| I[.astro/content.d.ts]
    J[Dev file watcher] -->|on change| C

1. On astro dev/astro build/astro sync, ContentLayer.run() invokes every collection's loader.
2. Loaders write entries to a MutableDataStore keyed by collection + entry id.
3. The store is serialized to .astro/data-store.json so subsequent runs can be incremental.
4. types-generator.ts walks the store and emits .astro/content.d.ts so getCollection('blog') is typed.
5. The Vite plugins (vite-plugin-content-*.ts) expose the data through astro:content.

Built-in loaders

• glob({ pattern, base }) — markdown/MDX/JSON/YAML/data files matching the glob.
• file(path) — a single JSON or YAML file containing many entries.

User loaders are objects implementing { name, load(context) }. The context exposes the data store, a logger, and a parseData helper for Zod validation.

Content imports

When a page does:

import { getCollection, getEntry } from 'astro:content';

const posts = await getCollection('blog');

…the call resolves through vite-plugin-content-virtual-mod.ts. At runtime, getCollection reads from the data store; in dev that's hot-reloaded, in build it's the prebuilt JSON.

Render and render images

getEntry(...).render() is the bridge into the markdown processor (for .md/.mdx). It returns { Content, headings, remarkPluginFrontmatter }. Images referenced in frontmatter are processed by runtime-assets.ts so they go through the astro:assets pipeline.

Sync command

astro sync (packages/astro/src/core/sync/) re-runs every loader, regenerates types, and writes them to .astro/. IDEs and the language server invoke it automatically when src/content/ changes; users can run it manually to force regeneration.

Related pages

• packages / markdown-remark
• packages / integrations / content & build — MDX, Markdoc.
• features / image optimization — frontmatter image handling.
• systems / build pipeline