Content Migration

WordPress Import is Optional

Important: Despite the name "WP2Astro", importing WordPress content is completely optional. You can:

• ✅ Start from scratch with a blank Astro site
• ✅ Import from WordPress if you have existing content
• ✅ Start blank and import later when you're ready
• ✅ Mix content - some imported, some created in WP2Astro

WP2Astro is a complete Astro development platform, not just a migration tool!

Two Ways to Create Content

Option 1: Start Fresh (No WordPress Needed)

Create a new project with WP2Astro's templates:

• Choose from Starter, Blog, Portfolio, Documentation, or Business templates
• Get example content to learn from
• Start writing immediately in the IDE
• No WordPress site required

Perfect for:

• New projects
• Learning Astro
• Building from scratch
• Clean slate development

Option 2: Import from WordPress

If you have an existing WordPress site:

• Export your WordPress content (XML file)
• Upload during project creation
• All posts, pages, and media imported
• Continue editing in WP2Astro

Perfect for:

• Migrating existing sites
• Preserving content history
• Moving away from WordPress
• Keeping existing content

WordPress Migration Process

If you choose to import WordPress content, here's how it works:

Content Types

WP2Astro migrates all standard WordPress content types:

Posts

Blog posts are converted to MDX files in src/content/blog/:

---
title: "Understanding React Hooks"
description: "A comprehensive guide to React hooks"
publishDate: 2024-02-20
author: "Jane Developer"
tags: ["react", "javascript", "tutorial"]
---

Your post content here...

Pages

Static pages become Astro pages in src/pages/:

// src/pages/about.astro
---
import Layout from '../layouts/Layout.astro';
---

<Layout title="About">
  <h1>About Us</h1>
  <p>Your about page content...</p>
</Layout>

Custom Post Types

Custom post types are preserved as content collections:

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const portfolio = defineCollection({
  schema: z.object({
    title: z.string(),
    client: z.string(),
    date: z.date(),
    featured: z.boolean(),
  }),
});

export const collections = { portfolio };

Metadata Preservation

All WordPress metadata is preserved:

Post Metadata

---
title: "Original WordPress Title"
description: "Original excerpt or meta description"
publishDate: 2024-01-15T10:30:00Z
updatedDate: 2024-02-20T14:22:00Z
author: "John Doe"
featured: true
draft: false
---

Taxonomy Terms

Categories and tags are maintained:

categories: ["Web Development", "Tutorial"]
tags: ["javascript", "astro", "performance"]

Featured Images

Featured images are downloaded and referenced:

image: "./images/my-post-featured.jpg"
imageAlt: "Description of the image"

Content Transformation

WordPress HTML is intelligently converted:

Headings

<!-- WordPress -->
<h2>My Heading</h2>

<!-- Becomes -->
## My Heading

Text Formatting

<!-- WordPress -->
<p>Some <strong>bold</strong> and <em>italic</em> text</p>

<!-- Becomes -->
Some **bold** and *italic* text

Lists

<!-- WordPress -->
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

<!-- Becomes -->
- Item 1
- Item 2

Links

Internal links are automatically updated:

<!-- WordPress -->
<a href="https://oldsite.com/about">About</a>

<!-- Becomes -->
[About](/about)

Images

<!-- WordPress -->
<img src="https://oldsite.com/wp-content/uploads/2024/image.jpg" alt="Photo" />

<!-- Becomes -->
![Photo](../../assets/images/image.jpg)

Media Migration

All media files are downloaded and optimized:

Image Processing

1. Download from WordPress
2. Optimize with sharp
3. Convert to modern formats (WebP, AVIF)
4. Generate responsive sizes

File Organization

Shortcode Conversion

WordPress shortcodes are converted to MDX components:

Gallery Shortcode

<!-- WordPress -->
[gallery ids="1,2,3,4"]

<!-- Becomes MDX -->
<Gallery images={[
  '/images/1.jpg',
  '/images/2.jpg',
  '/images/3.jpg',
  '/images/4.jpg'
]} />

Button Shortcode

<!-- WordPress -->
[button link="/contact" text="Contact Us"]

<!-- Becomes MDX -->
<Button href="/contact">Contact Us</Button>

Embeds

External embeds are preserved:

YouTube

<!-- WordPress auto-embed -->
https://www.youtube.com/watch?v=dQw4w9WgXcQ

<!-- Becomes -->
<YouTube id="dQw4w9WgXcQ" />

Twitter

https://twitter.com/username/status/123456

<Tweet id="123456" />

Advanced Features

Code Blocks

Syntax highlighting is preserved:

```javascript
function hello() {
  console.log("Hello World!");
}
```

Tables

| Feature | WordPress | Astro |
|---------|-----------|-------|
| Speed | Slow | Fast |
| Cost | $50/mo | Free |

Blockquotes

> This is a quote from WordPress
> that spans multiple lines

Content Validation

WP2Astro validates all migrated content:

• ✅ Valid frontmatter
• ✅ Working image links
• ✅ Valid internal links
• ✅ Proper Markdown syntax
• ✅ No broken embeds

Manual Adjustments

Some content may need manual review:

Complex Layouts

Page builders (Elementor, Divi) may need reconstruction:

<!-- Recreate custom layouts -->
<TwoColumnLayout>
  <Column>Left content</Column>
  <Column>Right content</Column>
</TwoColumnLayout>

Custom Widgets

Sidebar widgets become Astro components:

<Sidebar>
  <RecentPosts />
  <Newsletter />
  <SocialLinks />
</Sidebar>

Next Steps

• Explore Theme Conversion
• Learn about Custom Components
• Optimize SEO