Short version
Switching to Storyblok is a content project before it is a technology project. Design the content model first, migrate per 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. Do the switch yourself when your content is small and well structured; 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 the decision frame.
The decision is made: your website moves 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?
Storyblok projects are part of my Storyblok development services, and this site itself manages content the structured way. 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 is a template exception, publishing waits 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 is a headless CMS 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 the content will change shape anyway. If you plan a full rewrite soon, do the rewrite first — migrating content you are about to replace pays the moving costs 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 and your analytics tell you which URLs earn impressions; an archive pruning decision 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.
The migration path per source
The move itself looks different depending on where your content lives today.
Moving from WordPress to Storyblok
WordPress content exports through its API or an export file, and Storyblok documents the import side in its CMS migration documentation: the Management API, the CLI and a WordPress importer maintained by Storyblok itself. 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. Media migrates as assets with their alt texts, which you should treat as content, not metadata.
Plan the web hosting split at the same time: Storyblok hosts the CMS and your new frontend hosts elsewhere. 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. How heavy that manual share gets depends on the archive — a compact marketing site stays manageable by hand, 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 editor autonomy, and the technical share is the lightest of the three — 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 keep the risk small:
- 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.
- Clean canonicals 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. A new CMS, a new design and rewritten copy in the same launch make every ranking wobble unexplainable. Migrate first, redesign visibly 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. Stray 404s on old image URLs and category pages leak the authority you meant to keep.
- 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
The honest decision frame, by situation rather than by 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 — the mapping and redirect work grows quietly | 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 training time reserved | Yes — content modeling is the partner's core value |
A small, well-structured site migrates 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 the export, not after the stall.
How I run a Storyblok migration
My process follows the order this guide lays out: content model workshop first, migration scripts second, redirect map and baseline before anything goes live, editor training before handover, and a measurement round 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