Anatomy of a WordPress Theme

WordPress themes live in directories residing in wp-content/themes/. A theme named “Test”, for example, might live in wp-content/themes/Test. This theme directory will hold all of the theme’s stylesheets, templates, and images. A WordPress theme must have a stylesheet called style.css. If the theme inherits its templates from another theme, then the theme directory would contain only the stylesheet and possibly some images.

The interesting case is where the theme provides its own templates. In this case, the theme directory must contain an index.php file. This is the master template for the theme, and it must exist. Other templates you most likely will want to include with your theme are comments.php and comments-popup.php. These provide the comment and popup comment templates for your theme. If you do not provide these, the default wp-comments.php and wp-comments-popup.php will be used. These default templates may not match your theme very well, so you probably will want to provide your own.

Those are the basic files needed to make a theme. Place style.css, index.php, comments.php, and comments-popup.php in their own directory beneath wp-content/themes/, and you have a theme. But wait, there’s more. WordPress can load different templates for different query types. The various query types are briefly described here. Basically, if your theme provides a template called category.php and a category is currently being queried, category.php will be loaded instead of index.php. If category.php is not present, index.php is used as usual.

Here is the list of theme files recognized by WordPress. Of course, your theme can contain any templates, stylesheets, images, or other files you wish to include. Just keep in mind that the following have special meaning to WordPress.

• style.css – The main stylesheet. This must be included with your theme.
• index.php – The main template. If your theme provides its own templates, index.php must be present.
• comments.php – The comments template. If not present, wp-comments.php is used.
• comments-popup.php – The popup comments template. If not present, wp-comments-popup.php is used.
• single.php – The single post template. Used when a single post is queried. For this and all other query templates, index.php is used if the query template is not present.
• page.php – The page template. Used when a page is queried.
• category.php – The category template. Used when a category is queried.
• author.php – The author template. Used when an author is queried.
• date.php – The date/time template. Used when a date or time is queried. Year, month, day, hour, minute, second.
• archive.php – The archive template. Used when a category, author, or date is queried. Note that this template will be overridden by category.php, author.php, and date.php for their respective query types.
• search.php – The search template. Used when a search is performed.
• 404.php – The 404 Not Found template. Used when WordPress cannot find a post that matches the query.