⇤ BACK

WordPress to Astro Migration: The 3-Hour Method

Why Migrate?

  • WPEngine/Managed WordPress: $30-500+/month
  • Cloudflare Pages: $0/month (yes, free)
  • Performance: 10x faster load times
  • Security: No WordPress vulnerabilities, no plugin updates

What You Get with Cloudflare Pages (FREE)

  • Unlimited bandwidth
  • Global CDN with 300+ edge locations
  • Automatic SSL certificates
  • DDoS protection
  • Instant cache invalidation
  • Preview deployments for every git branch
  • Analytics included
  • Web Application Firewall (WAF)

Tools Required

  1. Astro MCP for Claude Code (the only MCP you need)
  2. Browser (to save reference HTML)
  3. WordPress (with export functionality)

Step 1: Export WordPress Content (30 minutes)

From WordPress Admin

Dashboard → Tools → Export → All Content

This gives you an XML file with everything - posts, pages, custom fields, categories, tags.

Claude Code Prompt to Parse

Give Claude Code the XML file with this prompt:

Parse this WordPress XML export.
Create markdown files with this structure:

---
title: [from <title>]
date: [from <wp:post_date>]
categories: [from <category>]
tags: [from <tag>]
author: [from <dc:creator>]
excerpt: [from <excerpt:encoded> or first paragraph]
---

[Convert content:encoded HTML to markdown]

Save each as: /content/blog/[slug].md

What Claude Handles Automatically

  • HTML to Markdown conversion
  • Shortcode removal
  • Image path updates
  • Special character encoding
  • Frontmatter generation
  • URL slug creation

Step 2: Capture Design Reference (15 minutes)

Save These WordPress Pages as Static HTML

In Chrome: File → Save Page As → “Webpage, Complete”

  1. Homepage (index.html)
  2. Blog listing page
  3. Single blog post
  4. About page
  5. Contact page (if you have one)

Store these in a /reference folder for Claude to analyze.

Step 3: Rebuild with Claude Code + Astro MCP (2 hours)

Prompt 1: Initial Analysis

Analyze these WordPress HTML files:
- homepage.html
- blog-listing.html
- single-post.html
- about.html

Identify:
1. Common header/footer elements
2. Unique sections per page
3. Repeating patterns (cards, lists, sidebars)
4. Design system (colors, fonts, spacing)
5. Interactive elements (menus, modals)

Prompt 2: Create Component Architecture

Based on this WordPress site analysis, create an Astro component structure.

Requirements:
- Reusable components for repeated elements
- TypeScript interfaces for all props
- Tailwind CSS for styling
- Mobile-responsive by default
- Accessibility best practices (ARIA labels, semantic HTML)
- SEO component for meta tags

Prompt 3: Build Core Components

Header Component

Create Header.astro from the WordPress header.
Include:
- Logo/site title
- Desktop navigation menu
- Mobile hamburger menu with toggle
- Active page highlighting
- Sticky header option

Blog Card Component

Extract the blog post preview from blog-listing.html.
Create BlogCard.astro that accepts:
- title (required)
- excerpt (required)
- date (required)
- author (optional)
- featuredImage (optional - handle missing gracefully)
- categories (array)
- slug (required)

Add hover states and consistent spacing.

Layout Components

Create two layout files:

1. BaseLayout.astro
- Import Header and Footer components
- Include SEO component
- Accept title and description props
- Add Google Fonts or Typekit if needed
- Include global CSS

2. BlogLayout.astro  
- Extend BaseLayout
- Add article schema markup
- Include author bio section
- Add related posts section
- Include social share buttons

Prompt 4: Content Collections Setup

Set up Astro content collections for the blog posts.

Create src/content/config.ts with schema:
- title: z.string()
- date: z.date()
- author: z.string().optional()
- excerpt: z.string()
- categories: z.array(z.string())
- tags: z.array(z.string()).optional()
- featuredImage: z.string().optional()

Prompt 5: Dynamic Routing

Create dynamic blog post routing in src/pages/blog/[...slug].astro

Requirements:
- Generate static paths from content collection
- Pass post data to BlogLayout
- Handle 404 for invalid slugs
- Add previous/next post navigation

Step 4: Deploy to Cloudflare Pages (15 minutes)

Push to GitHub

git init
git add .
git commit -m "Initial Astro migration from WordPress"
git branch -M main
git remote add origin [email protected]:yourusername/your-site.git
git push -u origin main

Connect Cloudflare Pages

  1. Log in to Cloudflare Dashboard
  2. Go to Pages
  3. Create a Project → Connect to Git
  4. Select your repository
  5. Configure build settings:
    • Build command: npm run build
    • Build output directory: dist
    • Node version: 18 or higher

Questions or Issues?

This guide is based on real migrations I’ve completed. The process works for most WordPress sites that are primarily content-based.

For WooCommerce or membership sites, you’ll need additional considerations.