---
name: astro-static-content
description: "Use when building, refactoring, or reviewing a Astro Static Site + Content Collections + Tailwind project (Astro, Tailwind CSS, TypeScript, MDX, Cloudflare). Rules for a fully static Astro 7 site: content collections with Zod schemas, zero-JS pages with rare islands, build-time sitemap and OG images, and static hosting on Cloudflare."
license: MIT
metadata:
  source: https://stackitfast.com/rules/astro-static-content
  version: "2026-10-04"
---

# Astro Static Site + Content Collections + Tailwind — Agent Skill

## When to use this skill
- Any task that scaffolds, modifies, refactors, or reviews code in a Astro Static Site + Content Collections + Tailwind codebase.
- Whenever the project depends on Astro, Tailwind CSS, TypeScript, MDX, Cloudflare.
- Apply these guidelines before proposing architecture, database, or deployment changes.

## Guidelines
# Project Architecture & Guidelines (Astro Static + Content Collections)

## 1. System Architecture
- **Framework**: Astro 7 with `output: 'static'` (the default). No server adapter; every route is HTML at build time.
- **Content**: Content collections defined in `src/content.config.ts` with the `glob()` and `file()` loaders and a Zod schema per collection.
- **Styling**: Tailwind CSS with a small token set in the config; no runtime CSS-in-JS.
- **Interactivity**: Astro components by default. A React, Svelte or Vue island only where state must survive after load, hydrated with `client:visible` or `client:idle`, never `client:load` by habit.
- **Hosting**: Static files on Cloudflare (Workers static assets or Pages). No functions unless a form or API genuinely needs one.
- **Runtime**: Node 22.12+ for the build (Astro 6 dropped Node 18 and 20).

## 2. File Layout
- `src/content.config.ts`: Every collection, its loader and its schema in one file.
- `src/content/<collection>/`: Markdown or MDX entries; file name is the slug.
- `src/pages/`: File-based routes. Dynamic routes export `getStaticPaths()` built from `getCollection()`.
- `src/layouts/Base.astro`: The only place that writes `<head>`: title, description, canonical, Open Graph, JSON-LD.
- `src/components/`: `.astro` components; islands live in `src/components/islands/` so they are easy to count.
- `src/pages/sitemap.xml.ts`, `rss.xml.ts`, `og/[...slug].png.ts`: Build-time endpoints, prerendered like pages.

## 3. Content Rules
- Every frontmatter field is in the collection schema. Adding a field means changing the schema first; the build fails on missing or mistyped fields.
- Use `z.coerce.date()` for dates and `reference()` for links between collections instead of raw slugs.
- Query with `getCollection()` / `getEntry()` and render with `render(entry)`. The legacy `getEntryBySlug()` API was removed in Astro 6.
- Drafts use a `draft: z.boolean().default(false)` field filtered out in one helper, not in every page.

## 4. SEO & Performance
- One layout owns all meta tags; pages pass `title`, `description` and `image` props, never raw `<meta>`.
- Canonical URLs match the served URLs exactly (pick a trailing-slash policy in `astro.config.mjs` and the host, and keep them aligned).
- Generate the sitemap, RSS feed and OG images at build time. Nothing about a static page should be computed per request.
- Use `astro:assets` `<Image />` for local images so width, height and modern formats are emitted at build.

## 5. Coding Standards
- Strict TypeScript (`astro/tsconfigs/strict`), zero `any`.
- Keep logic out of `.astro` templates: data shaping goes in `src/lib/*.ts`, which can be unit tested.
- No client-side router, no global state library, no CMS until the content outgrows a folder of Markdown.

## 6. Testing Conventions
- `astro check` and `astro build` are the test suite for content: both must pass in CI.
- Unit test `src/lib/` helpers (slugs, dates, sorting) with Vitest.
- Add a build-time assertion for the invariants that matter, e.g. every indexable page has a canonical URL and a description under 160 characters.

## 7. Git Workflow & PR Conventions
- Conventional Commits scoped to the area: `feat(blog): add series field`, `fix(seo): canonical for paginated lists`.
- A schema change and the content edits it requires land in the same PR.
- Preview deploys per PR; review the rendered page, not only the Markdown diff.

## Source
Maintained at https://stackitfast.com/rules/astro-static-content — also available as AGENTS.md, CLAUDE.md, and Cursor .mdc.