# Astro SEO for AI agents

Astro ships zero client JavaScript by default, making it naturally readable to search and AI crawlers when configured well. Pairing Astro with clickd lets your agent enforce strict Content Collection frontmatter rules, canonical URLs, JSON-LD and `/llms.txt` endpoints.

- Install skills: `npx skills add subinternal/clickd`
- Ask your agent: "Audit our Astro site with clickd_brief, enforce title and description lengths in src/content.config.ts, wire JSON-LD in BaseHead.astro, and rescan."
- MCP tools used: `clickd_brief`, `clickd_pages`, `clickd_schema_create`, `clickd_rescan`

## What breaks most often on Astro

- **Unchecked Content Collection frontmatter** (`description`): Markdown and MDX entries drift outside 15 to 65 character titles and 70 to 160 character descriptions unless validated in Zod schemas.
- **Missing site URL for canonicals and sitemaps** (`canonical`): When `site` is unset or mismatched in `astro.config.mjs`, `Astro.url` canonicals and `@astrojs/sitemap` point to localhost or staging domains.
- **Guides opening with throat-clearing intros** (`answer-first`): Long MDX posts bury the answer four paragraphs below the heading instead of opening with a 40 to 60 word direct answer.

## The Astro agentic SEO loop

1. **Audit live output** (`clickd_brief`): Check the deployed Astro site with clickd_brief to catch broken links, duplicate titles, missing schema and answer-first misses.
2. **Lock Zod schemas** (`on-page-seo`): Enforce title, description, publishDate and updatedDate constraints inside `src/content.config.ts` so bad metadata fails the build.
3. **Shared BaseHead & endpoints** (`schema-markup`): Emit canonical tags, Open Graph tags and escaped JSON-LD in `BaseHead.astro`, plus `/llms.txt.ts` from collection entries.
4. **Build & rescan** (`clickd_rescan`): Run `astro check && astro build`, deploy, and run clickd_rescan to confirm every collection page passes.

## Worked pattern (src/content.config.ts)

Zod frontmatter validation keeps every Astro guide inside clickd’s title and description rules at build time.

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

const guides = defineCollection({
  schema: z.object({
    title: z.string().min(15).max(52), // leaves room for " · Brand" under 65 chars
    description: z.string().min(70).max(160),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});

export const collections = { guides };
```

## Prompts to run on Astro

- **Enforce SEO in Astro collections**: "Add Zod length checks for title and description in src/content.config.ts and fix every Markdown/MDX entry that fails."
- **Add BaseHead JSON-LD & breadcrumbs**: "Wire Article, BreadcrumbList and Organization JSON-LD into our shared Astro layout and check the live pages with clickd."
- **Build src/pages/llms.txt.ts**: "Create an Astro endpoint at src/pages/llms.txt.ts generated from getCollection() so /llms.txt stays in sync with our sitemap."

## Paired skills

- [Page system](https://clickd.com/skills/page-system): Builds a site’s page templates and shared components so crawlers and assistants read every page well, and proves each pattern with clickd. About structure and spacing, not color, type or brand.
- [On-page SEO](https://clickd.com/skills/on-page-seo): Rewrites title tags, meta descriptions, single H1s, question headings, answer-first openings, image alt text and AI writing tells in your site’s templates and content files, checked live with clickd.
- [Schema markup](https://clickd.com/skills/schema-markup): Generates, wires and validates JSON-LD structured data (Organization, LocalBusiness, Product, Service, Article, FAQPage and BreadcrumbList) from the visible facts on your pages, checked live with clickd.
- [llms.txt](https://clickd.com/skills/llms-txt): Adds a /llms.txt to a site, a plain text outline for AI assistants built from the site’s own pages and facts, with tests that catch a missing page, and checks it with clickd.

## Questions

### Why run clickd on an Astro site if Astro already outputs static HTML?

Static HTML solves JavaScript rendering, not metadata quality, orphan pages, broken links, missing JSON-LD or buried answers. clickd grades all 45 rules across Access, Understand, Trust and Act on your live build.

### Can an Astro endpoint generate `/llms.txt` automatically at build time?

Yes. Adding `src/pages/llms.txt.ts` reading from `getCollection()` compiles `/llms.txt` statically on every build so a new guide can never be missing from the file.