Migrating from WordPress to Django

The migrating from WordPress to Django process involved several challenges. It ultimately resulted in a successful migration with all content preserved and properly formatted. In this post, I'll share the approach, tools, and lessons learned during this migration journey.

I am assuming if you are reading this you already know what Django is and why it is so great. Otherwise you can read more about it here - What is Django?

Why Migrate from WordPress to Django?

Before diving into the how, let's briefly discuss why you might want to make this transition:

- Greater development flexibility: Django gives you complete control over your codebase

- Performance improvements: Django sites often load faster than WordPress installations

- Security benefits: Fewer plugins means a reduced attack surface

- Learning opportunity: Working with Python and Django enhances your skillset

- Integration with other Python tools: Connect easily with data science libraries and more

The Migration Process Overview

The WordPress to Django migration followed these general steps:

1. Exporting content from WordPress

2. Converting WordPress XML export to JSON

3. Creating a Django data structure compatible with our models

4. Developing custom management commands

5. Importing data in batches

6. Validating and cleaning the imported content

Let's look at each of these steps in detail.

Step 1: Exporting WordPress Content

The migration begins with exporting your WordPress content. WordPress provides a built-in tool for this:

Log in to your WordPress admin dashboard

Navigate to Tools → Export

Choose "All content" to include posts, pages, comments, etc.

Download the XML file

This XML file contains all your posts, pages, media, categories, tags, and other content in WordPress's WXR (WordPress eXtended RSS) format.

IMPORTANT: If you have content in DRAFT form or waiting to be published, these posts will not move over well!

Step 2: Converting WordPress XML to JSON

Working with XML can be cumbersome, so I converted the export file to JSON for easier processing:

Various online tools can perform this conversion - I used https://jsonformatter.org/xml-to-json

Alternatively, you can use Python libraries like xmltodict to convert XML to JSON

The resulting JSON file is more manageable for parsing and importing

This conversion step simplifies the data extraction process and makes it easier to map WordPress fields to Django model fields.

Step 3: Creating Django Data Structures

Before importing the data, I needed to ensure my Django models could accommodate the WordPress content structure. This involved:

Analysing the WordPress data schema (posts, categories, tags, etc.)

Creating or modifying Django models to match this structure

Setting up appropriate relationships between models

My Django blog application uses models for:

Posts (content, publication date, status)

Categories (name, slug)

Media (images and attachments)

Step 4: Developing Custom Management Commands

The heart of the migration process involved creating several Django management commands:

The Import Command
This command was responsible for:
-Reading the JSON data
-Parsing WordPress posts and categories
-Creating corresponding Django objects
-Handling media imports
-Managing relationships between content

The Content Cleaning Command
-WordPress content often contains HTML that doesn't translate well to Django templates. This command:
-Removes unnecessary WordPress-specific HTML
-Fixes formatting issues
-Cleans up embedded media
-Ensures content renders properly in Django templates

The Slug Validation Command
-WordPress and Django handle URL slugs differently. This command:
-Validates all post and category slugs
-Identifies slugs that don't match Django's URL patterns
-Reports problematic content that needs attention

The Slug Fixing Command
To address issues identified by the validation command, this tool:
-Automatically regenerates invalid slugs from post titles
-Ensures unique slugs across all content
-Updates database records with corrected slugs


Step 5: Importing Data in Batches

Importing all content at once can be risky and resource-intensive. Instead, I used a batch processing approach:

Imported content in small batches (5-10 posts at a time)

Used offset parameters to control which content was imported

Added year/month filters to organize imports chronologically

Created a wrapper script to automate the batch process

This approach provided several benefits:

-Easier to troubleshoot if issues arose
-Reduced server load during imports
-Allowed for pausing and resuming the import process
-Provided better visibility into progress


Step 6: Validating and Cleaning Imported Content

After importing, several quality assurance steps ensured everything was working properly:

Running the validation command to check for URL resolution issues

Cleaning WordPress-specific HTML and formatting

Checking template rendering for all imported content

Verifying media and embedded content displayed correctly

Common Challenges and Solutions

During the migration, I encountered several challenges that required specific solutions:

Invalid Slug Formats
Problem: WordPress sometimes uses query parameter formats in slugs (like ?p=123) that aren't compatible with Django's URL patterns.
Solution: Created a custom management command that identifies these slugs and automatically regenerates them from post titles, ensuring they match Django's URL pattern requirements.

WordPress Shortcodes
Problem: WordPress content often contains shortcodes (, , etc.) that don't work in Django.
Solution: The content cleaning command identifies and processes these shortcodes, either converting them to standard HTML or removing them when appropriate.

Media Handling
Problem: WordPress stores media in a specific directory structure that differs from Django's approach.
Solution: Implemented media downloading and remapping to ensure all images and attachments were correctly imported and properly referenced in content.

Content Formatting
Problem: WordPress adds various classes, inline styles, and non-semantic HTML that can cause rendering issues.
Solution: Created a content cleaning process using BeautifulSoup that sanitizes HTML, removes unnecessary attributes, and improves semantic structure.

Draft Posts
Problem: Some WordPress posts might be in draft status but still need to be imported.
Solution: The import command preserves post status, ensuring draft posts remain unpublished in the Django site while still being imported.
Lessons Learned

This migration taught me several valuable lessons:

1. Start with a small test set: Import a few representative posts first to identify potential issues before running the full import.


2. Validate early and often: Create validation tools from the beginning to catch issues as they arise.


3. Plan for content cleaning: WordPress content almost always needs cleaning to work well in Django templates.


4. Batch processing is essential: Breaking the import into manageable chunks makes troubleshooting much easier.


5. Keep track of what's imported: Use logging and tracking to know which content has been successfully imported.


6. Watch out for draft posts: Be aware of post status and publication dates when importing.

Migrating from WordPress to Django is a complex but rewarding process. By breaking it down into methodical steps and creating custom tools to handle specific challenges, you can successfully transition your content while maintaining its integrity.

The management commands created for this process can be reused for future content migrations, making them valuable additions to your Django toolkit. While the initial setup requires effort, the long-term benefits of having your content in a flexible, powerful framework like Django make the migration well worth it.