Apostrophe 1.5: legacy documentation

Still using Apostrophe 1.5? Check out Apostrophe 2 for your future projects.

apostrophe Importers Plugin

Apostrophe Importers Plugin

This plugin is a home for import tools that bring in content from specific CMSes. Plugins here read export files from other CMSes and generate XML to be fed to the apostrophe:import-pages and apostrophe:import-blog tasks, which are part of the core plugins.

Currently this plugin offers the apostrophe:import-wordpress task. This task currently only imports blog posts (and the images that appear inline in those blog posts).


To import a Wordpress blog, follow these steps:

1. Make sure your Wordpress blog is still up and running. You'll need it operational to export its content, and to retrieve its inline images.

2. Out of the box, Apostrophe's blog only supports comments via the  Disqus service. WordPress? can also use Disqus but does not do so by default. If you want to keep comments on your blog posts and you are not already using Disqus with Wordpress, you will need to migrate your existing Wordpress blog comments to Disqus first. This is not hard to do.  See the Disqus Wordpress documentation.

3. If you haven't already, build and design your Apostrophe site according to the documentation. Include the blog plugin in the site of course. You should add blog posts and satisfy yourself with basic Apostrophe blog design issues before you continue. If you are bringing in Disqus comments from Wordpress, make sure you enable Disqus in your Apostrophe site too, with the same shortname.

4. Add apostropheImportersPlugin to the list of plugins in your project configuration class. Make sure this plugin is enabled AFTER apostropheBlogPlugin in your project configuration class. This is a critical requirement. If you are using svn to manage your project you can just do:

svn propedit svn:externals plugins

And add this line:

apostropheImportersPlugin http://svn.apostrophenow.org/plugins/apostropheImportersPlugin/trunk

If you are not otherwise using svn for your project, you can just check out the importers plugin via svn to a subdirectory of your plugins folder:

cd plugins
svn co http://svn.apostrophenow.org/plugins/apostropheImportersPlugin/trunk apostropheImportersPlugin

5. Rebuild your Doctrine classes and migrate your project to add the column used to associate posts with their original Disqus thread identifier (you should do these steps even if you don't use Disqus just for consistency's sake):

./symfony doctrine:build --all-classes

And follow that up by migrating your database:

./symfony apostrophe:migrate --env=dev (or staging, or prod...)

6. Add users corresponding to the authors of your existing Wordpress blog posts. If you must change the author usernames, you can create an authors.xml file like this one:

<?xml version="1.0" encoding="UTF-8"?>
        <mapping from="Alex" to="alex" />
        <mapping from="Dana" to="dana" />
        <mapping from="Geoff" to="geoffd" />
        <mapping from="Johnny" to="johnnybenson" />
        <mapping from="Rick" to="rick" />
        <mapping from="Tom" to="boutell" />
        <mapping from="admin" to="admin" />

You should always have an admin user. The import task will assign any posts that don't otherwise match a user to the admin user. If you don't care about retaining information about multiple authors you can get away with not adding any additional users.

7. Log into your existing Wordpress site, click Tools, and click Export. Save the resulting XML file as wordpress.xml in the data folder of your Apostrophe project.

8. Run the import task! If you do not have an authors.xml file and you don't care about Disqus comments, run:

./symfony apostrophe:import-wordpress --xml=data/window-wp.xml

If you have an authors.xml file and Disqus comments, run:

./symfony apostrophe:import-wordpress --xml=data/window-wp.xml --authors=data/authors.xml --disqus

Naturally you can combine these options as appropriate.

Like most Symfony tasks this task defaults to the dev environment. If you are running in staging or production you will need to specify --env=staging or --env=prod.

The task will run for a while and import your blog posts and media files. Inline images are fetched from the sites they reside on, which must be up and running at the time of the import, and copied to the media repository. In future you may wish to replace them with larger originals, but this "scraping" import is effective and gets your migration out of the way.


That's it! Your Wordpress blog posts (along with their comments, if you had them in Disqus) should now appear on the blog of your Apostrophe site, with the same authors and content.