How to Migrate Your WordPress Site to Astro Step by Step

You’ve decided to move from WordPress to Astro. Maybe you’re tired of plugin updates, slow load times, or security patches. Maybe you’ve seen the performance comparison and want top Lighthouse performance.

This guide walks you through the entire migration process. We’ve done this dozens of times across our agency clients, and we’ll share the exact workflow we use.

Before You Start

Audit your current site. Before touching anything, document what you have:

1. Page inventory: List every URL on your WordPress site. Use Screaming Frog, Sitecrawler, or your existing sitemap (/sitemap_index.xml)
2. Content types: Pages, posts, custom post types, categories, tags
3. Functionality: Contact forms, search, comments, ecommerce, membership
4. Plugins: List every active plugin and what it does. Most can be replaced with Astro equivalents or eliminated entirely
5. Traffic sources: Check Google Analytics for your top 50 pages by organic traffic. These are the pages you cannot afford to break during migration

Set a realistic timeline. A 20-page business site takes 1-2 days. A 200-page blog with custom post types takes 1-2 weeks. Factor in testing and redirect verification.

Step 1: Export WordPress Content

Export Posts and Pages to Markdown

WordPress stores content in its database. You need to extract it as Markdown files for Astro.

Option A: WP to Markdown plugin

Install the “WordPress to Markdown Exporter” plugin. It exports posts and pages as Markdown files with YAML frontmatter.

Option B: Script-based export

Export your WordPress content as XML (Tools > Export > All Content), then convert to Markdown:

npx wordpress-export-to-markdown --input export.xml --output src/content/

This converts posts, pages, and metadata to Markdown with frontmatter. Review the output for formatting issues - complex WordPress blocks don’t always convert cleanly.

Export Images

Download your wp-content/uploads/ directory. Reorganize images into a flat structure under public/images/ in your Astro project. Update image paths in your Markdown files to match.

# Download all uploaded media
rsync -avz user@server:/var/www/html/wp-content/uploads/ ./public/images/uploads/

Step 2: Set Up Your Astro Project

Start with a template that matches your site type. The Wumty Starter Kit gives you the base structure with dark mode, SEO, and responsive layouts. The Single Site adds content collections, blog, forms, and structured data.

# Clone the starter
git clone https://github.com/wumty/starter.git my-new-site
cd my-new-site
pnpm install

Configure Your Site

Update src/config/site.json with your domain, branding, and metadata:

{
  "title": "Your Site Name",
  "base_url": "https://yoursite.com",
  "siteName": "Your Site",
  "logo": "/images/your-logo.svg"
}

Set Up Content Collections

Define Zod schemas that match your WordPress content structure. See our Content Collections guide for detailed examples.

// src/content.config.ts
const blogCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    date: z.date(),
    categories: z.array(z.string()).default([]),
    image: z.string().optional(),
    draft: z.boolean().default(false),
  }),
});

Step 3: Migrate Content

Blog Posts

Place your exported Markdown files in src/content/blog/. Clean up the frontmatter to match your Zod schema:

---
title: "Your Post Title"
description: "A concise description for SEO"
date: 2025-06-15
categories: ["tutorial"]
image: "/images/uploads/post-image.jpg"
---

Common cleanup tasks:

• Remove WordPress-specific shortcodes ([gallery], [contact-form])
• Fix image paths (from /wp-content/uploads/ to /images/uploads/)
• Convert HTML blocks to Markdown
• Add missing descriptions (WordPress often lacks meta descriptions)

Pages

Static pages (About, Contact, Privacy Policy) go in src/content/pages/ or directly in src/pages/. For pages with structured sections (hero, features, testimonials), use frontmatter sections that map to Astro components.

Categories and Tags

Map WordPress categories to your content collection’s category field. If you had 30 WordPress categories and only 5 matter, consolidate. Fewer, well-defined categories are better for SEO than dozens of thin ones.

Step 4: Preserve SEO (Critical)

This is where most migrations go wrong. Lose your SEO equity and you lose months of organic traffic.

URL Mapping

Create a complete mapping from old WordPress URLs to new Astro URLs:

WordPress URL                    → Astro URL
/2024/06/15/my-post-title/      → /blog/my-post-title/
/category/tutorials/             → /blog/ (filtered)
/about-us/                       → /about/
/services/web-design/            → /services/web-design/

WordPress often uses date-based URLs (/2024/06/15/slug/). Astro typically uses flat URLs (/blog/slug/). Both work, but you must set up redirects for the old URLs.

Set Up 301 Redirects

For Netlify, create a public/_redirects file:

/2024/06/15/my-post-title/   /blog/my-post-title/   301
/category/tutorials/          /blog/                  301
/about-us/                    /about/                 301
/feed/                        /rss.xml                301
/wp-admin/                    /404                    410
/wp-login.php                 /404                    410

For Vercel, use vercel.json:

{
  "redirects": [
    { "source": "/2024/06/15/my-post-title/", "destination": "/blog/my-post-title/", "statusCode": 301 }
  ]
}

Do not skip redirects. Every indexed URL that returns a 404 loses whatever PageRank it had accumulated. 301 redirects transfer that equity to the new URL.

Preserve Meta Tags

Ensure every migrated page has:

• The same (or improved) title tag
• A meta description (add one if WordPress didn’t have one)
• Open Graph image
• Canonical URL pointing to the new URL

Submit Updated Sitemap

After deployment, submit your new sitemap to Google Search Console. Google will discover the redirects and start indexing the new URLs. Monitor the “Coverage” report for 404 errors from old URLs you missed.

Step 5: Handle WordPress Features

Contact Forms

Replace WordPress contact form plugins (Contact Form 7, Gravity Forms) with a serverless form handler. Wumty templates include a built-in form component with API integration. Alternatives include Netlify Forms, Formspree, or a custom serverless function.

Search

WordPress has built-in search powered by its database. For a static Astro site, use:

• Pagefind: Client-side search that indexes your static HTML at build time (0 dependencies, ~50KB)
• Algolia: Managed search service for larger sites

Comments

If you had WordPress comments, migrate to:

• Giscus: GitHub-backed discussions (developer audiences)
• Disqus: General-purpose comment system
• Or remove comments entirely - most business sites don’t need them

RSS Feeds

WordPress generates RSS at /feed/. Add the Astro RSS integration:

pnpm add @astrojs/rss

Create src/pages/rss.xml.ts to generate your feed. Redirect /feed/ to /rss.xml in your redirects file.

Step 6: Test Before Switching DNS

Deploy your Astro site to a staging URL (Netlify preview, Vercel preview) and verify:

1. Every page renders correctly - spot-check at least the top 20 pages by traffic
2. All redirects work - test old URLs and confirm they 301 to new URLs
3. Meta tags are correct - use the browser dev tools or an SEO crawler
4. Structured data validates - test with Google’s Rich Results Test
5. Lighthouse scores meet expectations - run audits on key pages
6. Forms work - submit test entries
7. Images load - check for broken image paths from the migration

Step 7: Go Live

1. Point your domain to the new host (update DNS records)
2. Verify HTTPS is working
3. Submit the new sitemap to Google Search Console
4. Monitor Search Console daily for the first two weeks
5. Watch for crawl errors, indexing drops, or ranking changes

Expect a temporary traffic dip. Google needs time to process redirects and re-index your content. Most sites recover within 2-4 weeks. If you preserved URLs and set up redirects correctly, the dip should be minimal.

Common Migration Mistakes

1. Forgetting redirects - The #1 cause of post-migration traffic loss
2. Changing URLs without redirects - Even “small” URL changes need 301s
3. Losing meta descriptions - WordPress plugins like Yoast store descriptions that don’t export automatically
4. Breaking internal links - Update all internal links to use new URL structure
5. Ignoring WordPress RSS subscribers - Redirect /feed/ to your new RSS URL
6. Not monitoring after launch - Check Search Console daily for two weeks

Need Help Migrating?

The Wumty Agency Kit includes a Node.js migration script that automates scaffolding, config merging, and content conversion. It handles the tedious parts so you can focus on customization.

For a single site, the Single Site gives you the destination template with content collections, blog, forms, and structured data already configured. Start with the free Starter Kit if you want to test the waters first.

The SEO Toolkit preserves your structured data during migration, while the Theme System gives you dark mode and design tokens without writing CSS. Read more about why agencies are switching from WordPress or see how we manage 15+ migrated sites from one codebase.

---

Migrating from WordPress? The free Starter Kit gives you a production-ready Astro foundation. For agencies moving multiple client sites, the Agency Kit includes migration tooling and monorepo architecture.