Skip to content
Typeroll CMS

WordPress Migration

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”

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”

  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 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”

Start your AI agent and describe the migration:

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

Or with the helper plugin:

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”

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

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”

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

Publish all the imported pages and deploy.

Or review page by page and publish individually.

Helper plugin

Section titled “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.