Wagtail WordPress Import

A package for Wagtail CMS to import WordPress blog content from an XML file into Wagtail.

• Wagtail WordPress Import
  • Requirements
  • Compatibility
  • Initial app and package setup
    • Site URL for importing images and documents
    • First steps to configure your Wagtail app
  • Running the import command
    • Optional command arguments
  • Import process flow
  • Module documentation
  • Developer Tooling
  • Further Usage Examples

Requirements

1. Wagtail CMS Installed with initial setup
2. WordPress XML export of all content in a single file
3. The WordPress website will need to be live and available for importing of assets such as images and documents.

Compatibility

The package has been developed and tested with:

• Wagtail: 2.14 and 2.15
• Django: 3.1 and 3.2
• Postgres and SQLite Databases

Initial app and package setup

1. Setup a Wagtail site using your preferred method or follow the official documentation to get started.
2. Install this package with pip install -e "git+https://github.com/torchbox/wagtail-wordpress-import.git#egg=wagtail-wordpress-import" or using any method you prefer.
3. Place your XML files somewhere on your disk. The file can have any name you choose.
4. Create a log folder in the root of your site. The import script will need to write report files to this folder, you may need to set the permissions on the folder.
5. Add "wagtail_wordpress_import" to your INSTALLED_APPS config in your settings.py file.

Site URL for importing images and documents

Add a setting of WAGTAIL_WORDPRESS_IMPORTER_SOURCE_DOMAIN in your sites settings and set it to the the URL of the website that the images and documents will be imported from.

First steps to configure your Wagtail app

The import can be run on an existing or new site but you will need to perform some setup on your page models.

We recommend your page model inherits from the provided WPImportedPageMixin

from wagtail_wordpress_import.models import WPImportedPageMixin
class PostPage(WPImportedPageMixin, Page):
    ...

You will need to run python manage.py makemigrations and python manage.py migrate to add the fields to your page model.

It's intended that these fields are temporary for while importing, and can be removed once the content has been imported. view source

A full example of the suggested page model class

from wagtail.admin.edit_handlers import (
    FieldPanel,
    ObjectList,
    StreamFieldPanel,
    TabbedInterface,
)
from wagtail.core.fields import StreamField
from wagtail.core.models import Page
from wagtail_wordpress_import.blocks import WPImportStreamBlocks
from wagtail_wordpress_import.models import WPImportedPageMixin


class PostPage(WPImportedPageMixin, Page):
    body = StreamField(WPImportStreamBlocks)
    content_panels = Page.content_panels + [
        StreamFieldPanel("body"),
    ]

    edit_handler = TabbedInterface(
        [
            ObjectList(content_panels, heading="Content"),
            ObjectList(Page.promote_panels, heading="Promote"),
            ObjectList(Page.settings_panels, heading="Settings", classname="settings"),
            ObjectList(WPImportedPageMixin.wordpress_panels, heading="Debug"),
        ]
    )

    def import_wordpress_data(self, data):
        # Wagtail page model fields
        self.title = data["title"]
        self.slug = data["slug"]
        self.first_published_at = data["first_published_at"]
        self.last_published_at = data["last_published_at"]
        self.latest_revision_created_at = data["latest_revision_created_at"]
        self.search_description = data["search_description"]

        # debug fields
        self.wp_post_id = data["wp_post_id"]
        self.wp_post_type = data["wp_post_type"]
        self.wp_link = data["wp_link"]
        self.wp_raw_content = data["wp_raw_content"]
        self.wp_block_json = data["wp_block_json"]
        self.wp_processed_content = data["wp_processed_content"]
        self.wp_normalized_styles = data["wp_normalized_styles"]

        # own model fields
        self.body = data["body"]

Running the import command

The most basic command would be:

python manage.py import_xml path/to/xml/file.xml parent_page_id

parent_page_id is the ID of the page in your Wagtail site where WordPress pages will be imported as children. You can find this in the Wagtail admin URL when editing the page e.g. for http://www.domain.com/admin/pages/3/edit/ the ID is 3.

Running this command will import all WordPress 'post' and 'page' types to the 'PostPage' model in an app called 'pages'

Optional command arguments

• -m can be used to specify the Wagtail Page model to use for all imported pages. The default is PostPage when it's not specified.
• -a can be used to specify the Wagtail App where you have created your Wagtail Page model. The default is pages when it's not specified.
• -t can be used to limit the WordPress page types to be imported. You can pass in a comma-separated string of page types or just a single page type. The default is page,post if not specified.
• -s can be used to specify the status of pages you want to import. You can pass in a comma-separated string of statuses or just a single status. The default is publish,draft if not specified.

Import process flow

While the import process is simple to run with the options above there's a lot that happens during the import.

By changing the import configuration, you can customise the import process without modifying wagtail-wordpress-import package files. To understand what is possible, and how you can change the behaviour at different stages, you can read an overview of the import process.

Module documentation

• Block Builder
• Categories Import
• Import Hooks
• Prefilters
• WordPress Block Shortcodes
• WordPress Inline Shortcodes
• Yoast Import

Developer Tooling

We have included some developer commands to help you with importing large datasets and analyzing the data.

View Developer Tooling

Further Usage Examples

• Handling Specific HTML content structures