# Prompt-to-PR: Construye un sitio SEO estático con Astro
> SOP completo para crear desde cero un sitio SEO estático basado en contenido con Astro, Tailwind, colecciones de contenido MDX, mapa del sitio y etiquetas canónicas.
**Type:** Playbook
**Tools:** Cursor, Claude Code, Codex, Windsurf
**Stack:** Astro, TypeScript, Tailwind
**Difficulty:** medium
**Updated:** 2026-06-08
---
Crea un sitio Astro 5 completamente estático y listo para producción, optimizado para búsqueda orgánica: colecciones de contenido, tipografía de Tailwind, `@astrojs/sitemap` y metadatos `` correctos desde el primer día.
## 1. Requisito
Construye un sitio de marketing/contenido estático que obtenga 100 en SEO y Accesibilidad de Lighthouse. El contenido se escribe en archivos MDX administrados por las colecciones de contenido de Astro. No se necesita un framework de JavaScript: la salida es HTML+CSS puro con islas optativas.
## 2. Primer Prompt
```txt title="First Prompt"
Scaffold a new Astro 5 static SEO site from scratch in the current directory.
Requirements:
1. Init with: `bunx create astro@latest . --template minimal --typescript strict --no-git`
2. Add integrations:
- `@astrojs/tailwind` with `@tailwindcss/typography`
- `@astrojs/sitemap`
- `@astrojs/mdx`
3. Create a content collection `blog` in `src/content/blog/` with this Zod schema:
title, description, pubDate (Date), updatedDate (Date, optional),
author (string, default "Admin"), tags (string[], default []), draft (bool, default false).
4. Create a BaseLayout.astro with:
- A `` block: charset, viewport, canonical (`Astro.url.href`),
og:title, og:description, og:url, og:type, twitter:card.
- Accept `title`, `description`, `image` props.
5. Create pages:
- `/` — hero + last 6 non-draft posts
- `/blog` — paginated list (10 per page) using `paginate()`
- `/blog/[slug]` — single post rendered with ``
- `/tags/[tag]` — posts filtered by tag
6. Create `src/content/blog/hello-world.mdx` as a real sample post.
7. Configure `astro.config.ts`:
- `site: process.env.SITE_URL ?? "http://localhost:4321"`
- `integrations: [tailwind(), sitemap(), mdx()]`
- `output: "static"`
8. Add a `.env.example` with `SITE_URL=https://example.com`.
```
## 3. Cambios de archivos esperados
```txt
astro.config.ts
tailwind.config.ts
src/content.config.ts (blog collection schema)
src/layouts/BaseLayout.astro (head + canonical + OG tags)
src/pages/index.astro
src/pages/blog/index.astro (paginated)
src/pages/blog/[slug].astro
src/pages/tags/[tag].astro
src/content/blog/hello-world.mdx
.env.example
package.json (updated with all integrations)
```
## 4. Lista de verificación
- `astro.config.ts` establece `site` — necesario para que `@astrojs/sitemap` emita URLs absolutas.
- `BaseLayout.astro` genera un `` usando `Astro.url.href`.
- La página de lista del blog usa `Astro.props.page.data` de `paginate()` — no una llamada directa a `getCollection()`.
- Los borradores (`draft: true`) se excluyen en producción mediante la comprobación de `import.meta.env.PROD`.
- Se establece `` en el elemento raíz.
- `tailwind.config.ts` incluye el plugin `typography` y apunta a `src/**/*.{astro,mdx}`.
- La integración de `sitemap()` está presente — verifica que `dist/sitemap-index.xml` exista después de ejecutar `bun run build`.
## 5. Comandos de prueba
```bash
bun install
bun run dev
# visit http://localhost:4321 and confirm hero + posts render
bun run build
# expect zero errors
bun run preview
# check /sitemap-index.xml and /sitemap-0.xml exist
# check /blog and /blog/hello-world render with correct and canonical
# Lighthouse CLI smoke test (optional)
bunx lighthouse http://localhost:4321 --output json --quiet | jq '.categories.seo.score'
# expect 1 (100%)
```
## 6. Fallos comunes
- **El mapa del sitio genera URLs relativas** — falta `site` en `astro.config.ts`. Agrégalo.
- **`getCollection` devuelve borradores en producción** — filtra: `posts.filter(p => !p.data.draft || !import.meta.env.PROD)`.
- **Error 404 de paginación en `/blog`** — la primera página debe ser `/blog/` (índice), no `/blog/1`. Por defecto, `paginate()` de Astro genera `/blog/`, `/blog/2/`, etc.
- **Contenido MDX sin estilo** — falta la clase `prose` de `@tailwindcss/typography` en el envoltorio del artículo en `[slug].astro`.
- **Las etiquetas OG usan una ruta de imagen relativa** — debe ser una URL absoluta. Prefija con `Astro.site`.
## 7. Prompt de corrección
```txt title="Fix Prompt"
The sitemap at /sitemap-0.xml contains relative paths like "/blog/hello-world"
instead of absolute URLs like "https://example.com/blog/hello-world".
Fix: add `site: "https://example.com"` (or `process.env.SITE_URL`) to the
top-level astro.config.ts object. The sitemap integration reads this value
to prefix all URLs.
```
## 8. Descripción del PR
```md title="PR description"
## Init: Static Astro 5 SEO site
- Astro 5 + TypeScript strict + Tailwind (with `@tailwindcss/typography`)
- `@astrojs/sitemap` and `@astrojs/mdx` integrations
- Content collection `blog` with Zod schema (title, description, pubDate, tags, draft)
- BaseLayout with canonical, OG, and Twitter Card meta tags
- Pages: home, paginated blog list, single post, tag archive
- Sample `hello-world.mdx` post
- `bun run build` emits `sitemap-index.xml` and all static pages
```