Content collections are the best way to work with Markdown and MDX in any Astro project. Content collections are a feature of Astro that help manage your content files in a project. Collections help to organize your content, validate your frontmatter, and provide automatic TypeScript type-safety for all of your content.
What are Content Collections?Section titled What are Content Collections?
A content collection is any directory inside the reserved
src/content project directory, such as
src/content/blog. Only content collections are allowed inside the
src/content directory. This directory cannot be used for anything else.
A content entry is any piece of content stored inside of your content collection directory. Content entries are stored as either Markdown (
.md) or MDX (
.mdx) files. You can use any filename you want, but we recommend using a consistent naming scheme (lower-case, dashes instead of spaces) to make it easier to find and organize your content.
newsletter/ the “newsletter” collection
- week-1.md a collection entry
- week-2.md a collection entry
- week-3.md a collection entry
Once you have a collection, you can start querying your content using Astro’s built-in content APIs.
The “.astro” DirectorySection titled The “.astro” Directory
Astro stores important metadata for content collections in an
.astro directory in your project. No action is needed on your part to maintain or update this directory. You are encouraged to ignore it entirely while working in your project.
Organizing with multiple collectionsSection titled Organizing with multiple collections
If two files represent different kinds of content (e.g. a blog post and an author profile), they most likely belong in different collections. This is important because many features (frontmatter validation, automatic TypeScript type-safety) require that all entries in a collection share a similar frontmatter structure.
If you find yourself working with different types of content, you should create multiple collections to represent each type. You can create as many different collections in your project as you’d like.
authors/ split different content types into new collections
Organizing with subdirectoriesSection titled Organizing with subdirectories
A content collection is always a top-level folder inside of the
src/content/ directory. You cannot nest one collection inside of another. However, you can use subdirectories to organize your content within a collection.
For example, you can use the following directory structure to organize i18n translations within a single
docs collection. When you query this collection, you’ll be able to filter the result by language using the file path.
docs/ this collection uses subdirectories to organize by language
Defining CollectionsSection titled Defining Collections
To get the most out of your content collections, create a
src/content/config.ts file in your project (
.mjs extensions are also supported). This is a special file that Astro will automatically load and use to configure your content collections.
Setting up TypeScriptSection titled Setting up TypeScript
If you do not already extend Astro’s
strictest recommended TypeScript settings in your
tsconfig.json file, you may need to update your
tsconfig.json to enable
Defining a collection schemaSection titled Defining a collection schema
Schemas enforce consistent frontmatter within a collection. A schema guarantees that your frontmatter exists in a predictable form when you need to reference or query it. If any file violates its collection schema, Astro will provide a helpful error to let you know.
Schemas also power Astro’s automatic TypeScript typings for your content. When you define a schema for your collection, Astro will automatically generate and apply a TypeScript interface to it. The result is full TypeScript support when you query your collection, including property autocompletion and type-checking.
To create your first content schema, create a
src/content/config.ts file if one does not already exist (
.mjs extensions are also supported). This file should:
- Import the proper utilities from
- Define each collection that you’d like to validate with a schema.
- Export a single
collectionsobject to register your collections.
Defining multiple collectionsSection titled Defining multiple collections
You can use
defineCollection() as many times as you want to create multiple schemas. All collections must be exported from inside the single
As your project grows, you are also free to reorganize your codebase and move logic out of the
src/content/config.ts file. Defining your schemas separately can be useful for reusing schemas across multiple collections and sharing schemas with other parts of your project.
Using third-party collection schemasSection titled Using third-party collection schemas
You can import collection schemas from anywhere, including external npm packages. This can be useful when working with themes and libraries that provide their own collection schemas for you to use.
Defining datatypes with ZodSection titled Defining datatypes with Zod
Astro uses Zod to power its content schemas. With Zod, Astro is able to validate every file’s frontmatter within a collection and provide automatic TypeScript types when you go to query content from inside your project.
To use Zod in Astro, import the
z utility from
"astro:content". This is a re-export of the Zod library, and it supports all of the features of Zod. See Zod’s README for complete documentation on how Zod works and what features are available.
Defining custom slugsSection titled Defining custom slugs
Every content entry generates a URL-friendly
slug property from its file
id. The slug is used to query the entry directly from your collection. It is also useful when creating new pages and URLs from your content.
You can override an entry’s generated slug by adding your own
slug property to the file frontmatter. This is similar to the “permalink” feature of other web frameworks.
"slug" is a special, reserved property name that is not allowed in your custom collection
schema and will not appear in your entry’s
Querying CollectionsSection titled Querying Collections
Both functions return content entries as defined by the
Filtering collection queriesSection titled Filtering collection queries
getCollection() takes an optional “filter” callback that allows you to filter your query based on an entry’s
data (frontmatter) properties.
You can use this to filter by any content criteria you like. For example, you can filter by frontmatter properties like
draft to prevent any draft blog posts from publishing to your blog:
The filter argument also supports filtering by nested directories within a collection. Since the
id includes the full nested path, you can filter by the start of each
id to only return items from a specific nested directory:
Using content in Astro templatesSection titled Using content in Astro templates
Once you have queried your collection entries, you can access each entry directly inside of your Astro component template. This lets you to render HTML for things like links to your content (using the content
slug) or information about your content (using the
For information about rendering your content to HTML, see Rendering Content to HTML below.
Passing content as propsSection titled Passing content as props
A component can also pass an entire content entry as a prop.
If you do this, you can use the
CollectionEntry utility to correctly type your components props using TypeScript. This utility takes a string argument that matches the name of your collection schema, and will inherit all of the properties of that collection’s schema.
Rendering content to HTMLSection titled Rendering content to HTML
Once queried, you can render a collection entry to HTML using the entry
render() function property. Calling this function gives you access to rendered content and metadata, including both a
<Content /> component and a list of all rendered headings.
Generating Routes from ContentSection titled Generating Routes from Content
Content collections are stored outside of the
src/pages/ directory. You will need to create a new dynamic route to generate HTML pages from your collection entries. Your dynamic route will map the incoming request param (ex:
src/pages/blog/[slug].astro) to fetch the correct entry inside a collection.
The exact method for generating routes will depend on your build
output mode: ‘static’ (the default) or ‘server’ (for SSR).
Building for static output (default)Section titled Building for static output (default)
If you are building a static website (Astro’s default behavior), you would use the
getStaticPaths() function to create multiple pages from a single
src/pages/ component during your build.
getCollection() inside of
getStaticPaths() to query your content. Then, create your new URL paths using the
slug property of each content entry.
This will generate a new page for every entry in the
blog collection. For example, an entry at
src/content/blog/hello-world.md will have a slug of
hello-world, and therefore its final URL will be
Building for server output (SSR)Section titled Building for server output (SSR)
If you are building a dynamic website (using Astro’s SSR support), you are not expected to generate any paths ahead-of-time during the build. Instead, your page should examine the request (using
Astro.params) to find the
slug on-demand, and then fetch it using
Migrating from File-Based RoutingSection titled Migrating from File-Based Routing
This guide shows you how to convert an existing Astro project with Markdown files in the
src/pages/ folder to content collections. It uses the Build a Blog tutorial’s finished project as an example.
Upgrade to Astro v2.0 or later, and upgrade all integrations to their latest versions.
Set up TypeScript for content collections.
Create at least one collection (folder in
src/content/) and move your Markdown and MDX pages from
src/pages/into these subdirectories of
src/content/. Collections work best when all files in the same collection have similar frontmatter properties. So, choose your new folder structure to reflect similar types of pages.
For example, to migrate the blog posts in the tutorial, move the contents of
src/content/config.tsfile and define a schema for each content type. For the blog, we only have one content type,
For the tutorial, create a
src/pages/posts/[...slug].astro. This page will use dynamic routing and to generate a page for each collection entry.
This page will also need to query your collection to fetch page slugs and make the page content available to each route.
Render your post
<Content />within the layout for your Markdown or MDX pages. This allows you to specify a common layout for all of your posts.
layoutdefinition in each individual post’s frontmatter. Your content is now wrapped in a layout when rendered, and this property is no longer needed.
getCollection()to fetch content and metadata from your Markdown files. You will also need to update references to the returned post object, since you will now find your frontmatter values on the
The blog index page in the tutorial lists a card for each post. This becomes:
The tutorial blog project also dynamically generates a page for each tag. This page now becomes:
The same logic appears in the tag index page, which becomes:
Lastly, the tutorial blog project includes an RSS feed. This file must also use
getCollectionand use the
For the full example of the blog tutorial using content collections, see the Content Collections branch of the tutorial repo.
Modifying Frontmatter with RemarkSection titled Modifying Frontmatter with Remark
Astro supports remark or rehype plugins that modify your frontmatter directly. You can access this modified frontmatter inside of a content entry by using the
remarkPluginFrontmatter property returned from
The remark and rehype pipelines only runs when your content is rendered, which explains why
remarkPluginFrontmatter is only available after you call
render() on your content entry. In contrast,
getEntryBySlug() cannot return these values directly because they do not render your content.