Typed content collections in Astro

One of the things I wanted to get right early on this blog was the content model. Markdown is flexible to the point of being dangerous — nothing stops you from publishing a post with a missing title, a malformed date, or a cover image path that leads nowhere. On a small site this sounds manageable. In practice, these problems compound.

Astro content collections solve this with Zod schema validation at build time. If the content doesn’t match the schema, the build fails loudly instead of deploying silently broken content.

How the collection is defined

Everything lives in src/content.config.ts. The defineCollection call takes a loader (which describes where to find the files) and a schema:

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

5
const posts = defineCollection({
6
  loader: glob({ pattern: ["**/*.md", "!README.md"], base: "./collections/posts" }),
7
  schema: ({ image }) =>
8
    z.object({
9
      title: z.string(),
10
      subTitle: z.string(),
11
      description: z.string(),
12
      pubDate: z.coerce.date(),
13
      author: z.string(),
14
      cover: z
15
        .object({
16
          image: image(),
17
          alt: z.string(),
18
        })
19
        .optional(),
20
      tags: z.array(z.string()),
21
      draft: z.boolean().default(false),
22
      history: z
23
        .array(
24
          z.object({
25
            datetime: z.coerce.date(),
26
            note: z.string(),
27
          }),
28
        )
29
        .optional(),
30
      credits: z
31
        .array(
32
          z.object({
33
            label: z.string(),
34
            text: z.string(),
35
            url: z.string().url().optional(),
36
          }),
37
        )
38
        .optional(),
39
    }),
40
});
41

42
export const collections = { posts };

A few things worth noting:

• z.coerce.date() means a YAML string like 2026-03-26T00:00:00 is automatically coerced to a JavaScript Date object. You get proper date comparison and formatting in templates without any manual parsing.
• image() is a special helper provided by Astro’s schema context. It validates that the referenced file exists on disk and returns a typed object with the processed src. Astro passes this through its image optimisation pipeline.
• draft: z.boolean().default(false) means the draft field is optional in frontmatter — omitting it defaults to false, so only posts that explicitly declare draft: true need the field.
• credits URLs use z.string().url(), so a malformed URL will fail the build rather than silently render a broken link.

Where the posts live

The glob loader uses a base path outside src/ — the posts are in collections/posts/ at the project root. Each post gets its own directory:

1
collections/
2
  posts/
3
    why-astro/
4
      index.md
5
    comments-system/
6
      index.md
7
      comments-system-cover.jpg

Co-locating the cover image with the Markdown file is simpler than managing a separate public/ directory for post images. Astro’s image pipeline picks them up automatically when the schema uses image().

The post id that Astro assigns is derived from the directory structure — why-astro for the post above. That becomes the URL slug via the [id].astro dynamic route.

Querying the collection

In any .astro file or API route, getCollection("posts") returns a typed array of posts whose data property matches the schema:

1
import { getCollection } from "astro:content";
2

3
const allPosts = await getCollection("posts");

Every access to post.data.title, post.data.pubDate, or post.data.tags is fully typed. If the schema changes, TypeScript catches every reference that no longer lines up.

The draft flag and scheduled publishing

The draft field alone isn’t the full picture. The blog uses a small utility in src/utils/drafts.ts that combines draft status, publish date, and an environment variable:

1
export const showDrafts: boolean = import.meta.env.SHOW_DRAFTS === "true";
2

3
export function isPublished(post: { data: { draft: boolean; pubDate: Date } }): boolean {
4
  if (showDrafts) return true;
5
  if (post.data.draft) return false;
6
  return post.data.pubDate <= new Date();
7
}

Every collection query that feeds the public site passes posts through isPublished() rather than a bare draft check:

1
import { getCollection } from "astro:content";
2
import { isPublished } from "../utils/drafts";
3

4
const allPosts = (await getCollection("posts")).filter(isPublished);

This gives three distinct states:

• draft: true — never visible on the public site, regardless of pubDate.
• draft: false, future pubDate — not yet published; filtered out until the date passes.
• draft: false, past pubDate — live.

The SHOW_DRAFTS=true environment variable short-circuits the filter entirely, which is how the preview branch deploy works — it shows everything, including drafts and scheduled posts, behind a passcode wall.

Posts filtered out by isPublished() are excluded from listings, tag pages, the RSS feed, and getStaticPaths() — so their URLs return a 404 in production even if someone guesses the slug.

Optional fields and TypeScript

The cover, history, and credits fields are all .optional(). In templates this means you get types like ({ image: ImageMetadata; alt: string } | undefined). TypeScript will refuse to let you access cover.image.src without first checking that cover exists.

That’s the intended behaviour — it forces every template that uses these fields to handle the case where they’re absent, which is exactly the kind of bug that slips through without a type system.

What this gives you

Build-time validation. A malformed date, a missing required field, or a cover image pointing to a nonexistent file stops the build immediately. You find content errors locally, not after deploying.

Full TypeScript coverage across templates. Every .astro component that touches post.data gets accurate types. Rename a field in the schema and TypeScript surfaces every broken reference.

Scheduled publishing without a CMS. Because pubDate is a typed Date and the isPublished() filter compares it to the current time, setting a future date is enough to schedule a post. The daily build picks it up automatically. There’s a dedicated post on how this works coming 8 May.

Drafts with a preview workflow. draft: true keeps work-in-progress content off the live site, while the SHOW_DRAFTS flag lets you review it fully rendered on a separate deploy before it goes public.