Docs

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 Tina.

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

Node.js is installed
You have set up a Tina starter
Have a basic understanding of using the Tina Editor and the schema
Have a basic understanding of React

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:

npx wordpress-export-to-markdown --post-folders=false --include-other-types=true

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 Tina 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:

For MacOS/Linux:

for file in *.md; do mv "$file" "${file%.md}.mdx"; done

For Windows:

ren *.md *.mdx

Which will convert your files from Markdown to MDX.

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

For ease of use the format of Tina 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 Tina app's content folder named wp-pages.

2. Create a new file in your Tina 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.

import type { Collection } from 'tinacms';

const WpPage: Collection = {
  label: 'Migrated WordPress Pages',
  name: 'wppage',
  path: 'content/wp-pages',
  format: 'md',
  fields: [
    {
      type: 'string',
      label: 'Title',
      name: 'title',
      isTitle: true,
      required: true,
    },
    {
      type: 'rich-text',
      label: 'Body',
      name: '_body',
      isBody: true,
    },
  ],
};

export default WpPage;

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


import WpPage from "./collection/wp-page";
...

schema: {
  collections: [Page, Post, ..., WpPage],
},

View and Edit your migrated content

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

npm run dev

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 Tina 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:

---
title: Your Post Title
coverImage: picture_post_1.png
---

{{ Content }}

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

---
title: Your Post Title
coverImage: /uploads/picture_post_1.png
---

{{ Content }}

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

fields: [
  {
    type: 'image',
    name: 'coverImage',
    label: 'Cover Image',
  },
  // Your other fields
];

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

return (
  // .... Your title and author components
  // Example coverImage rendering
  {
    post.coverImage && (
      <div className="w-full">
        <div data-tina-field={tinaField(post, "coverImage")}>
          <Image
            src={post.coverImage}
            alt={post.title}
            width={500}
            height={500}
            className="mx-auto"
          />
        </div>
      </div>
    )
  }
  // ... Your body component
);