Mike McAlister, creator of the free Ollie theme, has been working towards getting his theme approved for hosting on WordPress.org. Ollie went into public beta in April 2023 and gained momentum over the next few months when McAlister previewed the theme’s new onboarding wizard.

WordPress users have been slow to adopt the block editor and block themes by extension. In 2022, only 54% of respondents to WordPress’ annual survey have used the block editor, four years after it was introduced. Block themes have trickled into the official directory, far behind the lofty goals set for their expansion. The sluggish movement towards block-based sites has led some to speculate on whether there will ever be a market for commercial block themes.

Ollie was designed to make onboarding to a block theme easier and the Site Editor more approachable, so that users don’t have to start from a blank canvas. The theme’s demo boasts “a 40-hr head start” on setting up a new WordPress website, thanks in part to dozens of patterns for fast page building. Ollie’s built-in onboarding experience aims to drastically reduce the amount of time users spend getting started.

After receiving significant pushback from the Theme Review team during Ollie’s three weeks in the queue, McAlister has put up a poll requesting feedback on how he should proceed.

Although provisionally approved by veteran theme reviewer Justin Tadlock, who said the onboarding functionality should be allowed until WordPress core offers a standard solution, Ollie was met with heavy criticism from other members of the team.

“The setup wizard is plugin territory,” UXL Themes founder and theme reviewer Andrew Starr said. “Why not make this as a plugin that would work with any block theme? A plugin could be inspiration or a nudge to improve the core experience.”

McAlister responded to this question in the Trac ticket for the review and in posts on X. He maintains that a plugin is a “far worse experience for the end user” and for his team as the maintainers of the product. Also, since the plugin review queue has 1,249 plugins awaiting review with developers waiting an average of 98 days for an initial review, a plugin for Ollie’s onboarding experience would likely not be live until next year.

“As a compromise and show of good faith, I’ve chopped down the onboarding wizard to a fraction of what it was,” he said. “No dice. Still, it continues to be a highly contentious issue that is causing folks to publicly question my intentions and integrity. Disheartening to say the least.”

Automattic-sponsored contributor Justin Tadlock, who helped author the guidelines in question many years ago and who has historically been widely esteemed for his impeccable judgment in regards to the grey areas of content creation in themes and the necessity of preserving data portability, weighed in on the ticket after performing the initial review:

As someone who co-wrote the original guideline for settings to use the customizer, I can say with 100% certainty that we never meant that to be a hard line drawn in the sand. The team reps can and have always had the capability to mark a theme as a “special case” (there’s even a tag for this in the backend, or there was when I was a rep). And there are themes where we felt like the functionality was unique enough to give it a bit of wiggle room. That was a position that we took when we wrote the “settings must be in the customizer” guideline. While I’m no longer one of the team reps, I feel like this settings page feature is unique enough to mark as a “special case.”

With block themes, some things must be reevaluated because the customizer is not available by default and is not an expected part of the block theme experience. In fact, this guideline is very specific to classic themes. Nothing has been written yet for block themes. Whether that’s a good thing, I don’t know. This could be a good moment for experimentation.

I disagree that the settings page should be packaged as a companion plugin. That defeats the purpose of its inclusion in the theme, and it would create an additional hurdle for the users who would benefit the most from this feature.

Yoast-sponsored contributor Carolina Nymark contends that allowing this onboarding experience will set a precedent that erodes the standard the team is trying to uphold for the ecosystem of themes hosted on WordPress.org and gives Ollie an unfair commercial advantage:

“That settings pages are not allowed is in many ways unrelated to the customizer. And if we really want to angle it that way, it would be way easier to re-enable the customizer link in the theme.

It is about having a standard that is easy for all theme authors to use and easy to review.
It is about not opening up the reviews to another situation with incredibly difficult and time consuming reviews of code that the theme developers themselves don’t understand because they copy-pasted it and managed to cause all sorts of errors and security issues.
Where that feature “lives”, in the customizer or on another page, is not the issue.

I would like everyone to also consider that the Site Editor is not at all far away from solving the problem with the initial template selection. It does not solve all onboarding steps, like getting to the Site Editor, but it is improving.

Compare it with the use of TGMPA. There is a problem that needs solving and a solution has been agreed upon where the theme author and reviewers only need to adjust a few variables and text strings.

If something similar could be reached here I would support it.

This is not about a special case, because it is an unfair commercial advantage over other theme developers.

Ollie is a beautifully-designed multipurpose theme of the highest caliber, the likes of which WordPress.org doesn’t see very often. If expanding block theme adoption is an important goal, these are the kinds of experiences you want people building for WordPress users. It may be time to redefine theme guidelines based on the possibilities that the block editor enables, instead of saddling block themes with antiquated constraints for the sake of maintaining a more expedient review process.

“Just because there are problems with onboarding it doesn’t mean that a theme, any theme, is the right tool just because one can put code in it,” Nymark said. “Plugins extend features, themes display content.”

Given the amount of pushback from the Theme Review team, McAlister is now torn about removing everything “extra” to get Ollie in the directory for better distribution, or to keep the innovations in place and forego the directory in favor of independent distribution. So far, the results of his poll are overwhelmingly in favor of McAlister distributing the theme himself.

“I’m passionate about innovation and getting the most out of all the possibilities that modern WordPress affords us,” McAlister told the Tavern. “We were tasked to ‘Learn JavaScript Deeply’ not to remain where we’ve been for so long, but to push the boundaries and scope out the future of WordPress and what’s possible.

“So we designed and developed Ollie’s educational dashboard and onboarding wizard to help users get over some of the hurdles they’ve been plagued with for so long when setting up a new site or switching to a new theme. We even designed it in a very core-inspired way to match the site editor to create a very cohesive experience. The feedback has been inspiring!”

After posting about his experience with the Theme Review team, which McAlister characterized as “rocky (and downright combative),” the community following his work on Ollie over the past year has rallied around him with advice and support.

“I am torn about this,” Joost de Valk commented on McAlister’s poll on X. “I feel WordPress needs these onboarding experiences. Very very much. Should it be in themes? Not sure. Should the theme repository block this stuff? I don’t think so… we should be open to experimenting with this a bit more.”

McAlister said that even as the theme’s creator, he is torn about the decision as well.

“I built this as a good faith attempt to help people onboard into block themes and hopefully even help drive adoption,” he said. “My intentions are pure and steeped in 15 years of doing it ‘the WP way.’ It’s an attempt to move the needle, worth a shot anyway.”

“I always felt that onboarding like this should be part of Core,” Yoast-sponsored contributor Ari Stathopoulos commented. “The current experience for a newcomer to WP is not a good one. We have to start somewhere… if it’s in themes, then so be it.”

WordPress’ Theme Review team has a critical choice here, whether to stifle innovation and throw the book at one of the most highly anticipated block themes, or identify this as a special case where the author has the users’ best interests at heart.

Many participants in the discussion on X encouraged McAlister to distribute his work independently, citing examples of other WordPress products that have found success in doing so. This would be an unfortunate loss for WordPress.org where the project is essentially shooting itself in the foot by clinging to outmoded guidelines in order to deny high quality block themes that are innovating to create a better user experience. In pursuit of a more robust offering of block themes, the last thing WordPress needs to do is chase away its trailblazers.

“Since this morning, there has been an overwhelming amount of feedback telling me to avoid the WordPress.org directory,” McAlister said. “I’m kind of bummed by this because I think it says something about the directory that a lot of folks think but few want to say out loud.

“Personally, I want the directory to succeed and be an inspiring and resourceful jump-off point for new WordPress users! It’s the front page of our open source project, of our community. It should be a showcase of the finest our community has to offer. But today, I’m disheartened and not sure if it’s the place where I want to put some of my best work to date.”