Making a (proper) WordPress Theme

One of the things that I’ve built regularly are custom WordPress themes for clients. Let me clarify — a custom theme for each client. One theme per client.

So, I decided to try my hand at making a “proper” WordPress theme — a theme for regular users. And I submitted it to the WordPress themes gallery. Successfully!

wp386 - my first public WordPress theme!
wp386 – my first public WordPress theme!

There were, however, quite a few catches along the way.

  • Code format / styling.
  • Completeness.
  • Compatibility / interoperability.
  • Edge cases.

TL;DR? Use _s.

Code format / styling.

If you are even a lightly experienced programmer, you understand the importance of a uniform code style. This applies here, too. WordPress has a few coding conventions that you should adhere to.

If you use _s, you’re pretty much set on this – just follow the conventions that have been established.


Support for comments, post titles, categories, tags, et cetera. You need it all.

Compatibility / interoperability.

This is a big one.

Please don’t design your theme to have any special features.

Since the purpose of Themes is to define the presentation of user content, Themes must not be used to define the generation of user content, or to define Theme-independent site options or functionality.

(read more)

Ideally, a user should not have the appearance of lost data when switching themes. Switch themes throughout development semi-regularly, just to make sure your users are happy both when they try your theme and when they try other themes.

Edge cases.

This is a little harder – there are quite a few edge cases (long titles, non-breaking text, you know the general culprits).

I strongly recommend using the WordPress Theme Unit Test suite of tools, including a WXR file full of edge cases, against your theme during development.


Quite a few of these catches can be easily overcome by simply building your theme with a steady foundation. I highly recommend _s, a theme that Automattic (the makers of built. Not only does it get you started with the basic features (think comments, theme hooks, base CSS classes), it will provide a basic template for more advanced features, such as Jetpack compatibility, the live theme editor, among others.

Have fun!


Too long? tl;dr.

Situation: You’re migrating a big site to WordPress. You don’t want to make 1,000+ posts manually, do you?

Meet Ruby/WordPress. I’ve made a quick little Ruby gem that interfaces with your WordPress database, so you can manipulate it within Ruby. This opens up a whole world of possibilites – the most exciting being Nokogiri, of course.

Here’s a quick code sample that will create 100 new posts!

require 'wordpress'

# Configuration
wp = { host: '',
                     port: 3306,
                     username: 'test',
                     password: 'test',
                     encoding: 'utf8',
                     database: 'wordpress',
                     wordpress_prefix: 'wp_' }

(1..100).each do |i|
  post = wp.new_post { post_name: "post-#{i}",
                       post_status: 'publish',
                       post_title: "Post #{i}" }
  post.post_content = "This is the content for post #{i}"!

Note that the configuration must point to a valid WordPress database (and make sure you don’t use one with valuable data… I don’t take responsibility for any lost data. You should be backing up anyways.)

It’s at version 0.0.2, a very early beta at this point, but it can do basic tasks such as creating posts (as shown before) and post querying (albeit, very basic at this stage in development):

wp.query( post__in: [ 1, 5, 8] ).each do |post|
  puts "Post: #{ post.post_title }n"
wp.query( post_type: 'custom_post_type', post_parent: 10 ).each do |post|
  puts "Post: #{ post.post_title }n"

The ultimate goal of WordPress#query is to be fully compatible with the WP_Query API.

Another feature is post meta manipulation. After you get your post object (WordPress::Post), getting or setting post meta is very easy:

post.post_meta['hello'] = 'world'
puts post.post_meta['hello'] + "n"

Initial support for taxonomies is also included:

puts post.get_the_terms('category').join(', ') + "n"
post.set_post_terms ['love', 'WordPress'], 'category'

Note: WordPress::Post#set_post_terms will overwrite all terms of the given taxonomy, unless you supply the “append” flag:

post.set_post_terms ['love', 'WordPress'], 'category', true

As you can probably tell, this is not a very ideal API, and I am planning on changing it soon.


Contributions are very welcome!! If you have an idea, or something that you would like to contribute, but don’t feel like you have something concrete enough for a pull request yet, please don’t hesitate to open an issue or contact me directly.

How to Install

Ruby/WordPress can be installed via RubyGems:

$ gem install ruby-wordpress

or, if you use Bundler:

gem 'ruby-wordpress', :require => 'wordpress'