# WordPress Migration

Source: [WordPress Migration](https://typeroll.com/docs/guides/wordpress-migration/)

> A complete guide to migrating a WordPress site to Typeroll using the AI migration workflow.

The migration workflow and helper plugin are included in the open-source Typeroll distribution. Typeroll Cloud also offers migration as an operated, supported service.

## Overview

[Section titled “Overview”](https://typeroll.com/docs/guides/wordpress-migration/#overview)

The migration workflow imports accessible WordPress content (pages, posts and supported custom post types) into a new Typeroll site, transfers your media through Typeroll’s media storage, and generates redirects from old URLs to new slugs.

**What it does:**

* Imports pages and posts as Typeroll pages
* Transfers media (images) through the media API — only images actually used on imported pages
* Maps custom post types to Typeroll collections
* Generates URL redirects
* Leaves everything as drafts for your review before going live

**What it doesn’t do:**

* Import your old WordPress theme or CSS (you build a new design in Typeroll)
* Import plugins or plugin-specific data that isn’t content
* Touch the source WordPress site in any way

## Before you start

[Section titled “Before you start”](https://typeroll.com/docs/guides/wordpress-migration/#before-you-start)

1. **Build the target site’s design**

   The migration imports content into your new design — not the old one. Before starting the migration, set up:

   * Colour palette and fonts (`update_site_settings`)
   * Header partial with navigation
   * Footer partial
   * 1–2 example pages (home, about) — the AI agent uses these as design references

2. **Check that the WP REST API is accessible**

   The migration needs `https://yoursite.com/wp-json/wp/v2/` to be publicly accessible. Test it in your browser — you should see a JSON response.

   If the REST API is disabled or restricted, [install the helper plugin](https://typeroll.com/docs/guides/wordpress-migration/#helper-plugin) which provides a separate authenticated export endpoint. Your administrator must allow access to that endpoint.

3. **Optional: install the helper plugin**

   The helper plugin gives the AI agent access to custom post types, ACF fields and navigation menus that may not be exposed via the standard REST API.

## Running the migration

[Section titled “Running the migration”](https://typeroll.com/docs/guides/wordpress-migration/#running-the-migration)

Start your AI agent and describe the migration:

```plaintext
Migrate my WordPress site at https://acme.se to this Typeroll site.
```

Or with the helper plugin:

```plaintext
Migrate the WordPress site at https://acme.se — I've installed the helper plugin
and configured its API key securely in the agent environment.
```

The AI agent will:

1. Verify the WP REST API connection
2. Build an inventory of all URLs on the site
3. Import pages and posts, transferring images along the way
4. Map any custom post types to collections
5. Generate redirects
6. Show you a coverage report

## Reviewing the migration

[Section titled “Reviewing the migration”](https://typeroll.com/docs/guides/wordpress-migration/#reviewing-the-migration)

After the content is imported, the AI agent shows a coverage report:

```plaintext
Migration complete. Here's the coverage:


✅ 24 pages migrated
↪  8 redirects created
⬜ 12 URLs excluded (pagination, feeds, admin)
⚠️  3 URLs unhandled:


  /category/projekt     → needs a redirect or category page
  /tag/stockholm        → tag archive — exclude or redirect to /blog
  /wp-content/uploads/2019/hero.pdf  → file, needs manual handling
```

For each unhandled URL, decide: add a redirect, create a page, or exclude it.

Sites imported with an older Typeroll version may have WordPress entities or markup left in titles and SEO text. Ask the AI agent to run `repair_migration_plain_text` as a dry run and show every proposed change. The repair is restricted to plain-text fields and leaves bodies, slugs, paths, and URLs alone. Approve the write only after reviewing the returned diffs; records with existing working copies are skipped rather than overwritten.

## Publishing

[Section titled “Publishing”](https://typeroll.com/docs/guides/wordpress-migration/#publishing)

All imported pages start as `status: "review"`. When you’re satisfied:

```plaintext
Publish all the imported pages and deploy.
```

Or review page by page and publish individually.

## Helper plugin

[Section titled “Helper plugin”](https://typeroll.com/docs/guides/wordpress-migration/#helper-plugin)

The Typeroll Helper Plugin gives the migration workflow access to:

* Custom post types with `show_in_rest: false`
* ACF fields with image references normalised
* Navigation menus
* Builder JSON (Elementor, Breakdance)
* Complete canonical URL list

**Installing:**

1. Download the `wp-helper-plugin` directory from the Typeroll repository and create a ZIP archive from it.
2. In WordPress: **Plugins → Add New → Upload Plugin**
3. Activate the plugin
4. Go to **Settings → Typeroll Helper** and generate an API key
5. Give the agent the site URL and configure the key through its secure credential mechanism. Keep the key out of shared prompts and documentation.

Tip

The helper plugin is read-only — it never modifies your WordPress database or files.