Short version
Switching to Storyblok is a content project before it is a technology project. Design the content model first, choose a migration approach for your source (WordPress, a SaaS builder or a hard-coded site), and protect your search visibility by keeping URLs unchanged where possible and permanently redirecting the rest. Handle the switch yourself when you have a small amount of well-structured content; bring in a partner when the archive is large, the URLs are valuable or the integrations are custom. This guide walks through each path, the pitfalls, and how to decide.
You have decided to move your website to Storyblok. This guide starts where the comparison articles stop — with the move itself. What do you take with you, in which order, and how do you make sure Google and your editors both survive the switch?
I offer Storyblok development services. This site stores its structured content in Git rather than Storyblok, but the same content-modeling principles apply. What follows is the field guide I wish every team read before their first export.
Why teams switch to Storyblok
The pattern repeats across projects. A marketing team outgrows its CMS: every page needs a template customization, publishing depends on a developer, and the plugin stack needs more maintenance than the content. Storyblok answers that with a headless CMS that manages content as structured blocks and a visual editor that lets editors compose pages themselves. If the concept itself is new to you, read what a headless CMS is first — this guide assumes the definition and skips straight to the move.
Three triggers dominate in practice:
- Editorial freedom. Editors build pages from reusable blocks in a visual preview, without filing a ticket per paragraph.
- Performance headroom. The frontend becomes a separate, fast site — static where possible — instead of a theme layer on a database. The website performance gains are real when the rebuild is done with discipline.
- One content hub. The same structured content feeds the website now and other channels later, through one API.
When switching is not the right move
Honesty first, because a migration guide that always recommends migrating is a sales pitch. Staying put is the right call more often than vendors admit:
- Your site is small, stable and rarely edited. A five-page brochure site gains little from a content hub; the migration effort outweighs years of light website maintenance.
- Your rankings carry the business and you are about to overhaul the content. If you plan a full rewrite soon, do the rewrite first — migrating content you are about to replace means paying to move it twice.
- Your real problem is the website, not the CMS. A slow, dated site on WordPress becomes a slow, dated site on Storyblok when the frontend is rebuilt without care. Sometimes the answer is a headless website rebuild where Storyblok is one component, not the goal.
The core of the switch
A CMS migration is a content project before it is a technology project. The teams that struggle are the ones that start with the export; the teams that succeed start with the content model.
Start with the content model, not the export
Every source — WordPress, a SaaS builder, a hard-coded site — hides its structure inside pages. Storyblok makes structure explicit: a content model of typed stories and reusable blocks. Designing that model first is what separates a migration from a copy-paste.
Inventory what you have before modeling: page types, repeatable sections, media usage, and the content that is actually still read. Search Console shows which URLs earn search impressions, while analytics shows how visitors use them; deciding which content to remove is cheaper before the move than after. Then define the blocks: hero, text section, image with caption, call-to-action, FAQ. Editors should recognize their future toolkit in that list.
AI agents can help prepare this mapping work: compare a crawl with the sitemap, Search Console and analytics exports, propose redirect pairs, and flag pages for review. Those suggestions are not migration instructions. A person must check every destination, content mapping and removal decision before publication. An agent cannot decide whether a page still serves a customer just because it has few search impressions.
Migration options for each source
The move itself looks different depending on where your content lives today.
Moving from WordPress to Storyblok
You can export WordPress content through its API or an export file. Storyblok’s CMS migration documentation covers the import options: the Management API, the CLI, and a WordPress importer created by Storyblok. The mechanics are the easy part. The real work is mapping: posts and pages become typed stories, page-builder layouts become blocks, and shortcodes — the markup fragments plugins leave inside your text — need manual untangling. Migrate media as assets and preserve their alt text as part of the content.
Plan the web hosting split at the same time: Storyblok hosts the CMS, while you host the new frontend separately. The redirects belong to the new setup — once the domain points at the new host, that server answers every changed old URL with a permanent redirect. Keep the old WordPress install as a backup and rollback path until the new site has proven itself, not as the redirect layer your launch depends on.
Moving from a SaaS site builder
Builders like Wix, Squarespace or Webflow rarely offer a clean export. Expect a manual or semi-scripted extraction: content comes out as HTML or CSV, and structure has to be rebuilt by reading the pages, not the database. The amount of manual work depends on the archive: a compact marketing site remains manageable by hand, while a large one needs scripts and editorial review. The discipline that matters here is the redirect map, because SaaS builders often generate URL patterns you cannot replicate — and do not want to.
Replacing a hard-coded website
A hard-coded site is the simplest source technically: the content already sits in files you own. The work is editorial, deciding which paragraphs become which blocks. This path is common for teams moving from a developer-maintained static website to a site editors can manage themselves. Of the three approaches, this requires the least technical work — provided someone with content judgment does the mapping instead of a script that treats every div as a block.
Take your search visibility with you
No checklist guarantees your rankings — Google’s own site-move documentation warns to expect temporary fluctuation while it recrawls and reindexes the new addresses. But URLs are assets, and five rules help reduce the risk:
- Keep URLs unchanged where you can. An unchanged URL needs no redirect at all and keeps its history untouched; preserve every address that still makes sense and only change URLs that genuinely need a better structure.
- Redirect what changes, permanently and precisely. Every changed URL gets a 301 or 308 to its relevant new destination — never a blanket redirect to the homepage. Google’s redirect documentation confirms that permanent server-side redirects pass their signals to the new address.
- Build the URL inventory from four sources. Combine the XML sitemap, a full crawl of the live site, Search Console’s page data and your analytics. A rankings-only list misses URLs that carry backlinks or conversions without earning impressions.
- Set canonical URLs correctly from day one. Each new page carries a canonical URL that points at itself in the new structure, so Google consolidates signals on the new addresses instead of guessing.
- Change one thing at a time. Changing the CMS, design, and copy in the same launch makes ranking changes harder to explain. Migrate first, then redesign later.
Measure before and after. Record a baseline — impressions, clicks, positions for the pages that matter — and check the same numbers thirty days after launch. A migration you do not measure is a migration you cannot defend. And keep the redirects live long after the move: Google advises at least a year, because old addresses keep surfacing in links, bookmarks and indexes.
Common pitfalls
The failures repeat across sources:
- The content model mirrors the old site. Migrating “pages” instead of designing blocks recreates the old rigidity inside a new system.
- The redirect map covers pages but not media, feeds or tag archives. 404 errors on old image URLs and category pages can lose the search signals you meant to preserve.
- Editors meet the new CMS on launch day. The visual editor is intuitive, but the block model needs a walkthrough; an hour of training before launch beats a week of tickets after.
- The redirect map is treated as finished at launch. Old URLs resurface for months — in other sites’ links, in bookmarks, in Google’s index — so the redirects stay live at the new host for the long haul, and a full backup of the old site stays available for rollback.
Doing it yourself or working with a partner
Compare the options based on your situation rather than your budget:
| Situation | Migrate it yourself | Work with a Storyblok partner |
|---|---|---|
| A small site with a handful of page types | Yes — the manual work stays manageable | Possible, but rarely necessary |
| A large archive with years of content and media | Risky — mapping and redirect work can grow unexpectedly | Yes — scripted migration with editorial review |
| Rankings that carry the business | Only with a verified redirect map and a baseline | Yes — SEO preservation is planned and measured |
| Custom integrations: forms, commerce, search | Depends on your development capacity | Yes — integrations are where migrations stall |
| A team that will edit daily after launch | Yes, with time set aside for training | Yes — content modeling is the partner's core value |
You can migrate a small, well-structured site in-house with this guide and patience. The balance tips when the archive is large, the URLs are valuable or the integrations are custom — the three places where a migration quietly doubles in effort. If that is your situation, it is worth talking to a Storyblok agency before exporting, not after the project stalls.
How I run a Storyblok migration
My process follows the order this guide lays out: content-modeling workshop first, migration scripts second, redirect map and baseline before anything goes live, editor training before handoff, and follow-up measurements thirty days after launch. Straffe Sites is a Storyblok partner, with the partner listing and shipped Storyblok projects publicly verifiable — you can migrate with a Storyblok partner when the scope calls for it, and this guide tells you honestly when it does not.
Further reading by topic:
- What is a headless CMS, and what are its benefits? — the concept behind the switch
- Building a headless website: when it pays off — the frontend decision alongside the CMS
- Generate localized sitemaps for your Astro and Storyblok project — the technical follow-up once you are live
- Website performance: improve your site speed in 9 clear steps — what the rebuild should protect