Migrating content from one CMS to another sounds simple—until you’re actually doing it. If you’re staring down a pile of posts, pages, and weird legacy content, this guide is for you. I’ll walk you through moving your content to Contentful without losing data, your mind, or your weekend. No silver bullets, just the real steps you’ll need.
Before You Do Anything: Know What You’re Getting Into
Moving content between CMSes isn’t just copy-paste. Every platform stores things in its own way. You’re probably dealing with different field types, images living in odd places, slugs that don’t match up, and maybe some “surprise” embedded HTML.
A successful migration comes down to planning, not fancy tools. Here’s how to avoid the common traps:
- Don’t assume an “export” button will save you. Exports rarely include everything.
- Don’t trust third-party connectors blindly—test them on a small batch first.
- Always keep a clean backup of your original CMS content. You’ll want it when something inevitably goes sideways.
Let’s get into the steps.
Step 1: Audit and Map Your Existing Content
You can’t move what you don’t understand. Before touching Contentful, take inventory.
What to do: - List all content types (posts, pages, products, etc.). - For each type, note the fields (title, body, images, tags, etc.). - Watch for weird one-off fields or “custom” sections. - Document relationships (e.g., posts linked to authors or categories). - Check for media files: where are images and PDFs stored?
Pro tip: Sketch out a quick spreadsheet. This helps you see gaps and oddities.
What to ignore: Don’t waste time mapping old drafts or “test” content unless you really need them. Focus on what’s live and valuable.
Step 2: Design Your Contentful Content Model
Contentful works on structured content models (think: custom content types with fields). This is where most migrations get messy.
What to do: - Create Contentful content types that match your audit. Don’t just copy your old CMS’s setup—improve it if you can. - Use Contentful’s field types smartly (e.g., “Rich Text” for body content, “Media” for images). - For relationships (like author->post), use “Reference” fields. - Set up required fields and validation rules now, not later.
Honest take: Overcomplicating your model is easy and tempting. Resist. Start with what you need for launch. You can always iterate.
What to ignore: Don’t obsess over perfectly matching your old CMS structure. Contentful is probably more flexible—use that to clean up legacy messes.
Step 3: Prepare and Export Your Data
Now comes the grunt work: getting your content out of the old system and into a format Contentful will accept.
What to do: - Use your old CMS’s export tools to get all content. It’ll usually be XML, CSV, or JSON. - Export media files separately—these rarely come bundled. - Clean the exported data. Remove weird formatting, HTML you don’t want, and duplicate entries. - Map old field names to your new Contentful model.
Pro tip: If the old CMS’s export is a mess (and it probably is), use a script (Python, Node.js, whatever you’re comfortable with) to clean and restructure it.
What to ignore: Don’t try to bring over legacy formatting (inline styles, ancient widgets). This is your chance to start fresh.
Step 4: Import Content into Contentful
There’s no official “one-click import” for everything. But Contentful provides tools to help:
- Contentful CLI: The Contentful CLI can import data from JSON files. This is the most reliable method for bulk imports.
- Content Management API: For custom needs, you can script your own import using their API.
- Third-party tools: Some exist, but tread carefully—they’re rarely maintained and may not support your use case.
How to do it:
1. Convert your exported data to Contentful’s import format (JSON). Match field names and types.
2. Import a small batch first. Check for errors, missing fields, or weird formatting.
3. If all looks good, run the full import.
4. Use the CLI’s --publish flag if you want content to go live right away. If not, import as drafts.
Pro tip: Expect to run the import several times. You’ll find issues each run—fix and repeat.
What to ignore: Don’t rely on third-party “magic” tools unless you’ve tested them. Custom scripting will take longer but is safer.
Step 5: Handle Media Files (Images, PDFs, etc.)
Media is where most migrations trip up. URLs change, files get lost, and references break.
What to do: - Upload all media to Contentful’s Media Library (you can script this using their API or CLI). - Update your content to reference the new asset URLs or IDs. - Check for broken links—run a script to catch missing images.
Honest take: Media migration is tedious and rarely seamless. Plan for manual spot checks.
What to ignore: Don’t try to automate embedding every single legacy format (Flash, Silverlight, etc.). Focus on what you actually use.
Step 6: Test Everything—Twice
You’re not done just because the import finished without errors. Test like your job depends on it (because it probably does).
What to do: - Compare a random sample of entries—old CMS vs. Contentful. Is everything there? - Check all relationships (authors, categories, tags). - Click through media links to make sure they work. - Validate frontends if you have them wired up already.
Pro tip: Make a checklist and get someone else to review a sample. Fresh eyes catch what you’ll miss.
What to ignore: Don’t assume “no errors in the logs” means you’re in the clear. Visual spot-checks matter.
Step 7: Plan Your Go-Live and Post-Migration Cleanup
Once you’ve confirmed the migration works, you need a plan for cutover.
What to do: - Freeze content changes in your old CMS during the final migration. - Run a final export/import to catch last-minute changes. - Update your frontends or APIs to point to Contentful. - Watch analytics and error logs closely for the first week.
Honest take: There will be surprises—broken links, missing images, weird formatting. Prioritize fixes by impact.
What to ignore: Don’t rush to delete the old CMS. Keep it in read-only mode for a while, just in case.
FAQ: What Trips Most People Up?
- “Why does my content look weird?”
Usually it’s because field types didn’t match, or the old CMS used custom HTML. - “My images are missing!”
You probably forgot to update links in your content to point to Contentful’s assets. - “Can’t I automate this entire thing?”
You can automate a lot, but not everything—manual spot checks are non-negotiable. - “Is there a tool that does this for me?”
Some exist, but they’re rarely plug-and-play. Custom scripting is almost always needed for anything complex.
Keep It Simple and Iterate
The best migrations are boring: start with the must-haves, verify everything, then clean up as you go. Don’t try to make your new Contentful setup perfect on day one—get it working, then improve over time. You’ll sleep better, and your content will be safer for it.