Content Collections API Reference
Added in:
astro@2.0.0
Content collections offer APIs to configure and query your Markdown or MDX documents in src/content/
. For features and usage examples, see our content collections guide.
Imports from astro:content
Section titled Imports from astro:contentdefineCollection()
Section titled defineCollection()Type: (input: CollectionConfig) => CollectionConfig
astro@2.0.0
defineCollection()
is a utility to configure a collection in a src/content.config.*
file.
This function accepts the following properties:
loader
Section titled loaderType: () => Promise<Array<{ id: string, [key: string]: any }> | Record<string, Record<string, any>>> | Loader
astro@5.0.0
New
A loader
is either an object or a function that allows you to load data from any source, local or remote, into content collections.
See the Content Collection
guide for example usage.
schema
Section titled schemaType: ZodType | (context: SchemaContext) => ZodType
astro@2.0.0
schema
is an optional Zod object to configure the type and shape of document frontmatter for a collection. Each value must use a Zod validator.
See the Content Collection
guide for example usage.
reference()
Section titled reference()Type: (collection: string) => ZodEffects<ZodString, { collection, id: string }>
astro@2.5.0
The reference()
function is used in the content config to define a relationship, or “reference,” from one collection to another. This accepts a collection name and validates the entry identifier(s) specified in your content frontmatter or data file.
This example defines references from a blog author to the authors
collection and an array of related posts to the same blog
collection:
See the Content Collection
guide for example usage.
getCollection()
Section titled getCollection()Type: (collection: string, filter?: (entry: CollectionEntry<collection>) => boolean) => CollectionEntry<collection>[]
astro@2.0.0
getCollection()
is a function that retrieves a list of content collection entries by collection name.
It returns all items in the collection by default, and accepts an optional filter
function to narrow by entry properties. This allows you to query for only some items in a collection based on id
or frontmatter values via the data
object.
See the Content Collection
guide for example usage.
getEntry()
Section titled getEntry()Type: ( collection: string, id: string ) => CollectionEntry<collection> | ({ collection: string, id: string }) => CollectionEntry<collection>
astro@2.5.0
getEntry()
is a function that retrieves a single collection entry by collection name and the entry id
. getEntry()
can also be used to get referenced entries to access the data
or body
properties:
See the Content Collections
guide for examples of querying collection entries.
getEntries()
Section titled getEntries()Type: (Array<{ collection: string, id: string }>) => Array<CollectionEntry<collection>>
astro@2.5.0
getEntries()
is a function that retrieves multiple collection entries from the same collection. This is useful for returning an array of referenced entries to access their associated data
and body
properties.
render()
Section titled render()Type: () => Promise<RenderedEntry>
astro@5.0.0
New
A function to compile a given entry for rendering. This returns the following properties:
<Content />
- A component used to render the document’s contents in an Astro file.headings
- A generated list of headings, mirroring Astro’sgetHeadings()
utility on Markdown and MDX imports.remarkPluginFrontmatter
- The modified frontmatter object after any remark or rehype plugins have been applied. Set to typeany
.
See the Content Collection
guide for example usage.
astro:content
types
Section titled astro:content typesCollectionEntry
Section titled CollectionEntryQuery functions including getCollection()
, getEntry()
, and getEntries()
each return entries with the CollectionEntry
type. This type is available as a utility from astro:content
:
CollectionEntry
is a generic type. Use it with the name of the collection you’re querying.
For example, an entry in your blog
collection would have the type CollectionEntry<'blog'>
.
Each CollectionEntry
is an object with the following values:
Example Type: 'author-1' | 'author-2' | ...
A unique ID. Note that all IDs from Astro’s built-in glob()
loader are slugified.
collection
Section titled collectionExample Type: 'blog' | 'authors' | ...
The name of a collection in which entries are located. This is the name used to reference the collection in your schema, and in querying functions.
Type: CollectionSchema<TCollectionName>
An object of frontmatter properties inferred from your collection schema (see defineCollection()
reference). Defaults to any
if no schema is configured.
Type: string
A string containing the raw, uncompiled body of the Markdown or MDX document.
CollectionKey
Section titled CollectionKey
Added in:
astro@3.1.0
A string union of all collection names defined in your src/content.config.*
file. This type can be useful when defining a generic function that accepts any collection name.
SchemaContext
Section titled SchemaContextThe context
object that defineCollection
uses for the function shape of schema
. This type can be useful when building reusable schemas for multiple collections.
This includes the following property:
image
- Theimage()
schema helper that allows you to use local images in Content Collections