This is probably the single most frequently asked question that arrives in my inbox, or elsewhere. And for good reason, I suppose. Seeing how I’ve been building sites on top of WordPress exclusively for about 3 years now. There are many different routes you can take when building a theme, and I’ve pretty much streamlined my method over the past couple years. Granted, there are always exceptions and I’ve found that I can’t work from a base template. Instead, I build “themes” from the ground-up, but with a little help. Here’s how…

First, a Little Clarification

I only use the word “theme” because that’s what WordPress calls them. In fact, I’ve only built one theme to date. That being the soon-to-be-released WicketPixie. For the most part, I design and build unique sites for individuals or companies that are used for their sole purposes.

The Starting Point

Once a design has been signed off on, it’s time to move to the cutting board. At this point, WordPress hasn’t even crossed my mind. I build out XHTML/CSS templates for however many unique layouts are going to be needed. For the most part, this includes the homepage and article/post templates. This is where I have a bit of a head start, in that I use my Barebones Stylesheet as a base and build from that. Since its release, my Barebones Stylesheet has evolved into a full directory hierarchy with multiple stylesheets – a re-release is in the cards, so stay tuned for that. Once the templates are complete, I normally upload them to my dev server and have my client give them a once over before proceeding to building out the theme.

Now, The Fun Begins

Honestly, having the static templates turn into a working theme is my favourite part of any project.

At this point, I have a local dev site running where I begin to create the templates that make up the theme. First, I create the new theme’s directory in /wp-content/themes. I then make a copy of my template directory and move everything into the new theme directory. The theme directory looks something like this…

  • css
  • images
  • home.html
  • post.html

WordPress requires that index.php and style.css are present for a theme to be activated, so there’s still a bit to do before I open a browser and start testing. First thing’s first, let’s get index.php and style.css in place. I simply create a blank file named style.css and paste the snippet that’s required with the theme details. That’s all that style.css contains, since I keep all of my main styles in /css/screen.css. index.php is another story entirely, though. After duplicating post.html, I rename it index.php and open it for editing. I use TextMate for text editing and have a set of snippets which is essentially an extension off the WordPress Theme Bundle to place the necessary template tags. Prior to using TextMate, I used to open up the various includes from the default template and snatch the common template tags out of it. Things like and , etc.

Once all of the common template tags are in place, I start creating the includes that make up the theme. Pulling out the header portion to make header.php, and likewise for the footer and sidebar. Before I save my index.php again, my theme directory now contains the following files…

  • css
  • footer.php
  • header.php
  • images
  • index.php
  • home.html
  • post.html
  • sidebar.php

index.php is now in rough shape, with huge chunks of code taken out to make up the includes. All three of the main includes (header, sidebar, and footer) can be included by WP template tags. So where the code once was, I place the include calls – , , . Now index.php is saved and the theme can be activated.

There’s actually one step I skipped there, for the sake of keeping things more straight forward. Before saving index.php, I update any image paths so they are relative to the theme directory instead of the site root. To do this, I use the template tag.

The last step before building out the rest of the templates, is to add The Loop. Since this is based off the post template, I use a pretty standard Loop which calls things like the post title, date posted, content, comments, etc. Again, referring to the default theme is a good starting point.

Building Out the Remaining Templates

Now that index.php with accompanying includes is in place, the theme is functioning. I’m able to see the “Hello World” placeholder post and click-through to the permalink, browse the category index and even search. But everything is laid out exactly the same. This is where I start building additional templates off index.php and customizing their layout accordingly. Sticking to standard templates that WP automatically recognizes, I typically end up with…

  • 404.php
  • archive.php
  • comments.php
  • css
  • footer.php
  • header.php
  • images
  • index.php
  • home.php
  • page.php
  • search.php
  • searchform.php
  • sidebar.php
  • single.php

You might have noticed that my original XHTML templates are now gone. At this point, I no longer need them as I’ve built the dynamic versions.

The Bulk, Done

From here, each project takes a different path as they all have their own specific requirements. But until now, I follow the same steps to build out the basic theme each and every time.

I’m sure some of you are surprised that I don’t have a base theme that I build from. Honestly, pulling out code is more work than inserting. Especially when using an app that supports tab-triggers, like TextMate. I type “wploop”, hit tab and the entire WP Loop is laid out for me – perfectly indented and everything. I should really do a screencast and show my coding in action, shouldn’t I?


All I can say is thanks Matt. It’s nice to see an article on WP a bit more simplified than the the bulk that exist on the net right now. Great post!

Yeah, I made a point of skipping over the technical details, and instead linked off to the WP codex.

Hey Matt,

Awesome post. I’m suprised this post hasn’t been done sooner with the amount of requests you must get. It would be good to see how textmate works, I for one have never used it before and would be interested in seeing it being used to see if it would be better for me personally.

Any updates on when the question and answer post is going to happen?

Take Care


Are you on a Mac? TextMate is totally the way to go, if so. I’ll get on that screencast and you’ll see for yourself. It took a while for it to really click with me, but when it did, I was sold instantly.

I actually forgot about that QA post I did back in January. Then saw an email drop in my inbox last night asking this quesiton, which was also asked in the QA post. I’m going to chip away at those and get some of the bigger ones out of the way first, then do a catch-all for the remaining ones.

I had the mac, I got rid of the mac and now it’s calling me again. I can’t believe how stupid I was getting rid of it in the first place.

Stupid stupid stupid decision.

Look forward to seeing the QA post.

Go back to the Mac! I just got rid of my PC two weeks ago and welcomed a Macbook Pro into my house – no regrets….

Great idea for an article, Matt. I’m sure many up-and-coming (as well as veteran) WordPress developers are going to find this useful.

P.S. Screencasts are huge.

Great read. I used WP for about a year on a Photoshop brush site, but have since moved everything over to Expression Engine.

This really helps outline the advantages of WP over some other CMSes. Would love to see those screenshots.

Also thanks for the heads up on some great icons, desktop background, and alterations for the Mac via your Flickr photos. Good stuff.

Expression Engine has lots of features that WP doesn’t, which has almost lured me over a few times. But I can’t stand the template system, and some other things like the horribly lacking import and URL re-writing have kept me where I am.

Great Post Matt!

I’d like to see the bundle you greated for WordPress. Can you share the snippets you’ve created?

Yeah, I’ll likely do that. I’ve assembled quite a collection over time, and they’re all assigned tag-triggers.

nice work on the tutorial – I just did a course on WordPress theming and added a link to this posting.

I really like to see what you did with the TextMate WordPress Bundle. Care to share?

thanks in advance

One thing you haven’t mentioned is how you deal with pages of content! For instance say you had an about page with images, tables and some sort of XHTML, how would you go about adding this? Would you A) create a page and stick the code in the post box or B) create a new template file and leave the post blank. Plus how are you stopping WordPress for wrapping paragraphs and messing up the XHTML code in the post box?

This would fall more under content management then theme design. Not something I would have to worry about until the content is being placed, for the most part.

But as you’ve pointed out, dumping code into the editor isn’t a very good option. If there’s something more complex then straight text based content, I’ll often use custom fields to accomplish the goal where possible – you’d be amazed what you can do with them. It really comes down to the client, though. For my own blog, I just do anything "special" in the template. Where as, most clients don’t know HTML and shouldn’t be poking around in there.

Well I’m just curious how say you might do say that portfolio page, where is all the HTML code for that stored? In a page using page.php or do you have a custom template for the job? x

The design page is a custom template. The content is actually driven by the WordPress links manager, so it’s only about 8 lines of code. But it’s a unique layout in that there’s no sidebar. So it warrants a custom template.

I initially created this theme back in 2005 and wasn’t big into using conditionals as I am now. There’s a lot of custom templates that could be cut down by using conditionals. The next version will be a different story.

"This is probably the single most frequently asked question that arrives in my inbox, or elsewhere"

yeah, i’ve send you a mail about this 🙂

i learn it very quick, it is really easy when you start to understand what each file do.

i do like you, forget about wp and just do the layout but i do have a "ground theme" that i use to copy/paste the wp codes in the new theme and also to test different things in the loop, and stuff like that.

one suggestion, the post was great but edit it explaining what each file do (ie. category.php, used to show posts in a category) and how the file tree works (if category.php doesn’t exist, archive.php is used instead), it was the 2 things that i had most difficulty with and in my opinion are both important to understand to create themes more "open and dynamic"

I liked your walkthrough of your theme process.

One thing that you might be interested in is setting up a PHP function to place your loop(s). I have a file called loop.php and then in function.php I create a function called get_loop(); that I use on every page.

On the loop.php file, I use the WordPress conditions like is_page, is_category, etc to make the individual loops. It’s MUCH more convenient than hard coding each individual loop.

And, since I use the Blueprint CSS framework, much (at least 90%) of the coding can be recycled for other clients–like the loop.php file.

Great work on Wicket Pixie!

Good tip! I’ve seen reference to the loop template in my passings, but always forget to try it out. I’ll have to give it ago next time I’m setting up a theme… which will be early next week.

I’m not sure what you said about me, but thanks! 😉 That’s a nice looking blog you’ve got there.

[…] bin ein großer Fan von Matt Brett (bekannt als “Erfinder” der Feed-Icons) der in seinem Blog über Games, Projekte und […]

Question. Is WordPress flexible enough as a CMS for multi purpose website? I wanna learn theme desigining, but there are 2 CMS I’m worried about, Drupal (or Joomla) and WordPress. Which one you reckon?

Hey great site and thanks for the help. I really appreciate the effort you have put into helping others out with themes. Keep up the good work!

Richard Ogima

[…] Link ]    « Apple maakt de iPhone 3G officiëel bekend… Ook […]

Awesome stuff, found this one when I was browsing around for info on WordPress theming.

Seems like there is no real base theme for WordPress that includes all the files you need to get started. But I’ll try it your way now, seems fairly simple. 🙂

Just too bad I’m not a designer. Good thing I work with them though. 😛

Thanks for the post!

[…] unas semanas llegamos por casualidad a un artículo de cómo crear un tema de wordpress desde cero y no pudimos evitar la tentación de crear uno. Además nuestro servidor acaba de ser actualizado y […]

Really enjoyed the article and love your work. Recently discovered wordpress and realized how easy it was to work with.

take it easy….

Hello Matt,

I have ended up here because a Google search for "what do different wordpress theme files do?" landed me here. And I am glad. I am about to build my first wp theme and I am looking for good tuts that are not daunting.

Screencasts are most welcome. We newbies will sure benefit from it.

Have a nice day.