---
title: "Migrate from WordPress"
description: "A comprehensive guide to migrating your WordPress website to Prismic."
category: "concepts"
audience: developers
lastUpdated: "2026-03-26T09:12:40.000Z"
---

<MigrationStudyRecruitment />

Prismic offers a modern, API-first approach to content management. This guide helps WordPress developers understand how to migrate their content and rebuild their frontend using Prismic.

> If this is your first time migrating a website to Prismic, we recommend reading [the general migration guide](https://prismic.io/docs/migration.md) first.

# What to expect

Migrating from WordPress to Prismic involves two main efforts:

* **Writing a migration script** to extract and transform your WordPress content into Prismic's format.
* **Rebuilding your frontend** using one of Prismic's supported frameworks: [Next.js](https://prismic.io/docs/nextjs.md), [Nuxt](https://prismic.io/docs/nuxt.md), or [SvelteKit](https://prismic.io/docs/sveltekit.md).

WordPress themes, plugins, and page builders do not transfer to Prismic. Instead, you'll build a modern, component-based frontend with full control over your website's code.

# Process overview

This page provides WordPress-specific guidance to supplement the [general migration guide](https://prismic.io/docs/migration.md).

The process involves the following steps:

* **Prepare content**

  1. [Audit your existing site](https://prismic.io/docs/migration.md#audit-your-existing-site)
  2. [Create a Prismic repository](https://prismic.io/docs/migration.md#create-a-prismic-repository)
  3. [Set up a project and install Slice Machine](https://prismic.io/docs/migration.md#set-up-a-project-and-install-slice-machine)
  4. [Define content models](https://prismic.io/docs/migration.md#define-content-models)

* **Extract content**

  1. [Extract data from WordPress](#extracting-wordpress-data)

* **Migrate content**

  1. [Transform your content to match Prismic models](https://prismic.io/docs/migration.md#transform-your-content-to-match-prismic-models)
  2. [Upload your content to Prismic](https://prismic.io/docs/migration.md#upload-your-content-to-prismic)
  3. [Build or update your frontend](https://prismic.io/docs/migration.md#build-or-update-your-frontend)

# WordPress vs. Prismic

Learn about the key differences between WordPress and Prismic.

## Content model

WordPress and Prismic structure content differently. Here's how WordPress concepts map to Prismic.

| WordPress        | Prismic                                                                                                                                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Posts and pages  | [Page types](https://prismic.io/docs/content-modeling.md#page-types)                                                                                                                                           |
| Authors          | [Custom types](https://prismic.io/docs/content-modeling.md#custom-types) + [content relationships](https://prismic.io/docs/fields/content-relationship.md#blog-post-authors)                                   |
| Taxonomies       | [Tags](https://prismic.io/docs/organize-pages.md#page-tags) or [content relationships](https://prismic.io/docs/fields/content-relationship.md#taxonomies)                                                      |
| Featured images  | [Image fields](https://prismic.io/docs/fields/image.md)                                                                                                                                                        |
| ACF fields       | [Fields](https://prismic.io/docs/fields.md), [repeatable groups](https://prismic.io/docs/fields/repeatable-group.md) for repeater fields, and [slices](https://prismic.io/docs/slices.md) for flexible content |
| Gutenberg blocks | [Slices](https://prismic.io/docs/slices.md)                                                                                                                                                                    |
| Post meta        | [Fields](https://prismic.io/docs/fields.md) in the static zone                                                                                                                                                 |
| Shortcodes       | [Slices](https://prismic.io/docs/slices.md) or [fields](https://prismic.io/docs/fields.md)                                                                                                                     |

> This mapping is a starting point, not a strict guideline. Every WordPress site is different — adapt these recommendations to fit your specific content structure and needs.

## Posts and pages

WordPress posts and pages map to Prismic [page types](https://prismic.io/docs/content-modeling.md#page-types).

* **Posts**: Create a reusable page type (e.g. `blog_post`).
* **Pages**: Create a reusable page type (e.g. `page`) for generic pages, or single page types for unique pages (e.g. `homepage`).

> Unlike WordPress where posts and pages are fundamentally different, Prismic treats all content as documents with different types. This gives you more flexibility in how you structure content.

## ACF Flexible Content and Gutenberg blocks

WordPress's flexible content approaches map directly to Prismic [slices](https://prismic.io/docs/slices.md).

Here's an example of how a common ACF Flexible Content setup might translate to Prismic slices.

| ACF Layout     | Prismic Slice      |
| -------------- | ------------------ |
| Hero           | Hero slice         |
| Text Block     | Text slice         |
| Image Gallery  | ImageGallery slice |
| Call to Action | CallToAction slice |
| Testimonials   | Testimonials slice |
| FAQ            | FAQ slice          |

Similarly, each Gutenberg block type you use becomes a slice in Prismic.

| Gutenberg Block | Prismic Slice                          |
| --------------- | -------------------------------------- |
| Paragraph       | Text slice (or inline in other slices) |
| Heading         | Text slice with heading configuration  |
| Image           | Image slice                            |
| Gallery         | Gallery slice                          |
| Quote           | Quote slice                            |
| Columns         | Columns slice (or slice variation)     |
| Buttons         | CallToAction slice                     |

> You don't need a 1:1 mapping. Use this opportunity to consolidate similar blocks into flexible slices with [variations](https://prismic.io/docs/slices.md#slice-variations).

## Routing

Prismic uses [route resolvers](https://prismic.io/docs/routes.md) to generate page URLs based on [documents' UID fields](https://prismic.io/docs/fields/uid.md).

| WordPress URL Pattern   | Prismic Route Resolver                      | Notes                           |
| ----------------------- | ------------------------------------------- | ------------------------------- |
| `/`                     | `{ type: "homepage", path: "/" }`           | Homepage                        |
| `/[slug]`               | `{ type: "page", path: "/:uid" }`           | Generic pages                   |
| `/blog`                 | `{ type: "blog_index", path: "/blog" }`     | Blog index page (single type)   |
| `/blog/[slug]`          | `{ type: "blog_post", path: "/blog/:uid" }` | Individual blog posts           |
| `/author/[slug]`        | `{ type: "author", path: "/author/:uid" }`  | If authors have dedicated pages |
| `/2024/01/15/post-name` | Not natively supported                      | See note below                  |

> **Important**
>
> WordPress's date-based permalinks (e.g. `/2024/01/15/post-name`) aren't natively supported in Prismic. Plan to simplify URLs to `/blog/post-name` and set up 301 redirects from old URLs to new ones at your hosting provider.

> Prismic supports more advanced routing patterns, including nested URLs based on content relationships. See the [route resolvers](https://prismic.io/docs/routes.md) documentation for details.

## Frontend

WordPress uses PHP themes and templates. Prismic websites are built with modern JavaScript frameworks.

| WordPress                  | Prismic                                                                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Themes                     | [Next.js](https://prismic.io/docs/nextjs.md), [Nuxt](https://prismic.io/docs/nuxt.md), or [SvelteKit](https://prismic.io/docs/sveltekit.md) projects |
| Template hierarchy         | File-based routing + page components                                                                                                                 |
| Template parts             | React, Vue, or Svelte components                                                                                                                     |
| `the_content()`            | [`<SliceZone>`](https://prismic.io/docs/slices.md#display-slices) component                                                                          |
| `get_posts()` / `WP_Query` | [Prismic client](https://prismic.io/docs/technical-reference/prismicio-client.md) methods                                                            |
| Plugins                    | npm packages                                                                                                                                         |

> Your WordPress theme won't transfer to Prismic. However, you'll gain full control over your frontend code, better performance, and a modern developer experience.

# Extract WordPress content

We recommend using the [WordPress REST API](https://developer.wordpress.org/rest-api) to extract your content. Unless disabled, it's available at `/wp-json/wp/v2/` on any WordPress site and returns JSON representation of your content.

```javascript
// Fetch posts with embedded data (featured images, authors, terms, etc.)
const response = await fetch(
  "https://your-site.com/wp-json/wp/v2/posts?per_page=100&_embed",
);
const posts = await response.json();
```

The [`@wordpress/api-fetch`](https://www.npmjs.com/package/@wordpress/api-fetch) package can be used in combination with [`wp-types`](https://www.npmjs.com/package/wp-types) to simplify your fetching logic and get typed responses.

```typescript
import wpFetch from "@wordpress/api-fetch";
import type {
  WP_REST_API_Pages,
  WP_REST_API_Posts,
  WP_REST_API_Settings,
} from "wp-types";

wpFetch.use(wpFetch.createRootURLMiddleware("https://your-site.com/wp-json"));
const wpClient = {
  getPages: () =>
    wpFetch<WP_REST_API_Pages>({
      path: "/wp/v2/pages?_embed",
    }),
  getPosts: () =>
    wpFetch<WP_REST_API_Posts>({
      path: "/wp/v2/posts?_embed",
    }),
  getSettings: () =>
    wpFetch<WP_REST_API_Settings>({
      path: "/wp/v2/settings?_embed",
    }),
  // Add more endpoints and query parameters support as needed.
};
```

> WordPress plugins often extend the REST API with custom endpoints and data (e.g. [ACF integration](https://www.advancedcustomfields.com/resources/wp-rest-api-integration)). Check your API responses for plugin-specific fields and extend the `wp-types` types as needed.

For complex migrations with custom database tables or non-standard content, you might need to query the WordPress database directly, use [WP Import Export](https://wordpress.org/plugins/wp-import-export-lite) plugin or other third-party export tools.

[Learn more about extracting content](https://prismic.io/docs/migration.md#extract-content)

# Convert WordPress content

Most WordPress field values can map directly to their equivalent on Prismic. Here's an example transformation from the WordPress REST API response to a Prismic document:

```javascript
// WordPress post from the REST API
const wpPost = {
  title: { rendered: "Hello World" },
  slug: "hello-world",
  _embedded: {
    "wp:term": [
      [{ slug: "technology" }], // Categories
      [{ slug: "javascript" }], // Tags
    ],
  },
  excerpt: { rendered: "<p>Saying hello to the world</p>" },
  content: { rendered: "<p>Lorem ipsum dolor sit amet...</p>" },
};

// Transformed to a Prismic document
const prismicDoc = {
  type: "blog_post",
  lang: "en-us",
  uid: wpPost.slug,
  tags: wpPost._embedded["wp:term"].flatMap((term) =>
    term.map(({ slug }) => slug),
  ),
  data: {
    title: wpPost.title.rendered,
  },
};
```

WordPress content fields like `content` and `excerpt` are HTML. You can convert them to Prismic rich text format using [`htmlAsRichText()`](https://prismic.io/docs/technical-reference/prismicio-migrate.md#htmlasrichtext) from `@prismicio/migrate`.

```javascript
import { htmlAsRichText } from "@prismicio/migrate";

const excerpt = htmlAsRichText(wpPost.excerpt.rendered).result;
const content = htmlAsRichText(wpPost.content.rendered).result;
```

[Learn more about `htmlAsRichText`](https://prismic.io/docs/migration.md#defining-rich-text-fields)
