Skip to content

Content Collections

Astronaut CMS works with Astro’s standard content collection API. Define your collections in src/content.config.ts and the CMS admin panel will automatically generate editor forms from your Zod schemas.

Glob collections store one entry per file. Use the glob() loader to match files by pattern.

src/content.config.ts
import { defineCollection } from "astro:content";
import { glob } from "astro/loaders";
import { z } from "astro/zod";
const blog = defineCollection({
loader: glob({ pattern: "**/*.{md,mdx}", base: "src/content/blog" }),
schema: ({ image }) =>
z.object({
title: z.string(),
description: z.string(),
date: z.coerce.date(),
cover: image().optional(),
}),
});
export const collections = { blog };

The admin panel will display a form with fields for title, description, date, and an image picker for cover.

The CMS reads the pattern exactly as Astro’s loader does. The admin lists, and the build checks, only the files under base that the pattern matches. Without a base, that is the project root, as in Astro. Dotfiles never match, and a pattern starting with ! excludes what the others match, such as ["**/*.md", "!drafts/**"]. Creating or renaming an entry to a path the pattern does not match is refused, since the site would never load it.

Entries have the ids Astro gives them, so Über Uns.md is the entry über-uns. A new entry is written to its id with the format’s extension, so the CMS refuses an id Astro would spell differently and suggests Astro’s spelling. A slug field that gives an entry another id than its file fails the build, since the CMS names entries by their files. A generateId passed to glob() cannot be mirrored, and the CMS warns about it at startup.

File collections store multiple entries in a single file. Use the file() loader for JSON, YAML, or TOML data files.

src/content.config.ts
import { defineCollection } from "astro:content";
import { file } from "astro/loaders";
import { z } from "astro/zod";
const authors = defineCollection({
loader: file("src/data/authors.json"),
schema: z.object({
name: z.string(),
email: z.string().email().optional(),
bio: z.string().optional(),
}),
});
export const collections = { authors };

File collections support both array and object layouts, which the admin panel detects automatically.

A glob collection whose pattern names one literal file is a singleton, such as the master data of a company.

src/content.config.ts
const company = defineCollection({
loader: glob({ pattern: "company.yml", base: "src/content" }),
schema: z.object({ name: z.string(), phone: z.string() }),
});

Read it with getEntry("company", "company"). The admin opens its entry form directly from the navigation and offers no way to create, duplicate, rename or delete an entry. The server refuses those operations too, for editors and agents alike. A build fails while the file is missing.

With content languages, a singleton can hold one file per language: a pattern of a language folder followed by one literal file, such as */site.yml. See Localized singletons.

Astro’s getCollection() returns entries sorted by id, whatever order a file holds them in. Set sort per collection in the collections export of src/cms.config.ts to choose another order:

sort Order
{ by: "id" } (default) By id, as astro returns them
{ by: "natural" } By id, with numbers compared as numbers (2 before 10)
{ by: "file" } The order of the file, for file() collections only
{ by: "field", field: "number" } By a top-level scalar field, compared like natural, entries without it last
src/cms.config.ts
import { defineCollection } from "astronaut-cms/config";
export const collections = {
authors: defineCollection({ sort: { by: "file" } }),
};

The admin lists entries in that order, and only a file order offers reordering. A field order needs every entry read to list a collection, so it suits a field editors maintain anyway, such as a catalog number. Read the same order in your pages with sortEntries():

src/pages/about.astro
---
import { getCollection } from "astro:content";
import { sortEntries } from "astronaut-cms/content";
const authors = sortEntries(await getCollection("authors"));
---

No order field is needed, so the schema holds nothing the editor has to maintain.

Use reference() to create relationships between collections.

src/content.config.ts
import { defineCollection, reference } from "astro:content";
import { glob, file } from "astro/loaders";
import { z } from "astro/zod";
const authors = defineCollection({
loader: file("src/data/authors.json"),
schema: z.object({
name: z.string(),
}),
});
const blog = defineCollection({
loader: glob({ pattern: "**/*.{md,mdx}", base: "src/content/blog" }),
schema: z.object({
title: z.string(),
author: reference("authors").optional(),
}),
});
export const collections = { authors, blog };

The admin panel renders reference fields as dropdown selectors populated with entries from the referenced collection.

The CMS admin panel generates appropriate form controls based on the Zod schema type:

Zod Type Admin Panel Control
z.string() Text input
z.string().email() Email input
z.number() Number input
z.boolean() Toggle switch
z.coerce.date() Date picker
z.enum([...]) Dropdown select
image() Image picker (from media library)
file() File picker (from media library)
reference("collection") Reference dropdown

The fields of an entry are listed above its body, each label next to its control once the page is wide enough. An object is shown in place as a framed section, and an optional field left empty is left out of the file.

A list or record of objects is shown as one row that names its items, and clicking it opens them in the panel next to the content. There, the items are reordered by dragging and added at the end, and clicking one opens its fields, with breadcrumbs leading back. An open item has the same actions as a component: buttons to move it up and down, and a menu to duplicate, copy, cut or delete it. The clipboard holds an item as JSON, so pasting takes it into any list its fields fit.

A field is labeled with its key in words, such as “Cta Href” for ctaHref. Zod’s .meta() changes how the form presents it:

z.object({
ctaHref: z.string().meta({ title: "Button link", description: "Where the button leads." }),
theme: z.enum(["light", "dark"]).meta({ group: "Appearance" }),
});

title replaces the label, and description (or .describe()) is shown below the field. Fields that share a group are listed together in a section that opens on demand, after the fields without one. multiline: true edits a text in a textarea, and labels names the options of an enum:

z.object({
intro: z.string().meta({ multiline: true }),
layout: z.enum(["mosaic", "grid"]).meta({ labels: { mosaic: "Mosaic", grid: "Equal tiles" } }),
});

The same keys work for the props of a component.

The body of a Markdown or MDX entry is edited as rich text. One insert menu adds anything to it: text blocks such as headings, lists, tables and images, the components from cms.config, and the content of the clipboard. It opens from typing / on an empty line or between blocks, and from the Insert button of the toolbar.

An empty line is a place to type or insert at. Between two blocks without text, such as components, tables and code blocks, the caret sits in the gap, shown as a short line. The arrow keys and a click between the blocks take it there, and Enter or typing then start a new line in that place. Markdown only knows blank lines between blocks, so an empty line is never written to the file, and it disappears once the caret leaves it. Saving rewrites only the blocks that were edited, and every other block keeps its source text along with the blank lines around it.

A component is selected with a click, and the arrow keys select it, or any other block without text, on the way past. Enter then starts a new line below it, and Backspace or Delete removes it.

While no component is selected, the panel next to the body shows its outline. Dragging a row reorders the body, and clicking one jumps to its block.

A selected component has its actions in the inspector: buttons to move it up and down, and a menu to duplicate, copy, cut or delete it. To move it to another entry, copy or cut it from there, or with the keyboard, and paste it where it belongs. The clipboard holds the component as MDX, so it can also be pasted into the source view or another editor. Pasting checks where the content goes: a structured child only fits into its parent, and a line of text only takes inline components.

Undo and redo, from the buttons next to Save or with the usual keys, take back the latest change of the page, whether in its fields, its body or the props of a component. Typing into one field in quick succession is one step. The history starts over with each page, so leaving a page with unsaved changes asks first.

Glob collections support the following file formats:

  • Markdown (.md) — YAML frontmatter + body
  • MDX (.mdx) — YAML frontmatter + body with JSX components
  • Markdoc (.mdoc) — YAML frontmatter + body

File collections support:

  • JSON (.json) — arrays or objects with id fields
  • YAML (.yaml, .yml) — objects with id keys
  • TOML (.toml) — objects