Content Collections Management for Astro

Complete content collections setup and management for Astro projects, including type-safe schemas, query patterns, frontmatter validation, and content organization.

Overview

This skill provides comprehensive support for Astro content collections:

• Schema definition with Zod validation
• Type-safe query patterns
• Frontmatter validation and testing
• Collection setup and configuration
• Content organization best practices

Instructions

1. Initial Setup

Run the setup script to initialize content collections in an Astro project:

bash scripts/setup-content-collections.sh [project-path]

This script:

• Creates src/content/config.ts if not exists
• Sets up collection directories
• Adds TypeScript types generation
• Configures content collection imports

2. Define Collection Schemas

Use schema templates to define type-safe collection schemas:

TypeScript Schema (Recommended):

# Read template for reference
Read: templates/schemas/blog-collection-schema.ts
Read: templates/schemas/docs-collection-schema.ts

Python Schema (for build scripts):

# For Python-based content generation
Read: templates/python/collection-schema.py

3. Generate TypeScript Types

Generate TypeScript types from your collection schemas:

bash scripts/generate-types.sh [project-path]

This creates:

• src/content/config.ts exports
• Type definitions in .astro/types.d.ts
• Auto-completion for collection queries

4. Query Content Collections

Use query builder patterns for type-safe content retrieval:

TypeScript Queries:

Read: templates/queries/basic-queries.ts
Read: templates/queries/advanced-queries.ts
Read: templates/queries/filtered-queries.ts

Python Queries (for build scripts):

Read: templates/python/query-patterns.py

5. Validate Frontmatter

Validate content frontmatter against schemas:

bash scripts/validate-frontmatter.sh [collection-name] [content-path]

This script:

• Checks frontmatter against schema
• Reports validation errors
• Suggests fixes for common issues

6. Build Query Patterns

Generate optimized query patterns:

bash scripts/query-builder.sh [collection-name] [query-type]

Query types:

• all - Get all entries
• filtered - Filter by frontmatter fields
• sorted - Sort by date/title/custom field
• paginated - Paginate results
• related - Find related content

7. Test Collections

Run comprehensive collection tests:

bash scripts/test-collections.sh [project-path]

Tests include:

• Schema validation
• Type checking
• Query performance
• Frontmatter completeness

Scripts Reference

All scripts located in scripts/:

1. setup-content-collections.sh - Initialize content collections structure
2. validate-frontmatter.sh - Validate content against schemas
3. generate-types.sh - Generate TypeScript types from schemas
4. query-builder.sh - Build optimized query patterns
5. test-collections.sh - Run comprehensive collection tests

Templates Reference

TypeScript Templates (templates/typescript/)

1. blog-collection.ts - Blog post collection schema
2. docs-collection.ts - Documentation collection schema
3. basic-queries.ts - Common query patterns
4. advanced-queries.ts - Complex filtering and sorting
5. paginated-queries.ts - Pagination patterns
6. related-content.ts - Related content finding

Python Templates (templates/python/)

1. collection-schema.py - Python schema definitions
2. query-patterns.py - Python query builders
3. frontmatter-validator.py - Validation utilities

Schema Templates (templates/schemas/)

1. blog-collection-schema.ts - Blog post schema with Zod
2. docs-collection-schema.ts - Documentation schema
3. product-collection-schema.ts - E-commerce product schema
4. author-collection-schema.ts - Author profile schema

Query Templates (templates/queries/)

1. basic-queries.ts - getAllEntries, getEntryBySlug
2. advanced-queries.ts - Complex filtering
3. filtered-queries.ts - Category, tag, date filtering
4. sorted-queries.ts - Sorting patterns
5. paginated-queries.ts - Pagination with prev/next
6. related-queries.ts - Related content algorithms

Validation Templates (templates/validation/)

1. schema-validator.ts - Zod schema validation
2. frontmatter-checker.ts - Frontmatter completeness
3. type-checker.ts - TypeScript type validation

Examples

See comprehensive examples in examples/:

1. basic-usage.md - Getting started with content collections
2. advanced-usage.md - Complex schemas and queries
3. common-patterns.md - Typical content collection patterns
4. error-handling.md - Common errors and solutions
5. integration.md - Integration with MDX, images, and components

Common Patterns

Blog Collection Schema

import { defineCollection, z } from 'astro:content';

const blogCollection = defineCollection({
  schema: z.object({
    title: z.string()
    description: z.string()
    pubDate: z.date()
    updatedDate: z.date().optional()
    heroImage: z.string().optional()
    tags: z.array(z.string()).default([])
    author: z.string()
    draft: z.boolean().default(false)
  })
});

export const collections = { blog: blogCollection };

Type-Safe Queries

import { getCollection, getEntry } from 'astro:content';

// Get all published blog posts
const posts = await getCollection('blog', ({ data }) => {
  return data.draft !== true;
});

// Get single post by slug
const post = await getEntry('blog', 'my-post-slug');

// Sort by date descending
const sortedPosts = posts.sort((a, b) =>
  b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
);

Frontmatter Validation

import { z } from 'zod';

const blogSchema = z.object({
  title: z.string().min(1, "Title required")
  description: z.string().max(160, "Description too long")
  pubDate: z.date()
});

// Validate frontmatter
const result = blogSchema.safeParse(frontmatter);
if (!result.success) {
  console.error(result.error.format());
}

Requirements

• Astro 3.0+ or 4.0+ (content collections support)
• Node.js 18+
• TypeScript 5.0+ (for type generation)
• Zod 3.0+ (for schema validation)
• Python 3.8+ (optional, for Python templates)

Best Practices

1. Schema Design:

   • Use specific types (date, enum) over strings
   • Add descriptions for better auto-completion
   • Set sensible defaults for optional fields
   • Use unions for variant content types

2. Query Optimization:

   • Filter in getCollection() not after
   • Use getEntry() for single items
   • Cache results when possible
   • Minimize data fetched per query

3. Frontmatter Validation:

   • Validate during build time
   • Provide clear error messages
   • Test with invalid data
   • Document required fields

4. Content Organization:

   • Group by collection type
   • Use consistent slug patterns
   • Separate drafts with boolean flag
   • Version control all content

Troubleshooting

Common issues and solutions documented in examples/error-handling.md:

• Schema validation errors
• Type generation failures
• Query performance issues
• Frontmatter parsing errors
• Content not appearing

Related Skills

• mdx-integration - MDX component usage in content
• image-optimization - Image handling in content
• seo-optimization - SEO for content collections
• static-generation - Static site generation patterns

---

Skill Version: 1.0.0 Last Updated: 2025-10-28 Plugin: website-builder