README.md

Storyblok WordPress importer

A simple script for migrating content from WordPress to Storyblok.

🚀 Usage

Prerequisets

This script has been tested on WordPress v5 with API v2. WordPress REST API must be publicly available during the migration process as this script won't handle authentication. On the Storyblok side you just need a space. In case the space is not an empty one, we recommend to test it before with a copy of the original space to make sure the migration process doesn't cause an issue to the existing content.

How to use

To use the script, just import it, initialise a new instance of the Wp2Storyblok class and run the Wp2Storyblok.migrate() method.

import {Wp2Storyblok} from './index.js'

const wp2storyblok = new Wp2Storyblok('http://yoursite.com/wp-json', {
  token: 'storyblok-oauth-token',
  space_id: 110836,
  blocks_mapping: [
    {
      name: 'core/paragraph',
      new_block_name: 'richtext',
      schema_mapping: {
        'attrs.content': 'content'
      }
    },
    {
      name: 'core/image',
      new_block_name: 'image',
      schema_mapping: {
        'attrs.url': 'image'
      }
    }
  ],
  content_types: [
    {
      name: 'pages',
      new_content_type: 'page',
      folder: 'your-custom-folder',
      taxonomies: [
        {
          name: 'categories',
          field: 'categories',
          type: 'value'
        }
      ],
      schema_mapping: {
        title: 'name',
        '_links.wp:featuredmedia.0': 'content.preview_image',
        content: {
          field: 'content.body_items',
          component: 'rich-text',
          component_field: 'content',
          categories: 'content.categories'
        }
      }
    }
  ]
})

wp2storyblok.migrate()

Parameters

• endpoint String, The main endpoint for the WordPress REST API, without the /wp/v2/ part
• settings Object
  • (region String, Optional, The region of your Storyblok space. Default is eu)
  • token String, The oauth token for the management API that can be retrieved in the account section of https://app.storyblok.com
  • space_id Integer, The id of your space
  • content_types Array of Objects
    • name String, The name of the content type in WordPress
    • new_content_type String, The name of the content type in Storyblok
    • schema_mapping Object, The mapping of the fields from WordPress to the fields in Storyblok. More info about the mapping here
  • (blocks_mapping Array of Objects, Optional, More info here)
    • name String, The name of the block in WordPress
    • (new_block_name String, Optional, The name of the component in Storyblok. If not set the original name of the component will be used)
    • schema_mapping Object, The mapping of the fields from WordPress to the fields in Storyblok. More info about the mapping here
  • (taxonomies Array of Objects, Optional, The taxonomies of the content type, More info here)
    • name String, The name of the taxonomy in WordPress
    • field String, The name of the source field in WordPress
    • (type String, Set to value to replace the taxonomy id with the slug of the taxonomy value. Set to relationship or leave empty in case you imported also the taxonomy entries as stories and you want to link the taxonomy entry with an option or multi-option field by UUID )
  • (folder String, Optional, The full slug of the destination folder in Storyblok)

Fields Mapping

The fields mapping object requires you to use the name of the field from WordPress as keys of the attributes and the name of the field in Storyblok as its value. You can also target subproperties and array elements using the dot notation.

"schema_mapping": {
  "_links.wp:featuredmedia.0": "content.preview_image"
}

In case you want a field to be migrated as content inside a nested block in a field in Storyblok, you can do that defining the target as an object with the following properties:

• field String, The name of the field in Storyblok
• component String, The name of the component you want to store inside the above field
• component_field String, The name of the field inside the component where you want to migrate the content

"schema_mapping": {
  "content": {
    "field": "content.body_items", 
    "component": "rich-text", 
    "component_field": "content" 
  }
}

WordPress Blocks Mapping

You can import blocks created with Gutenber as components in Storyblok. To achieve this you need to install the REST API blocks plugin and fill out the blocks_mapping property in the migration settings. You need to create an array of objects where you specify the name of the block from Gutenberg (called blockName in the REST API), the name of the component in Storyblok and then the schema mapping in the same format as for the content types. The blocks from Gutenberg are returned by the REST API inside the main object of an entry in a property called blocks.

  {
    "name": "pages",
    "new_content_type": "page",
    "folder": "",
    "schema_mapping": {
      "title": "name",
      "blocks": "content.body"
    },
  },

Importing Taxonomies

Taxonomies can be imported along with the other fields. You need to fill out the taxonomies settings in the settings of your content_type and the script will get the taxonomy value from WordPress instead of the taxonomy id and it will add it to your Stories in the field you chose.

🔗 Related Links

• How To Migrate From WordPress To A Headless CMS: In this article, we will look at when it makes sense to migrate from a monolithic project to a headless setup and the benefits that come with it. In addition to a step-by-step guide on how to migrate WordPress to Storyblok Headless CMS, the problems that will arise during the process and how to deal with them;
• Storyblok Technologies Hub: we prepared technology hubs so that you can find selected beginner tutorials, videos, boilerplates, and even cheatsheets all in one place.

ℹ️ More Resources

Support

• Bugs or Feature Requests? Submit an issue;

• Do you have questions about Storyblok or you need help? Join our Discord Community.

Contributing

Please see our contributing guidelines and our code of conduct. This project use semantic-release for generate new versions by using commit messages and we use the Angular Convention to naming the commits. Check this question about it in semantic-release FAQ.

License

This repository is published under the MIT license.