WordPress has become the most widely used blogging platform in the world, estimated to be used on a quarter of a billion websites online today. WordPress works as a blog, but also as a straightforward content management system, ready to use with search-engine-friendly URLs and fully valid HTML and CSS.With so many sites using WordPress and only about 1,200 themes listed on WordPress.org, there are inevitably lots of sites looking exactly the same. You and your clients need to stand out, or end up being branded as “just another WordPress blog.”In this article, I’ll show you how to take an existing HTML and CSS site template and convert it into a theme for WordPress. Of course, WordPress theming is much too vast a topic to cover entirely in a single article, so I’ll provide you with some resources at the end to further your learning. It’s hoped, though, that this article will serve as a good introduction and give you a solid foundation to start learning aboutcreating your own WordPress themes.I’m assuming you already know HTML and CSS, and already have a site design that you want to adapt to WordPress. Being familiar with PHP is unnecessary, as I’ll be explaining every function you need as we use it.
WordPress Theme Basics
WordPress themes live in a folder inside the
/wp-content/themes/ directory in your WordPress installation. Each theme’s folder includes a few essential components:
- A main CSS file. This is just a regular CSS file, except for a few extra details at the top, which I’ll be explaining shortly. You can, of course, have more CSS files if you need to (a print style sheet, for example).
index.php, the main index file that WordPress loads when you’re using the theme.
The contents of the
index.php page can also be split up into several other files, which would then be included in
index.php. Normally, these are:
header.php: contains the first part of the template, usually starting from the doctype and extending to just after the page’s header (including the site and page title, and navigation elements).
sidebar.php: similar to the
header.phpfile, it includes elements that appear in the sidebar. You can enable this to work with widgets in WordPress, or, if you prefer, you can enter the content directly into the theme files.
footer.php: normally called last in the page, and usually placed from the end of the page content through to the bottom of the web page.
comments.php: defines the structure of the comments section for each post. If you leave this out of your theme, the
comments.phpfile from the default theme will be used.
There can be other PHP files, but these are optional. You can add files that provide a specific layout for certain pages, such as category pages, single posts, or posts with a given tag. It’s also common to have templates for site errors like 404s.Once you have your HTML template that you’re ready to convert—whether you’ve written it from scratch, had it designed, or bought it from a template marketplace—you can convert it into a WordPress theme in very little time.
Starting Your Theme
Ideally, before you begin, you need an installation of WordPress up and running, which is available free from WordPress.org. When you’re creating the theme, it’s easiest to work on the files locally or on a local VM, although you could also work on a web server over FTP.First, you need a folder for the theme. This needs to be created inside
/wp-content/themes/ in your WordPress installation directory. It’s as simple as creating a new directory with a name related to your theme. Inside this, you’ll start off with your style sheet, which also includes some information about the theme that will be used in the administration panel later.Create a CSS file named
style.css, and add the following at the top of the file:
/*Theme Name: [A unique theme name here]Theme URI: [The theme website]Description: [A description]Author: [Your name]Author URI: [Your website].[Any other comments].*/
This is a comment block (enclosed by
*/), but WordPress reads this information and presents it on the theme selection screen in the administration interface.You need to insert content for each of these items. They’re mostly aimed at themes that will be distributed, so if you only plan to use the theme on your own site, most of the values are of little consequence. Make sure the theme’s name differs from any other themes you have installed, or it will cause problems!There’s also the option of adding a version number with the
Version: label.At this point, if you’re converting an existing HTML/CSS site, it should be easy enough to copy and paste all of your style information into this file from your original template’s CSS.
Next up, it’s the
index.php file. The easiestway to begin is by copying and pasting all of the content from the mainHTML file in your site template into this new file.We’ll start by replacing some of the hard-coded information in the file with dynamic content that will be generated on the fly by WordPress.WordPress has a built-in function called
bloginfo for accessing all types of information about the installation and the theme. We’ll use this to fetch the style sheet URL and the location of the RSS feed.
bloginfo is extremely simple to use:
<?php bloginfo('stylesheet_url'); ?>
In this example, I’ve included the style sheet URL; however, it works for a whole range of parameters including the
charset, blog description, and template directory. For a full list, see the WordPressCodex.Looking at your template, you now want to replace the
link element pointing to your style sheet with a line like this:
Example 1. (excerpt)
<link rel="stylesheet" href="<?php bloginfo('stylesheet_url'); ?>" type="text/css" />
?> will be replaced by the return value of the function, which in this case will be the URL pointing to your style sheet. This is perfect, because your website will now contain a line like:
<link rel="stylesheet" href="http://example/blog/wp-content/themes/style.css" type="text/css" />
The key to building WordPress themes is to take the process we’ve just gone through and repeat it for every bit of content on your site: take your existing HTML and find the parts of it that should be included dynamically. Then find the WordPress function that will return the value you want and insert it, either between the HTML tags or inside an attribute, as we did for the style sheet URL.
Of course, your CSS file most likely references a number of images, so it’s necessary at this point to move those over to your theme directory. While there are no set rules for how you name image and other asset directories within a theme folder, it’s worth adding a new folder called
js folders, but for the sake of this article, I’ll assume you’re sticking with a single
assets folder. Move all your images to the new folder.You need to change any references to the old image locations that existed before the template was converted to a WordPress theme to the new locations. Find and replace works in virtually every text editor out there, and is the easiest way to achieve this. Look for references to the old path (for example,
images/ up to just before the filename, including the trailing slash), and replace them with the following:
<?php bloginfo('template_directory') ?>/assets/
This will change all references to the path to the new folder your theme lives in. The
assets directory is where the images are now housed.If the location of the images relative to the CSS file have changed, a quick find and replace from the old folder name to the new one should make short work of this.Now, you should have a copy of your HTML, CSS, and images all set up and working in WordPress. To check, save it and try setting WordPress to use your theme, and see what happens. You should receive a duplicate of the original HTML template, only now it’s being generated by WordPress. There should be no WordPress content in there just yet, though.
The Header, the Footer, and the Sidebar
The next task will be to split the content into the header, footer, sidebar if you have one, and the rest of the page. Bearing in mind that the header, footer, and sidebar code remains unchanged on all pages (as a general rule), start by working from the top of the
until you reach the beginning of your sidebar or your main page content (depending on which one is first in the source), and select everything from the beginning to this point. This will usually include your page title, logo, and navigation menu.Cut and paste this into a new file, and save it in the same location as your
file with the name
. The filename is important, as WordPress will go looking for this file when you ask it to insert the header in your pages. Speaking of which, let’s tell WordPress to do this. In the place of the code you cut out of
, put the following line:
<?php get_header(); ?>
code tells WordPress to include the content from your
Learn PHP for free!
Make the leap into server-side programming with a comprehensive cover of PHP & MySQL.
RRP $11.95 Yours absolutely free
file at that location in the page.Next, we’ll do the same for the page’s footer: cut all the footer material from
and paste it into a new file called
, replacing it with:
<?php get_footer(); ?>
Finally, do the same action with your sidebar, saving it as
and replacing it with
<?php get_sidebar(); ?>
.It’s worth checking again to see that your page is still working at this point. We haven’t made any changes, just split it up into separate files, but it’s good to verify that everything is still working.
At this point, your site is just showing static HTML contained in your template, rather than fetching live data from WordPress. It’s time to change that.In WordPress, you use template tags to tell WordPress what content to fetch and insert into a page. There’s a definitive list of them on the WordPress Codex, but if you’ve been following this far, you’ve already met a few of them!
are all template tags.These tags can be added to any PHP file within the theme, so a good place to start is at the top of your site, with the
file.Let’s start at the very beginning of the file. The
can remain as is. The opening html tag can include a lang attribute, and WordPress provides this with the
template tag. So, we can replace the html tag with:
<html xmlns="http://www.w3.org/1999/xhtml" <?php language_attributes(); ?>
This will generate an attribute along the lines of:
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
If you’ve included any scripts, it’s worth moving them to the
by including these lines:
<link rel="alternate" type="application/rss+xml" title="<?php bloginfo('name'); ?> RSS Feed" href="<?php bloginfo('rss2_url'); ?>" /><link rel="pingback" href="<?php bloginfo('pingback_url'); ?>" />
With that done, you now need to include the
<?php wp_head(); ?>
The final element in the HTML head is the page title. Most WordPress themes use some variation of the following:
<title><?php bloginfo('name'); ?> <?php wp_title('-'); ?></title>
This will include the name of the blog, which can be defined in the WordPress settings, followed by the page title. For example, if the page is a single article, it will show the article’s title. The
in brackets is the separator, which will be placed before the
content if (and only if) there’s a title to display. This means that the title of my blog’s home page will be “My Blog,” whereas the title of an article on my blog will be “My Blog: Article Title.” WordPress is smart, and will only include the separator if it’s needed.Still in the
file, we’ll now move onto the body tag. This part will vary more depending on the structure of your template, but work through it andlook for any content that should be pulled in from WordPress. For example, if the website title appears in the code as
, it should be replaced with
<h1><?php bloginfo('name'); ?></h1>
.The template tags you’re most likely to need at this point are:
: the URL of the blog’s home page
: the URL of the blog’s RSS feed
: the description of the blog, as defined in the WordPress settings
As with the other template tags we’ve seen, these need to be put inside
tags; they can sit anywhere inside the PHP file, even inside your HTML tags.Moving your site’s navigation into WordPress can be a bit trickier. There are template tags that can provide you with lists of categories or lists of pages, which you can then use to create parts of your navigation. The template tags are
<?php wp_list_categories(); ?>
<?php wp_list_pages(); ?>
, and will provide you with lists of hyperlinks that you can style as you would a static navigation list. However, sometimes you need your pages to appear in a specific order, or you need to exclude certain pages. Much of this is possible by passing certain parameters to
. To learn more about how to manipulate this tag,
If you plan on releasing your theme to the wider community, it’s important that you widgetize the sidebar. Widgets are chunks of content that can be added to predefined areas in a theme via the WordPress administration panel. For example, you could have a widget area at the top of your sidebar, where the blog owner could easily add a list of pages or an arbitrary block of HTML. Widgets are beyond the scope of this tutorial, but you can read more about them on the WordPress Codex.Other tags you may like to add to your sidebar include (again wrapped in
: lists all the blog’s authors as
li elements. If they have authored posts, their name will be a link to a page showing all their posts.
: outputs the links that have been added in the
Linkssection of the administration panel, and is also wrapped in li tags.
: displays a cloud of all the tags that have been added to your posts.
Your footer section should be easy to handle now that you have a feel for template tags. If you need to output content we haven’t covered here, be sure to look for an appropriate template tag in the Codex. Remember to close any tags that are open in your
file, such as body or any wrapper divs.As you’ve worked through this, you probably tried viewing the page at various points to test it. Whether or not that’s the case, when you view the page now, it should include all the content being pulled from WordPress, except the main body of the page.
The Main Blog Content
Now that we’ve defined the content for the header, footer, and sidebar, it’s time to turn to our page’s core content. We’ll now go back to our
file and implement the WordPress Loop. The Loop is the mechanism WordPress uses to cycle through the posts that are to be displayed on a given page, and output the content for each of them.It begins like this:
<?php if (have_posts()) : ?><?php while (have_posts()) : the_post(); ?>
These two lines check to see if any posts have been provided. Depending on which page you’re viewing, different posts will be available. For example, on the main blog page, a certain number of the most recent posts will be shown. If you’re viewing a specific post, then only that post will be provided to the Loop. For category, tag, or author pages all posts belonging to that tag, category, or author will be shown.With those two lines in place, we’re now inside the loop. We now need to instruct WordPress to execute a few lines of code individually for each post in the set. For example:
<h2><a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>"><?php the_title(); ?></a></h2><small><?php the_time('F jS, Y') ?> by <?php the_author() ?> </small>
This example section begins with an h2 tag containing the post title, which is linked to that post’s page. Beneath this, the post time and author are listed, wrapped in the small tags. There are a number of new template tags here, and many others you can use to customize your template to display the HTML you want for each. Here are some of the more common ones:
: the URL of the permanent hyperlink to the post.
: the post’s title.
the_time('F jS, Y')
: displays the post’s date in “January 1st, 2010” format. To format the date differently, replace
'F jS, Y'
PHP date format string.
: displays the name of and links to the archive for the user who wrote the post.
: inserts the post content. There’s no need to place this inside
tags, as this will be done automatically.
: displays the name of and links to the archive of the post’s category.
The easiest way to make your post display match your existing template is to cut and paste your template’s sample content code inside the WordPress loop. Then insert the appropriate template tag into each part of the post’s HTML. Once you’ve included everything you want, it’s time to end the loop with
<?php endwhile; ?>
. This runs once all the posts have been processed. Ideally, it should be followed by some navigation controls:
<div class="navigation"> <div class="alignleft"><?php previous_posts_link('« Previous Entries') ?></div> <div class="alignright"><?php next_posts_link('Next Entries »') ?></div></div>
Each page displays a certain number of posts, as defined in the WordPress settings. These controls will allow your visitors to navigate back to older posts with Next and Previous links. The parameter passed to
(the string in parentheses) the text to be used for the link.At this point, note that the
structure has been closed, but the
is still open. I need to elaborate on this a little. It’s possible that a page will have no posts to display (for example, your home page before you’ve added any posts, or an archive page for a month in which no posts were published.) In those cases,
will evaluate to
, so none of the template code you’ve just written will be run.For those cases, you’ll want to provide some fallback content. So,we first need to define the
condition, and thenclose the
statement with PHP’s
<?php else: ?><p>Sorry, there are no posts to display.</p><?php endif; ?>
For this example, we’ve simply added a paragraph telling the that there were no posts found for the page. You could also add a box or links to other parts of your site, to help visitors find their back to the content they’re looking for.
In our simple example,
is being as the template for every page on the site. But if you want to modify aspect of the template only on a specific page (or group of WordPress lets you do that easily. All you need to do is
with more specific template files. example, you can create a
file, and template will be used for single post pages instead of
file. Similarly, there
(for search results),
(for the home page), and a number of othertemplate files you can create to customize each separate area of yoursite.
If you’ve followed along with this entire tutorial, you have:
- imported the content from your HTML template into your WordPress theme files
- included a few bits of code to tell WordPress where the different pieces of content go
- added some menus and links that WordPress puts together automatically
- begun familiarizing yourself with the WordPress loop and the ideas behind WordPress theming
There’s a lot more to creating a WordPress theme than what I’ve beenable to cover here, of course. I hope I’ve whet your appetite to learnmore.
If you enjoyed reading this post, you’ll love Learnable; the place to learn fresh skills and techniques from the masters. Members get instant access to all of SitePoint’s ebooks and interactive online courses, like The Beginner’s Guide to Web Design with WordPress.
Comments on this article are closed. Have a question about WordPress? Why not ask it on our forums?
Jump Start Git, 2nd Edition
Visual Studio Code: End-to-End Editing and Debugging Tools for Web Developers