Umbraco to WordPress: Two Open-Source CMSs, One Careful Move

🇹🇷 Türkçe: Bu yazının Türkçesini oku →

Umbraco is the one migration in this series where you are moving between two open-source systems, and that changes the tone of the conversation. This is not a story about escaping a proprietary vendor’s pricing. Umbraco is free, open, and genuinely well-liked by the .NET developers who use it. So when a team wants to move from Umbraco to WordPress, the reasons are more specific — and worth being honest about, because it is not a slam-dunk the way leaving an expensive DXP can be.

Let me lay it out plainly first, then get into the technical detail near the end.

Why teams leave Umbraco for WordPress

• The .NET hosting and talent reality. Umbraco is open source, but it is a .NET application — it needs Windows or .NET hosting and .NET developers. For an organisation whose team and infrastructure are drifting toward the PHP/JavaScript world, that is friction that grows over time. WordPress fits the more common hosting and hiring market.
• Editorial self-service. Umbraco’s document types are defined by developers. Adding a field or a new content section is a development task. WordPress with ACF and the block editor gives editors more of that control directly.
• Ecosystem depth. Umbraco has a healthy package ecosystem, but it is a fraction of WordPress’s. WooCommerce, the SEO plugins, the forms, the memberships, the sheer plugin economy — that gravity pulls a lot of content sites toward WordPress.
• Cost of change over time. For a marketing site that keeps needing new sections and campaigns, the per-change developer cost on Umbraco adds up against WordPress’s self-service model.

The honest part: open source is not the deciding factor here

I argue constantly that the real value of open source is not that it is free — it is that there is an exit. When a platform is open, and a fight breaks out, or a vendor’s priorities change, users still have options because the code is theirs. I made this exact argument about the ACF and WP Engine conflict in the WordPress world: the fork into Secure Custom Fields was messy and political, but it was possible because the code was open, and everyone kept working. The presence of risk was not the problem. The absence of an exit is the problem — and open source is the exit.

Here is the thing: Umbraco has that exit too. So moving from Umbraco to WordPress is not an escape from lock-in — both are open, both let you leave. This migration is a fit decision, not a survival decision. You are moving because WordPress matches your team, your hosting, your ecosystem, and your editors better — not because Umbraco trapped you. Being clear about that keeps you honest, and it keeps you from over-promising the client a rescue when what you are really delivering is a better fit.

How I plan an Umbraco migration

1. Inventory the model — document types, their properties and data types, the content tree, templates, the Block List/Block Grid content, members, and culture variants.
2. Prune the document types and properties that stopped being used.
3. Map to WordPress — document types to custom post types, properties to ACF, the content tree to page hierarchy or flattened collections, blocks to Gutenberg blocks or ACF flexible content, members to WordPress users.
4. Build the empty target and validate with editors.
5. Transform against a snapshot, dry-run on staging, repeat.
6. Redirects before cutover.
7. Cut over, then watch.

The Technical Part: Where an Umbraco Migration Actually Breaks

The specifics that decide the outcome.

Document types and the content tree

Umbraco content is a tree of nodes, each shaped by a document type (its content type, with properties driven by data types and property editors). Document types map to custom post types, properties to ACF fields. The content tree maps to WordPress page hierarchy where the hierarchy is meaningful, and should be flattened to posts-plus-taxonomy where it is really a flat collection. Umbraco document-type compositions (shared property groups mixed into multiple types) need resolving during inventory so you capture the full property set of each node.

Block List and Block Grid are the hard part

Modern Umbraco leans on the Block List and Block Grid editors — an editor picks block types and arranges them, much like a page builder. This is Umbraco’s equivalent of components/dynamic zones, and like every such system, it has no clean 1:1 in WordPress. Decide, per block type, whether it becomes a Gutenberg block/pattern or an ACF flexible-content layout, and handle every block type by hand. Block Grid layouts carry column/row structure that you must decide how to preserve or flatten. This is where the hours hide — inventory every block type and every grid layout before writing the transform.

Rich text: TinyMCE vs the block editor

Umbraco’s rich-text property has historically been TinyMCE-based HTML, and newer versions offer a block-based editor. HTML-based rich text drops into WordPress relatively cleanly, but watch for embedded macros, local links (/{localLink:umb://...}), and media picked inline — these Umbraco-specific tokens will not render and must be resolved to real URLs during the transform. Check which rich-text flavour each property uses before estimating.

Extraction: Content Delivery API, uSync, or the database

Umbraco does not have a clean “export to WordPress” path. Good routes are the Content Delivery API (the headless API in Umbraco 12+, which returns content as JSON), uSync (which serializes content and schema to disk), the Management API, or a direct read against the SQL Server/SQLite database. Whatever you pick, freeze a snapshot and run your transform against the frozen copy, repeatedly, until the output is boring. Never transform against live production.

Culture variants

Umbraco handles languages as culture variants on a node — one node, multiple language values. Choose the WordPress target — multisite, Polylang, or WPML — before migrating, and handle nodes that are published in some cultures but not others so you do not create orphan translations. As always: the multilingual architecture is decided first. It is an architecture problem, not a translation problem, and I have learned that lesson on more multilingual projects than I can count — German runs long, Turkish runs longer, Arabic runs the other way. If your target assumes a language, you have already failed.

Media and file references

Umbraco’s media section stores files as media nodes with their own properties. Download and re-import them into the WordPress media library, and rewrite every reference — in media-picker properties and, crucially, inside rich-text content where media is embedded by URL or umb://media reference. The in-content references are the ones that quietly break after you decommission the Umbraco instance.

Members and templates

Umbraco members (front-end user accounts, distinct from back-office users) map to WordPress users, but password hashes are not portable — plan for resets. And Umbraco templates are Razor views: they are presentation, they do not migrate, and the front-end has to be rebuilt as a WordPress theme or blocks. If a headless front-end consumes the Content Delivery API today, it will need to switch to the WordPress REST API or WPGraphQL, with a different response shape — budget for that data-layer rebuild.

My honest closing position

Umbraco is good software and leaving it is not a rescue mission. Both it and WordPress give you the one thing that actually matters — an exit — so this migration is about fit, not survival. You are moving because WordPress matches your team, your hosting, and your editors better, and that is a perfectly good reason on its own.

Do the modelling work anyway, especially the Block List and Block Grid mapping, because that is where an Umbraco migration quietly overruns. Handle every block type by hand, resolve the local-link and media tokens in rich text, decide the multilingual architecture first, and set your redirects before cutover. Do that, and the content lands somewhere that fits the way your team actually works — which is the only honest reason to move between two systems that both let you leave.

One More Thing: But Can’t WordPress Just Do What Umbraco Does?

Here is the question a .NET team asks the moment they consider this move: if we leave Umbraco, do we lose the decoupled setup we built with the Content Delivery API or Heartcore? No. You don’t. And this is the part where people who still picture WordPress as “just a blog” get a genuine surprise — because we at WP Clan are not going to shortchange WordPress here.

WordPress is not new to headless. The REST API has shipped in core since late 2016 — nearly a decade of production hardening. WPGraphQL has been around almost as long, and it is now backed by Automattic and on its way to canonical status as WordPress’s GraphQL layer. So the exact decoupled model you liked in Umbraco — content served as JSON to whatever front-end asks — WordPress does too, in the open, and has for years. Headless WordPress via WPGraphQL is a direct parallel to Umbraco’s Content Delivery API and Heartcore. Same architecture, different backend.

So you have two honest paths off Umbraco, not one:

• Traditional WordPress — the rest of this article. Give the editors a theme and a block editor and let them publish without a developer ticket. Umbraco can do this too, but WordPress leans further toward editorial self-service.
• Headless WordPress — keep the decoupled architecture you built. Document types become custom post types, Block List/Block Grid become ACF flexible content or native blocks, and WPGraphQL (or the REST API) replaces the Content Delivery API as your query layer. Your front-end barely notices the CMS changed underneath it.

Both are open source, both give you an exit — I said that at the top and I meant it. But WordPress brings more to the same table:

• A real commerce engine. WooCommerce, not a bolt-on.
• A far bigger plugin ecosystem — SEO, forms, memberships, none of it rebuilt from scratch.
• A huge non-.NET hosting and talent pool. No Windows or .NET requirement; the more common PHP/JavaScript market your team is already drifting toward.
• Editorial power for humans, not just developers.
• No per-seat pricing, no usage meter, and ownership — nobody can buy WordPress out from under you.

Umbraco is a fine CMS and it has its own exit. This isn’t a rescue. But “we run headless via the Content Delivery API” is not a reason to leave WordPress out of the conversation — it is a reason to run WordPress headless, keep the traditional option in your back pocket, and pick up a much bigger toolbox on the way. That’s the surprise: this is a fit upgrade, and you didn’t have to choose between headless and WordPress at all.