Migrating WordPress Content

Introduction

This guide is a walkthrough using a WordPress to Markdown converter, which is recommended for most use cases where you want to migrate your content from WordPress to TinaCMS.

This guide focuses on transferring content and media only and will not include page styling.

Other conversion options that are not covered in this guide include:

  • Using the WordPress Rest API - best for extracting the pure html for page or post content in JSON format
  • Using the WPGraphQL plugin - best for cases where you want to query and extract specific data and content

Prerequisites

Getting Started

Converting WordPress to Markdown

1. Export your Wordpress content by going to https://wordpress.com/export/ and select Export All

Name it export.xml to make it easier for you in the next step

Use wordpress-export-to-markdown to convert your WordPress content into Markdown.

2. In the folder where you've saved your exported file export.xml, run:

3. When prompted, make sure the filename is correct, and use the default values for the other prompts.

This creates an output folder that groups your posts and pages into separate folders.

Import data to TinaCMS

Migrating Images

1. In the output folder, drag the image folders output/post/images and output/page/images to your TinaCMS app's public/uploads folder.

You can rename the folder before dragging to prevent duplicate image names being replaced

You can also set up alternative hosting with your preferred media manager.

Migrating Posts

1. Navigate to your output's posts folder output/post, and run in the terminal:

Which will convert your files from Markdown to MDX.

2. Drag all the MDX files in output/post to your TinaCMS app's content/posts folder, now your posts have been migrated to TinaCMS!

For ease of use the format of TinaCMS Starter posts matches the format that WordPress uses.

Migrating Pages

If you are having trouble with this step, feel free to contact a developer for assistance through our Community Discord Server.

1. Create a new folder in your TinaCMS app's content folder named wp-pages.

2. Create a new file in your TinaCMS app's tina/collection folder named wp-page.ts and use the template below, you can change this later to fit your page's schemas better.

3. Import your created collection to the schema in tina/config.tsx.

View and Edit your migrated content

1. At the root of your TinaCMS app, run:

2. Go to localhost:3000/admin

3. Go to the Migrated WordPress Pages and Blog Posts collections, then to the Media Manager. You can now view and edit your migrated posts, pages and images!

You'll notice that your pages won't display your media properly, let's fix that!

Displaying Media on Posts Example

We can do this in two methods, unfortunately, they both will require some manual work.

  • Option 1 - Updating each post's hero image to the cover image - Recommended if the hero component fits your needs without much changing
  • Option 2 - Updating the schema to match the Markdown - Recommended for updating your schema to match what it used to look like

Option 1: Manually update posts' image

Using the TinaCMS editor, you can update the hero image of each post.

Option 2: Update the schema to match the Markdown

Have a look at one of your posts' Markdown file, it may look something like this:

1. Update the coverImage field so that it can be fetched properly, by appending /uploads/ in front of the image URL.

2. In tina/collection/post.ts, add a new field with the name coverImage.

3. In app/posts/[...filename]/client-page.tsx, add the coverImage field so that it can be rendered with TinaMarkdown.

You can also copy or rename the heroImg code snippet and edit to fit your needs

4. Now when you view your posts, you'll see that your images will be displayed on the page!

Next Steps

  • Making changes to the themes and any missing features from the exporter
  • Take advantage of npm packages to replace WordPress plugins functionalities
Last Edited: November 8, 2024