wordpress-import/README.rdoc

= Refinerycms-wordpress-import

This litte project is an importer for WordPress XML dumps into refinerycms(-blog). 

You can find the source code on github: https://github.com/mremolt/refinerycms-wordpress-import

Keep in mind, this gem imports blog posts and pages, NOT the media files, as they are not
part of the XML dump! You have to manually readd them to Refinery. 

The same goes for links to other pages on your site. WordPress exports them just as <a>-Tags. 
If your site (blog) structure uses new urls, the links WILL break! For example, if you used 
the popular WP blog url structure "YYYY-MM/slug", be warned that Refinery just uses "blog/slug". 
So your inner site links will point to the old WP url. 


== Prerequisites

As refinerycms-wordpress-import is an addon for RefineryCMS, is shares the prerequisites with it.
So you'll first need a running installation of refinerycms and refinerycms-blog. Make sure
the site is running, all migrations are run and you created the first refinery user. 


== Installation

Just add the gem to your projects Gemfile:

  gem 'refinerycms-wordpress-import'

Or if you want to stay on the bleeding edge: 

  gem 'refinerycms-wordpress-import', :git => 'git://github.com/mremolt/refinerycms-wordpress-import.git'

and run

  bundle


== Usage

Importing the XML dump is done via rake tasks:

  rake wordpress:reset_blog 

This one basically deletes all data from blog relevant tables (taggings, tags, blog_comments, 
blog_categories, blog_posts, blog_categories_blog_posts). 
Use this one first, if you want a clean import of your old blog. 

  rake wordpress:import_blog[file_name] 

This one does all the heavy work of parsing the dump and importing the data into refinery tables. 
The parameter is the path to the dump file. Got a report from a Mac user, that the ~
didn't work in the path. I'll have a look at it, but till then, don't use it please. 

If you don't want to import draft posts, you can set the ENV variable ONLY_PUBLISHED to true:


  rake wordpress:import_blog[file_name] ONLY_PUBLISHED=true

The task will then skip all posts that are not published.

  rake wordpress:reset_and_import_blog[file_name]

This one combines the two previous tasks. 

If you also want to import the cms part of WordPress, three more rake tasks manage
the import into RefineryCMS Pages:

  rake wordpress:reset_pages

This task deletes all data from the cms tables, ensuring a clean import. Otherwise existing 
pages could break the import because of duplicate IDs. 

  rake wordpress:import_pages[file_name] 

This task imports all the WordPress pages into Refinery. The page structure (parent - child)
is preserved. 

If you want to skip the draft pages, add the ONLY_PUBLISHED parameter to this task, 
just like with wordpress:import_blog.

  rake wordpress:import_pages[file_name] ONLY_PUBLISHED=true

If you want to clean the tables and import in one task:

  rake wordpress:reset_and_import_pages[file_name]


== Usage on ZSH

One more hint for users of zsh (like myself): 

The square brackets following the rake task need to be escaped on zsh, as they have a 
special meaning there. So the syntax is:

  rake wordpress:reset_and_import_blog\[file_name\]

Ugly, but it works. This is the case for all rake tasks by the way, not just mine. 


== Feedback

This is still a very new gem. It manages to import my own blog and a standard WordPress 3.1 dump with some sample posts. 
The first feedback is quite good, so it seems, the gem doesn't eat the machines it is installed on. 

If you want to help make it even more stable, please throw your own WP dumps against it 
and see what happens. If you encounter any bugs, please file a bug report here on github.
A sample dump that breaks this gem would be really helpful in that case. 

For extra karma, fork it, fix it yourself and send a pull request! ;-)