WordPress Theme Template & Directory Structure

While the most minimal of WordPress Themes really only need an index.php template and a style.css file (or just the style file if it’s a Child Theme) most need something a little more solid.

Let’s create the directories and files that will make up our _s-based theme, Shape.

Make a folder in wp-content/themes/ for your theme—for this tutorial I’ll be using “shape”, but it can be whatever you want—and create the following blank files and folders in that new folder (don’t worry, we’ll fill them up as we work through the lessons).

  • inc (folder)
  • js (folder)
  • languages (folder)
  • layouts (folder)
  • 404.php
  • archive.php
  • comments.php
  • content.php
  • content-aside.php
  • content-page.php
  • content-single.php
  • footer.php
  • functions.php
  • header.php
  • index.php
  • no-results.php
  • page.php
  • search.php
  • searchform.php
  • sidebar.php
  • single.php
  • license.txt
  • rtl.css
  • style.css

Now let’s open up the last file we created, style.css, in a text editor. The first thing we need to do is add a section at the top of this file bracketed by what are called CSS “comments” (these guys: /* and */). It’s here that we need to put the info that tells WordPress about your theme. Without it, your theme won’t show up in the themes panel.

I’m using “Shape” as the theme name here, but feel free to name your theme what you want. And of course, fill in the author name, URLs, and description with your own information. :)

/*
Theme Name: Shape
Theme URI: http://themeshaper.com/
Author: ThemeShaper
Author URI: http://themeshaper.com/
Description: The Shape theme is a simple, minimalist theme based on Underscores and the original Shape Theme by Ian Stewart. It was created especially as a learning theme for The ThemeShaper WordPress Theme Tutorial: 2nd Edition.
Version: 2.0
License: GNU General Public License
License URI: license.txt
Tags: light, white, one-column, two-columns, left-sidebar, right-sidebar, flexible-width, custom-backgroud, custom-header, custom-menu, featured-images, flexible-header, microformats, post-formats, rtl-language-support, threaded-comments, translation-ready
This theme, like WordPress, is licensed under the GPL.
Use it to make something cool, have fun, and share what you've learned with others.
*/

Let’s walk through each of these elements so you understand what they’re all about.

  • Theme Name – The name of your theme, obviously!
  • Theme URL – The URL of your theme’s home on the web. It can be a section of your website. For example, many theme authors will use something like: “http://yourgroovydomain.com/your-theme/”
  • Author – Self-explanatory. Your name, of course!
  • Author URI – Link to your website
  • Description – Provide a brief and clear description of your theme, summarizing its purpose and features in a few sentences. This description will appear in users’ Dashboards when they search for themes, as well as next to the theme’s listing on the WordPress.org Free Themes Directory.
  • Version – The version number of your theme. It’s up to you to decide how to number your versions, but you can start at 1.0 if it’s brand new. If you ever release updates, you can change the number accordingly.
  • License – Your theme’s license. If you’re distributing your theme, it’s required to use the GPL license, the license that WordPress uses.
  • License URI – Provide a link to where users can find the text of the license. We’re including a “license.txt” file with the theme that we’ll fill in in our lesson on Distributing Your WordPress Theme.
  • Tags – These words describe your theme’s features, colors, and subjects. They are required if you plan to distribute your theme. These tags allow people to filter their searches by color, subject, etc., when searching for themes in the WordPress Free Themes Directory or in their Dashboards. Here’s a list of approved tags.

Something to note: a lot of this is optional. Really, you just need the Theme Name. But if you ever plan on releasing your theme, or if you’re making a custom theme for someone, you’ll want to start out including most, if not all, of the rest. At the very least, I want you to feel free to mess around with it.

Once you’ve got that done you can activate your theme and navigate to your test site. We’ve made the ultimate blank theme! Things should start to get interesting right about now.

Building In Your HTML Structure

Now we get to use our HTML structure from the previous lesson. But first, a mini-lesson about WordPress and Templates.

WordPress really only needs 1 template file, index.php. We can, and will be using a series of template files that can be used instead of index.php for certain situations (single posts, archive pages, etc.), but at the very beginning, index.php is all we’ll need.

Now, index.php and all its related brothers and sisters (which we’ll get to) make the web pages we see in our browser. They’re files with some HTML and HTML-outputting-PHP but in the end they make web pages.

Let’s think of web pages like stories, something with a beginning, a middle, and an end. Well, when we write out our index.php file (and later our single.php, category.php, etc.) we’re going to concentrate only on the middle bit. But! We’re going to call in the beginning bit and the end bit. We may have to always be redoing our middles but we’re only going to do the beginning and end of each web page once.

Header.php and Footer.php

Get the HTML structure we worked on in the previous lesson and copy everything up to and including <div id=”main”> into header.php and save it. It should look like this:

<div id="page" class="hfeed site">
     <header id="masthead" class="site-header" role="banner">
         <hgroup></hgroup>
         <nav role="navigation" class="site-navigation main-navigation"></nav><!-- .site-navigation .main-navigation -->
     </header><!-- #masthead .site-header -->
<div id="main" class="site-main">

Now, copy everything after, and including, </div><!– #main –> into footer.php. It should look like this:

     </div><!-- #main .site-main -->
     <footer id="colophon" class="site-footer" role="contentinfo">
          <div class="site-info"></div><!-- .site-info -->
     </footer><!-- #colophon .site-footer -->
</div><!-- #page .hfeed .site -->

Sidebar.php

Copy the following from our HTML structure into sidebar.php. It should look like this:

<div id="secondary" class="widget-area">
</div><!-- #secondary .widget-area -->

<div id="tertiary" class="widget-area">
</div><!-- #tertiary .widget-area -->

Index.php

I bet you can guess what we have to do now. Copy everything from our HTML structure inside the #main div up until the #primary closing div into index.php. It should look like this:

<div id="primary" class="content-area">
    <div id="content" class="site-content" role="main">
    </div><!-- #content .site-content -->
</div><!-- #primary .content-area -->

With only two small additions we’ll have a perfectly invalid WordPress Theme but we’ll be on the right track. We need to call in the header, sidebars, and footer to your theme.

At the top of index.php, before anything else, add the following template tag.

<?php get_header(); ?>

All right! Can you guess which function calls we’re going to put at the bottom of index.php?

<?php get_sidebar(); ?>
<?php get_footer(); ?>

Yep. Now we’ve got our main file that WordPress looks for, index.php. It has all the middle bits of our web page, but the top calls in the beginning bits, and the bottom calls in the ending bits.

Reload your page in the browser and check out the source code (View > Page Source, in Firefox). Look! It’s your code!

You’re on your way to making your first WordPress Theme.

How To Create a WordPress Theme

This post is part of the The ThemeShaper WordPress Theme Tutorial: 2nd Edition that will show you how to create a powerful WordPress Theme from scratch. Read it from the beginning and code yourself up something awesome.

  1. WordPress Theme Tutorial Introduction
  2. Developing Theme Sense
  3. Theme Development Tools
  4. Creating a Theme HTML Structure
  5. Template and Directory Structure
  6. Setting Up Your Theme Functions
  7. Secure Your WordPress Theme
  8. The Header Template
  9. The Index Template
  10. The Single Post, Post Attachment, & 404 Templates
  11. The Comments Template
  12. The Search Template & The Page Template
  13. The Archive Template
  14. The Sidebar Template & The Footer Template
  15. Reset-Rebuild Theme CSS & Define Your Layouts
  16. Custom Background & Custom Header
  17. Distributing Your WordPress Theme

24 thoughts on “WordPress Theme Template & Directory Structure

  1. For those wondering about the tags listed in the style.css comment header, they’re not just arbitrary descriptors; they’re chosen from a specific list to allow filtering searches on the WordPress Free Themes Directory. If you don’t intend to submit your theme to the directory, then leaving these tags out (or chosing other descriptive tags) will not hurt anything.

    The list of possible tags can be found on the More Info page of the Themes Directory, under Theme Tags.

  2. Pingback: WordPress Theme Template & Directory Structure

  3. Al says:

    notice that search.php was not included in the template file list, was it just missed or was it dropped for a reason? it is in the _s theme.

    Al

  4. Pingback: Scion Players | WordPress Theme Template & Directory Structure | ThemeShaper

  5. I was using this great tutorial to build my own theme for a client. I did notice one thing, though. The footer code only closes the page div, but shouldn’t it also close the body and html elements too?

  6. Angela says:

    Thank you for this…I look forward to learning more about HTML5 and WP.

    I’m setting up the structure in my folders as you suggested and I downloaded TextWrangler. In creating the php files…what is the code I need to paste into the text files that will allow me to save them as php or css files? Maybe I missed something…can you shed some light?

  7. When I added
    I got this error: Fatal error: Call to undefined function get_header() in C:\wamp\www\wordpress\wp-content\themes\mytheme\index.php on line 1

    But when I used include ‘header.php’;
    It worked fine. What is the cause?

  8. I’m new to WP, I went through the 17 chapters, when I run the following:

    http://localhost/lh_us/wp-content/themes/shape/

    I’m getting:

    Fatal error: Call to undefined function get_header() in C:\wamp\www\LH_US\wp-content\themes\shape\index.php on line 15

    Please advise

    With all the copy & paste I could of messed up

    Is there a download of the complete tutorial I can install local host to see how the code is supposed to work

    Thanks, John

  9. Hi John!

    The Shape theme is based on _s from Underscores.me, and it is the final product of this tutorial if you follow it exactly.

    Since this tutorial was written, _s has naturally evolved and has become even better. So the version of _s that you download from Underscores.me or Github will be different from Shape.

    One suggestion: you can use Shape as a learning tool while working through the tutorial, and then when you’re ready to build your own theme, you can either continue to build on top of Shape, or download a copy of the latest iteration of _s from Underscores.me.

    I hope this helps, let us know if you have any other questions!

  10. raidem8 says:

    So, on the theme activation. It says now activate your theme, but it only takes files in a zip form. So I am assuming the file we made in the wp-content/ file needs to be zipped first?

  11. ryentzer says:

    I ran into the issue of the theme source being blank when trying to view source in the browser. I also put ‘Hello World’ into the main div just to see it in the browser.

    After a little digging I found the answer on the Codex. (Template Hierarchy)['http://codex.wordpress.org/Template_Hierarchy#Visual_Overview'].
    Wordpress looks for page.php before index.php when the front-page is set to be a static page. ‘page.php’ (thus far in the tutorial) was blank and therefore the content in the browser was blank.

    I tested this by removing page.php from the folder structure and reloading. Sure enough, my ‘Hello world’ content showed up.

    I’m leaving this here in case others run across this issue also.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s