lfurze Astro Website Builder
Build polished, multi-page static websites from provided content using Astro 5, deployed to Cloudflare Pages with custom domains.
When This Skill Applies
The user provides content in one of these forms (placed in the project root before starting):
- Markdown (.md) articles
- A PDF or eBook on a topic
- A collection of text files on a theme
- A WordPress XML export
- Sometimes just a topic and verbal description
The job is to transform that into a professional, fast, accessible website.
Before Starting: Gather Requirements
Ask these questions (skip any already answered):
- Site name and domain — What's it called? What custom domain? (e.g., myproject.com)
- Purpose and audience — Who is this for?
- Content sections — What pages should the site have? (Suggest a structure based on the provided content)
- Theme preference — Dark mode default, light mode, or both with toggle? Color preferences?
- Font style — Editorial/serif, clean modern, or technical? (See
references/design-tokens.mdfor options)
Project Initialization
Run in the empty project folder:
npm create astro@latest . -- --template minimal --typescript strict --install --git --no
npm install @astrojs/sitemap marked sanitize-html
Create the folder structure:
src/
├── components/ # Header, Footer, cards, reusable UI
├── layouts/ # BaseLayout.astro
├── pages/ # File-based routes
├── data/ # Content as TypeScript arrays
├── styles/ # global.css
└── utils/ # Helpers (if needed)
public/
├── images/
├── fonts/ # Self-hosted fonts (if any)
├── favicon.svg
├── favicon.ico
├── robots.txt
└── _headers
Create these config files:
astro.config.mjs:
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://[your-domain.com]',
integrations: [sitemap()],
});
wrangler.jsonc:
{
"name": "[project-name]",
"compatibility_date": "[YYYY-MM-DD]",
"assets": { "directory": "./dist" }
}
tsconfig.json — use Astro's strict preset with path alias:
{
"extends": "astro/tsconfigs/strict",
"include": [".astro/types.d.ts", "**/*"],
"exclude": ["dist"],
"compilerOptions": { "paths": { "@/*": ["src/*"] } }
}
Then create CLAUDE.md (read references/claude-md-template.md) and DESIGN.md (read references/design-tokens.md and customize for the project).
Content Processing
Step 1: Read the source material
Scan the project root for content files. Read all of them to understand scope, themes, and structure.
Step 2: Plan information architecture
A typical site has: Home, core content pages (articles/chapters/resources), About, Contact, and a 404 page. For larger content sets, add topic indexes, dynamic [slug].astro routes, resource pages, or case studies. Propose the structure to the user before building.
Step 3: Transform content into TypeScript data
Structure all content as typed TypeScript arrays in src/data/. This is the established pattern — TypeScript data files, not markdown content collections.
// src/data/articles.ts
export interface Article {
slug: string;
title: string;
date: string;
excerpt: string;
content: string; // Full markdown content as string
image?: string;
imageCredit?: string;
tags?: string[];
categories?: string[];
section?: string;
}
export const articles: Article[] = [ /* populated from source content */ ];
For markdown files: extract title from first heading, generate slug, create excerpt from first paragraph, store full content as markdown string.
For PDFs: extract text, identify chapters/sections, split into logical articles.
Step 4: Build pages
Read references/component-patterns.md before building components. Key architecture:
BaseLayout.astro wraps every page with: HTML document setup, SEO meta tags (title, description, Open Graph, Twitter Cards), canonical URLs, theme initialization (inline script in <head> to prevent flash), font loading, global CSS import, skip-to-main-content link, and Header + <main> slot + Footer.
Dynamic routes for collections:
---
// src/pages/articles/[slug].astro
import { articles } from '../../data/articles';
export function getStaticPaths() {
return articles.map(a => ({ params: { slug: a.slug }, props: { article: a } }));
}
const { article } = Astro.props;
---
Markdown rendering uses marked + sanitize-html for security. See references/component-patterns.md for the sanitization config.
Styling Approach
Read references/design-tokens.md before writing any CSS. Key principles:
- No Tailwind — custom CSS with CSS custom properties
- "Barely-there UI" — minimal chrome, let content breathe
- Fluid typography —
clamp()for responsive headings - Glass border effect — conic gradient + mask compositing on cards
- Cursor-following image zoom on card images
- Smooth easing —
cubic-bezier(0.16, 1, 0.3, 1)everywhere - Accessibility — skip links, focus-visible, prefers-reduced-motion
Theme toggle (if applicable): data-theme attribute on <html>, localStorage persistence, inline <script> in <head> to set before render.
SEO
Every site includes: meta tags in BaseLayout, Open Graph + Twitter Card tags, canonical URLs, JSON-LD structured data on article pages, sitemap via @astrojs/sitemap, robots.txt, and semantic HTML throughout.
Deployment
Build: npm run build. Production deployment is GitHub → Cloudflare Pages auto-deploy on push to main.
Cloudflare setup: push repo to GitHub → Cloudflare Pages → Create → Connect to Git → build command npm run build, output dist → add custom domain in settings.
Stability Checklist
Before considering complete: all pages render, build succeeds, no TS errors, images lazy-loaded, SEO meta on all pages, sitemap works, 404 page exists, mobile responsive (375/768/1024/1440px), keyboard nav works, no console errors, theme toggle works (if applicable), all source content included.
Reference Files
Read these before building:
references/design-tokens.md— Full design system: colors, typography, spacing, glass borders, animation, responsive breakpointsreferences/component-patterns.md— Established component patterns: Header, Footer, cards, layouts, prose styling, modalsreferences/claude-md-template.md— Template for the project's CLAUDE.md file