Ghost Migration — Import from WordPress, Medium and Other Platforms

In this tutorial, you'll learn how to migrate content into Ghost — importing from WordPress via XML export, importing from Medium, using the Ghost JSON export/import format, and verifying that all content was transferred correctly.

What You'll Learn

• The available Migration paths into Ghost
• Exporting content from WordPress (WXR XML file)
• Importing WordPress content into Ghost
• Exporting content from Medium and importing into Ghost
• The Ghost JSON export/import format structure
• Mapping WordPress content types to Ghost equivalents
• Handling images and media during migration
• Validating and cleaning up imported content
• Common migration pitfalls and how to avoid them

Why It Matters

Migrating platforms is stressful. Content represents months or years of work - losing even a single post due to a bad migration is frustrating. Ghost provides official import tools for WordPress and Medium, but the Process requires preparation. Understanding what gets imported, what gets left behind, and how to fix common issues after import ensures your migration succeeds without data loss.

Real-World Use

A blogger has been writing on WordPress for five years with 300+ posts. She wants to move to Ghost for its simpler interface and built-in membership features. She exports a WordPress XML file from her old site, uses the Ghost import tool, and all 300 posts - including tags, featured images, and author information - appear in her new Ghost site. She spends an hour fixing formatting in a few posts with complex WordPress shortcodes, but the bulk of the migration is done in minutes.

Learning Path

flowchart LR
  A["Ghost Labs"] --> B["Ghost Migration
You are here"]:::current
  B --> C["Posts & Pages"]
  C --> D["Tags & Taxonomy"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

Migration Overview

Ghost supports importing content from:

1. Another Ghost site - Direct JSON import (full fidelity)
2. WordPress - Via WXR (WordPress eXtended RSS) export
3. Medium - Via Medium's export HTML format
4. Substack - Via email export or manual transfer
5. Custom sources - Any platform that can produce JSON matching Ghost's format

Method 1: Ghost to Ghost Migration

This is the simplest migration - exporting from one Ghost site and importing into another.

Export from Source Ghost

1. Go to Labs > Export > Export your content.
2. Click the Export button.
3. A JSON file downloads to your computer.

Import into Destination Ghost

1. Go to Labs > Import > Import content.
2. Select the JSON file.
3. Ghost processes the import and reports results.

What Gets Transferred

• All posts and pages (including drafts)
• Tags with metadata
• Author profiles
• Site settings (title, description, timezone, navigation)
• Feature images and post images (image URLs)

What Does NOT Get Transferred

• Themes - install them separately
• Members and subscribers - export separately via Members > Export
• API keys and integrations - recreate them manually
• Configuration file settings - set them up again
• Custom code injection - copy it manually

Method 2: WordPress to Ghost Migration

WordPress to Ghost migration uses WordPress's WXR export format.

Step 1: Export from WordPress

In your WordPress admin:

1. Go to Tools > Export.
2. Select "All content."
3. Click "Download Export File."
4. Save the XML file (typically 1-50 MB depending on content volume).

Step 2: Import into Ghost

1. In Ghost admin, go to Labs > Import > Import content.
2. Select the WordPress XML file.
3. Ghost processes the file and maps WordPress content to Ghost format.
4. Review the import results and fix any issues.

Content Mapping

Post-Import Cleanup

After importing WordPress content, you typically need to:

1. Fix shortcodes: WordPress shortcodes (like [gallery] or [contact-form]) are imported as raw text. Search for square brackets in your posts and replace shortcodes with Ghost cards manually.

2. Fix image URLs: WordPress stores image URLs pointing to the old site. Ghost does not download WordPress images during import. You need either:

   • Keep images on the old WordPress site (they hotlink - not recommended)
   • Download and re-upload images to Ghost
   • Use a migration plugin that transfers images

3. Review formatting: WordPress Gutenberg blocks are converted to HTML, which may look different in Ghost compared to WordPress. Review complex posts for formatting issues.

4. Check broken links: Internal links between posts may use WordPress's URL structure. These will 404 on your Ghost site unless you set up redirects.

Method 3: Medium to Ghost Migration

Medium offers a built-in export feature.

Step 1: Export from Medium

1. Go to Settings > Account > Download your information.
2. Medium prepares a ZIP file with your posts as HTML files.
3. Download the ZIP and extract it.

Step 2: Import into Ghost

1. In Ghost admin, go to Labs > Import > Import content.
2. Upload the HTML files or ZIP archive.
3. Ghost parses the Medium HTML format and creates posts.

Limitations

• Medium exports include the post content, title, and publishing date
• Medium claps, responses, and stats are not included
• Medium images may hotlink to Medium's servers (download and re-upload)
• Series/collections from Medium are not preserved as tags

Method 4: Substack to Ghost Migration

Substack does not have a direct export format. Options include:

1. Manual copy-paste: Copy posts from Substack and paste into Ghost (time-consuming for many posts).
2. RSS import: Some third-party tools can fetch Substack posts via RSS and convert them to Ghost format.
3. Email export: Export your Substack subscriber list as CSV and import into Ghost.

Method 5: Custom Migration

For any other platform, you can create a custom migration:

1. Export your content from the source platform (CSV, JSON, XML, or database dump).
2. Write a script that converts the data to Ghost's JSON format.
3. Import the generated JSON via Labs > Import.

Ghost's import JSON format expects:

{
  "data": {
    "posts": [
      {
        "title": "Post Title",
        "slug": "post-title",
        "html": "<p>Post body HTML</p>",
        "status": "published",
        "visibility": "public",
        "published_at": "2024-01-15T10:00:00.000Z"
      }
    ],
    "tags": [...],
    "posts_tags": [...]
  }
}

Handling Images During Migration

Images are the trickiest part of any migration. Three approaches:

Option 1: Hotlink from Old Site

Keep images on the old server and point Ghost to them. This works temporarily but fails when you shut down the old site.

Option 2: Manual Re-Upload

Download all images from the old site and re-upload them to Ghost via the editor. This is labor-intensive but ensures images are under Ghost's control.

Option 3: Scripted Migration

Write a script that:

1. Downloads all images from the old site
2. Uploads them to Ghost via the Admin API
3. Updates post HTML to reference the new URLs

Post-Migration Checklist

After any migration, verify:

• All posts and pages are present (compare counts)
• Post content renders correctly (spot-check 10+ posts)
• Featured images appear on posts
• Tags are assigned correctly
• Author bylines are correct
• URLs and slugs match expectations
• Internal links work (not 404)
• RSS feed validates
• Sitemap includes all content
• Old site URLs redirect to new URLs (301 redirects)

Common Mistakes

1. Not downloading images before shutting down the old site: The WordPress import does not download images. If you shut down the old WordPress site, all images disappear from imported posts. Always download images first or keep the old site running during the transition period.

2. Using the Labs export as the only backup: The Labs export only exports content (posts, tags, authors). It does not include themes, settings, members, or API configurations. Use a full database backup for disaster recovery.

3. Ignoring shortcode conversion: WordPress shortcodes do not work in Ghost. If your posts have shortcodes for galleries, contact forms, or tables, they will appear as raw text like [gallery id="123"]. Search and replace these with actual Ghost cards.

4. Importing into a site with existing content: The import tool adds content to existing content - it does not replace it. If you import twice, you get duplicate posts. Always import into a fresh Ghost installation or delete test content afterward.

5. Forgetting to set up redirects: Your old site's URL structure is different from Ghost's. If you had a WordPress post at /2024/01/my-post/, it will now be at /my-post/ in Ghost. Without 301 redirects, visitors get 404 errors.

Practice Questions

1. What content formats does Ghost support for import? Answer: Ghost supports Ghost JSON format (for Ghost-to-Ghost migration), WordPress WXR XML format, and Medium HTML export format. For other platforms, you need to create a custom JSON file matching Ghost's import schema.

2. Why do WordPress shortcodes not render correctly after importing into Ghost? Answer: Shortcodes are WordPress-specific PHP functions that Ghost does not understand. During import, shortcodes are treated as plain text because Ghost has no plugin system to interpret them. You must manually replace shortcodes with equivalent Ghost cards.

3. How do you handle image migration from WordPress to Ghost? Answer: The WordPress import preserves image URLs but does not download the images. You have three options: keep the old WordPress site running (images hotlink), manually download and re-upload images, or write a script using the Admin API to automate image transfer.

4. Challenge: Set up a local WordPress site with 10 test posts that include images, categories, tags, and a few shortcodes. Export the WordPress content and import it into a local Ghost installation. Document every issue you encounter, fix the shortcodes manually, and write a migration report with your findings.

FAQ

Mini Project

Your task: Create a migration plan and execute a test migration.

1. Set up a local WordPress site with 5 posts, 3 categories, 5 tags, and 2 featured images.
2. Export the WordPress content as a WXR XML file.
3. Set up a local Ghost site.
4. Import the WordPress XML into Ghost.
5. Document every issue that occurs during import (broken images, shortcodes, formatting).
6. Fix all issues in Ghost and verify the final result matches the original WordPress content.
7. Write a migration checklist that you could give to a client migrating from WordPress to Ghost.

This exercise gives you hands-on experience with real migration challenges before you encounter them on a production site.

What's Next

Now that you know how to migrate content into Ghost, it is time to understand the two content types:

Continue to Lesson 10: Posts and Pages — Learn the differences between posts and pages, publish states, scheduling, and excerpts.

Related lessons:

• Tags and Taxonomy — Organize content with tags
• Authors — Manage author profiles and permissions