Guides

Building Astro with open-source tools

Astro's Content Collections provide a robust mechanism for managing Markdown and MDX files with full TypeScript safety. By leveraging Zod for schema validation, you can ensure that frontmatter data is consistent across hundreds of files, preventing runtime errors during build time. This guide covers the end-to-end setup of a validated content pipeline suitable for documentation sites or programmatic SEO projects.

45 minutes6 steps
1

Initialize Content Directory Structure

Astro reserves the 'src/content' directory for managed collections. Create a sub-directory for your specific content type (e.g., 'blog' or 'docs'). This organization allows Astro to generate a localized data store for your files.

mkdir -p src/content/blog

⚠ Common Pitfalls

  • •Do not place content collections outside of 'src/content', as Astro will not detect them for type generation.
  • •Avoid using nested folders within a collection unless you plan to handle complex slug resolution manually.
2

Define Collection Schema with Zod

Create a 'config.ts' file within 'src/content/'. This file acts as the single source of truth for your content's structure. Use Zod to define required fields, default values, and data transformations.

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

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    description: z.string().max(160),
    author: z.string().default('Admin'),
    tags: z.array(z.string()),
    draft: z.boolean().optional()
  }),
});

export const collections = { blog };

⚠ Common Pitfalls

  • •YAML dates in frontmatter are often parsed as strings; Zod's 'z.date()' coercion requires the date to be in a valid ISO format in the Markdown file.
  • •Forgetting to export the 'collections' object will result in type-generation failures.
3

Install and Configure MDX Integration

To use interactive components within your content, install the @astrojs/mdx package and add it to your configuration. This allows you to import React or Svelte components directly into your Markdown files.

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()]
});

⚠ Common Pitfalls

  • •MDX files must use the .mdx extension to be processed by the integration.
  • •Ensure any UI framework integrations (like React) are added before MDX in the integrations array.
4

Query Content with getCollection

Use the 'getCollection' function in your Astro components to fetch and filter your data. This function provides full type safety based on the Zod schema defined in step 2.

---
import { getCollection } from 'astro:content';
const allPosts = await getCollection('blog', ({ data }) => {
  return data.draft !== true;
});
---
<ul>
  {allPosts.map(post => (
    <li><a href={`/blog/${post.slug}`}>{post.data.title}</a></li>
  ))}
</ul>

⚠ Common Pitfalls

  • •Filtering should happen inside the getCollection callback for better performance in large datasets.
  • •Accessing 'post.data' directly without checking if the collection exists will cause TypeScript errors.
5

Implement Dynamic Routing for Content Pages

Create a dynamic route to render individual content entries. Use 'getStaticPaths' to generate a route for every entry in your collection and the '<Content />' component to render the Markdown/MDX body.

src/pages/blog/[...slug].astro
---
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const blogEntries = await getCollection('blog');
  return blogEntries.map(entry => ({
    params: { slug: entry.slug }, props: { entry },
  }));
}

const { entry } = Astro.props;
const { Content } = await entry.render();
---
<h1>{entry.data.title}</h1>
<Content />

⚠ Common Pitfalls

  • •In SSR mode, getStaticPaths is not used; you must fetch the entry using the slug directly from the URL params.
  • •The 'entry.render()' function is asynchronous; failing to await it will prevent the Content component from being available.
6

Configure Image Optimization for Content

To ensure high performance, use Astro's built-in image optimization. In your MDX files, reference local images using relative paths, and Astro will automatically process them during build.

---
title: "My Optimized Post"
---
![Alt text](../../assets/hero.png)

⚠ Common Pitfalls

  • •Remote images are not automatically optimized unless you use the <Image /> component or configure remote patterns in astro.config.mjs.
  • •Relative paths in Markdown must correctly resolve to the assets directory relative to the .md file location.

What you built

By implementing Content Collections with Zod, you have created a type-safe, high-performance content pipeline. This architecture ensures that frontmatter errors are caught during development, MDX allows for interactive elements without sacrificing SEO, and Astro's build process optimizes all assets for production. This setup is now ready for scaling to thousands of pages for pSEO or documentation needs.