/astro-content

name: astro-content
description: Use when managing structured content, blog posts, or typed data collections in Astro via the Content Layer API (content.config.ts).
versions:
  astro: 7
  zod: 4
user-invocable: true
references: references/overview.md, references/config.md, references/loaders.md, references/querying.md, references/rendering.md, references/mdx.md, references/templates/blog-collection.md, references/templates/custom-loader.md
related-skills: astro-7, astro-actions, astro-seo

<objective> Implements Astro's Content Layer API: the `src/content.config.ts` config file, built-in `glob()` and `file()` loaders for local Markdown/MDX/JSON/YAML content, custom loaders for remote APIs/CMS/databases, Zod 4 schemas for type-safe frontmatter, and the query APIs `getCollection()`, `getEntry()`, and `render()` (which returns a `Content` component plus headings).

Also covers MDX authoring with Remark/Rehype plugins and the `astro sync` workflow for generating collection types. Does not cover form submission via Astro Actions (astro-actions) or SEO metadata generation from content (astro-seo) — those are handled by their own skills. </objective>

Astro Content Layer Expert

Type-safe content management with loaders, Zod schemas, and the unified Content Layer API.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Check existing collections, loaders, and content structure 2. **fuse-ai-pilot:research-expert** - Verify latest Content Layer docs via Context7/Exa 3. **mcp__context7__query-docs** - Get loader and schema examples

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

Overview

When to Use

• Managing blog posts, docs, or product descriptions in Markdown/MDX
• Fetching content from a CMS, API, or database with type safety
• Needing TypeScript autocomplete for frontmatter fields
• Migrating from Astro 4 legacy content collections

Why Content Layer API

| Feature | Benefit | |---------|---------| | `src/content.config.ts` | Single config file at project root | | Built-in loaders | `glob()` and `file()` for local files | | Custom loaders | Fetch from any external source | | Zod 4 schemas | Full TypeScript type safety | | `astro sync` | Generates types from collections |

---

Core Concepts

Config File Location

The config file moved from `src/content/config.ts` to `src/content.config.ts` in Astro 5+.

Collection Types

| Loader | Use Case | |--------|----------| | `glob()` | Multiple files in a directory (MD, MDX, JSON, YAML) | | `file()` | Single JSON/YAML file with multiple entries | | Custom | Remote API, database, or any async data source |

Key APIs

| API | Description | |-----|-------------| | `getCollection(name)` | Fetch all entries in a collection | | `getEntry(name, id)` | Fetch a single entry by ID | | `render(entry)` | Render a content entry to HTML + headings | | `defineCollection()` | Define a collection with loader and schema |

---

Reference Guide

| Need | Reference | |------|-----------| | Overview & concepts | [overview.md](references/overview.md) | | Config file setup | [config.md](references/config.md) | | Glob, file, custom loaders | [loaders.md](references/loaders.md) | | getCollection / getEntry | [querying.md](references/querying.md) | | render() + headings | [rendering.md](references/rendering.md) | | MDX + Remark/Rehype | [mdx.md](references/mdx.md) | | Blog collection example | [templates/blog-collection.md](references/templates/blog-collection.md) | | Custom remote loader | [templates/custom-loader.md](references/templates/custom-loader.md) |

---

Best Practices

1. **Always define schemas** — Never skip Zod validation 2. **Run `astro sync`** — After changing `content.config.ts` 3. **Use `glob()` for local files** — Supports MD, MDX, JSON, YAML, TOML 4. **Custom loaders for remote data** — CMS, REST API, GraphQL 5. **`render()` for MDX** — Returns `Content` component + headings array