Primoz Cigler on Business and Code

Pushing Merlin WP Towards Stable Release

In the summer heat of the last year, Rich Tabor has spiced up the atmosphere with his project Merlin WP – the onboarding wizard for themes or, as he puts it:

Merlin WP is my stab at addressing the tedious and exhausting WordPress theme setup and onboarding process. It makes installing a new WordPress theme, its recommended WordPress plugins, Customizer settings, widgets, and demo content, an exciting and gratifying user experience.

– Rich Tabor (original post)

I met Rich for the first time at Pressnomics 5 and we kept in touch since. When he published the blog post where he revealed the Merlin project, I was blown away. And I know many other people were too, for a good reason – he hit the bullseye of many users and theme developers’ pain point.

However, back then Rich suggested that that project is in beta and it should not be used in the production environment. In our team, we had other projects lined up and we didn’t want to distract our focus away. In the blog post he mentions our One Click Demo Import (OCDI) plugin which we’ve released less than 2 years ago and with 200,000+ active installations today it’s the most popular content demo importer for WordPress! But the plugin as such leaves a lot of room for improvements. It was designed to be the best WordPress content importer out there which solves most of the issues the official WP XML importer has, but it doesn’t make the very first steps after activating the theme any easier for the user.

The Missing Parts

Merlin kicks in at this point – it was designed specifically to make the initial actions that everyone makes after installing and activating the theme as easy and enjoyable as possible. However, once checking the codebase I’ve noticed that it’s using the modified version of the original WordPress importer which has a bad reputation for having issues on many shared hostings.

It’s really a pity to give users the most beautiful wizard out there and see it fail at the most crucial step – demo import.

With our new WooCommerce theme coming up in March, we want the user experience to be at the top and beyond everything WordPress theme buyers have seen so far. Merlin came back to my mind addressing the tedious first steps after activating the theme. We’ve decided to use it to put the UX on the next level!

The problem was that since August, the GitHub project got very little attention and it was still in beta. I wrote to Rich what’s the status and he told me that he’s been successfully using Merlin in some of his themes, but the old importer is one of the major bits that’s holding Merlin in the beta stage. That’s something we can fix!

So we did.

At the beginning of February, Gregor Capuder (backend engineer from our team) forked the project and since then 6 pull requests have been merged back to the Merlin WP repo. Here’s the summary of the most notable changes we’ve contributed:

  • The old importer functionality has been replaced by the new one from OCDI, making it far more reliable.
  • The demo content XML files, widgets and customizer settings files are no longer required to be shipped with the theme files (can be huge for large demos), but can be stored on a remote server, accessible on the public URL.
  • The functionality has been added which supports choosing a specific demo to be imported (from a drop-down menu at the moment). Previously only one demo import was possible.
  • Added support for the Redux framework importer (this part has been encouraged and sponsored by Chris Robinson, thank you!).
  • Updated documentation regarding all the changes.

From the outside, the wizard stays about the same, but the improvements under the hood are remarkable and lead to a much better user experience.

Let’s Roll out a Stable Version

In his announcement post, Rich mentioned that he’s been aiming at releasing a stable version of Merlin by the end of August. However, that didn’t happen and there was little activity in the repo since August.

I don’t blame Rich, he’s been playing solo most of the time and even though there was an excitement in the community, nobody really stepped-in and help him push the project forward. Until now. We at ProteusThemes have a strong need for such onboarding experience and we’ll be using it in production, so we have a clear need and motivation to make it happen.

Today, I’m happy to announce that the Release Candidate 1 of the Merlin WP is out. We’re aiming to release a stable v1 within one week (March 7, 2018) if no blocking issues are reported.

Download Merlin WP (RC1) Check the documentation

How Can You Help?

Our contributions are addressing most of the currently opened issues on the GitHub which is just supporting Rich’s thoughts that the original demo content importer was the biggest obstacle between the beta and the stable release. In the next week, Rich, Gregor and I will go through the opened issues, pinging back to the issue reporters and encouraging them to try the Merlin WP again and closing all the issues that have been fixed.

I believe this is the major step forward and both Rich and I want to see Merlin WP becoming the de-facto library for making the tasks after theme activation a gratifying user experience.

You can help the project by testing it out and reporting any additional issues you face. But most importantly, you will help your users and yourself by making the initial steps much more intuitive and enjoyable. Your users will thank you and you’ll benefit fewer support requests originating from the the unclear onboarding experience.

Roadmap for the Future

The contribution with the OCDI core functionality is fundamental, but we’re not stopping here. Here are some of the things out of my head where the Merlin WP can be further improved:

  • More fine-grained control of the required and recommended plugins installation. (Already addressed in the PR #10.)
  • Progress bar for long-running tasks (plugin installation, demo import).
  • Better documentation on the GitHub pages.
  • Possibility to include Merlin WP as the composer package.
  • Code licensing step for inserting the theme/plugin license code. (Already planned by Rich, but pulled back.)
  • Better API for editing/adding/deleting wizard steps.
  • … and many more!

Let me know which of these you feel are the most important to you in the comments below so we have a sense of what’s needed the most by the community!

You should follow me on twitter, here.



A software engineer transitioning to a digital marketer and entrepreneur. Walking the talk. Windsurfer, digital nomad.