wordpress-blog-to-astro

WordPress to Astro Migration Skill

A Claude Code skill for migrating WordPress blogs to Astro static sites. Built from real migrations across multiple sites — a personal blog with 180+ posts (pmillerd.com), a book/podcast site with 120+ posts (pathlesspath.com), a bilingual podcast/blog (angiecreates.io), and a consulting content site (strategyu.co).

pmillerd.com	pathlesspath.com

strategyu.co	angiecreates.io

What This Skill Does

When you invoke /wordpress-to-astro in any project, Claude gets loaded with the full migration playbook: a 7-phase pipeline, ready-to-customize script templates, and a troubleshooting guide covering dozens of real issues.

Claude will walk you through the migration step by step, asking the right questions upfront and adapting scripts to your specific site.

Install

Personal (just you):

# Copy skill files to your local Claude skills directory
mkdir -p ~/.claude/skills/wordpress-to-astro
# Then copy SKILL.md, migration-scripts.md, common-issues.md, post-migration-patterns.md into it

As a plugin (shareable):

/install github:paulmil11/wordpress-blog-to-astro-skill

How It Works

The Migration Pipeline

The skill guides Claude through 7 phases, run in order:

1. Extract — Parse your WordPress XML export into structured JSON. Pulls out titles, slugs, dates, categories, tags, featured images (via _thumbnail_id postmeta lookup), and full HTML content.

2. Convert — Transform WordPress HTML to clean Markdown using Turndown with custom rules. Preserves YouTube/podcast/Substack embeds as raw HTML. Strips WordPress block comments, spacer blocks, and page builder wrappers. Generates YAML frontmatter with dual date fields (date for display, rawDate for sorting).

3. Download Images — Scan all markdown for external image URLs, download them locally to public/images/posts/, and rewrite all references. Handles CDN redirects (up to 5 hops), tracks failures, and is idempotent (safe to re-run).

4. Clean Up — Remove boilerplate (host social links, platform CTAs, subscription prompts) while intelligently preserving guest content. Standardize categories. Fix broken links from old domains. Normalize percent-encoded CJK filenames. Fix protocol-relative URLs in embeds. Convert bare Twitter/X URLs to markdown links.

5. Generate Missing Content — Auto-create landing pages for content that exists in external feeds (podcast RSS, newsletters) but has no blog post yet. Match by episode number, inject embed players.

6. Build & Deploy — Verify the Astro build, configure platform-specific redirects (Netlify _redirects, Vercel vercel.json, Cloudflare Pages), and deploy. For domain migrations, generate WordPress Redirection plugin CSV for the old site.

7. Post-Migration Polish — Fix remaining broken internal links, build standalone pages from old site content (coaching, reading lists, tools pages), implement dark mode, add blog page features (category filtering, search, sort by reading time), visual polish (gradient transitions, responsive layouts).

What Claude Asks You First

Before writing any code, the skill prompts Claude to ask about your specific setup:

Question	Why It Matters
Source platform — WordPress.com or self-hosted?	Affects XML export structure and image URL patterns
Hosting target — Cloudflare Pages, Vercel, or Netlify?	Determines redirect config format and deploy setup
Content types — Blog only? Podcast? Events? Portfolio?	Controls which scripts get created
Languages — Monolingual or multilingual?	Affects filename handling, reading time calculation, regex patterns for cleanup
Old domain — Need redirects from old URLs?	Creates redirect mapping from WordPress slugs
External feeds — Podcast RSS? Newsletter?	Enables auto-generation of missing content pages
Embeds — YouTube, podcast players, Instagram, Substack?	Configures Turndown custom rules to preserve specific embed types
Dark mode — Light/dark theme toggle?	CSS custom properties + [data-theme] attribute approach
Blog features — Category filtering, search, sort, stats?	Inline JS on blog index page

Key Architecture Decisions

The skill encodes opinions that come from doing this multiple times: