Select Page

WordPress Theme Development using Underscores (_s) – Part 1

Underscores is a WordPress starter theme and is 100% GPL. It is a blank theme and is developed & maintained by Atomattic. They are none other than the company who runs, Jetpack plugin, Akismet plugin & Gravatar.

Why Underscores (_s) ?

You must have this question in mind that why you should use underscores, so let me explain. However you have bunch of different ways to develop a WordPress theme, but the main reason of using _S as a base theme is that:

  • It gives you a 1000-HOUR HEAD START.
  • It’s open-source 100% GPL.
  • Always up-to-date with the latest WordPress code standards having around 95 contributors on github.
  • Includes well-commented, modern HTML5 templates.
  • It’s not bloated with any CSS framework, options framework, JavaScript library.

Still not convinced? Lets see who is using underscores:

I hope you are now ready to start with WordPress theme development using Underscores. Lets start!

How to build a WordPress theme with Underscores (_S)

The steps would be as follows:

  • Setup your WordPress development environment.
  • Generate a fresh _s theme, install & activate it.
  • Underscores Theme file structure overview.
  • Adding CSS styling & Customizing Theme Files. (Covered in Part 2)

Setup your WordPress development environment

There are already many tutorials available for this, so I won’t cover this in my tutorial however I am referring some good ones here:

So you are free to whatever option you like to use for setting up your development environment, you can also google for more tutorials if you do not find the above mentioned tutorials useful.

You are also free to directly work on a live server if you like, however developing on a local server is always preferred and speeds up the whole development time.

Generate a fresh _s theme, install & activate it

Now i assume you have set up your development environment and installed a fresh WordPress on it. Now lets head over to the underscores home page and click on the “Advanced Options” link.


Now fill in all your details in the input fields and tick the checkbox also and than click the GENERATE Button.


Now you should have a zip folder containing your new custom _s theme. Install it to your new local (or live) WordPress installation and activate it.

A quick video on how to upload & activate WordPress theme:

Now as you have activated your new theme if you will view your website from front-end it will look like a little messy to you at first, but don’t worry this is the plus point of this base theme as stated above, it’s a blank theme with very little base CSS and is not bloated with any useless stuff itself and therefore is like an empty glass which we can fill with whatever we like.


So the next part would be customizing our new theme as per our new web design. For our example we actually got inspired by the new design of Chris Lema and tried to make our blog theme similar. Here i want to make it clear that we did not clone it exactly, neither we copy any of the code or graphic from his website, we just got inspiration from his blog and this is purely legit (in our opinion at-least). Also let me point down that his website is built over rainmaker platform & the theme / framework used is Genesis Themes. This will be covered in part 2.

Underscores Theme file structure overview:

underscores-filesLets explore the files comes with the underscore themes. Do not get scared with the number of files it has, they are well organize as per the standards of WordPress and well coded obviously.

Files in Root

As you can see in the screenshot most of the files are self-explanatory by names. Lets understand what file does what by understanding the structure of a website.

As you may know the website could be structured with following files:

  • Header
  • Footer
  • Content Section
  • Sidebar

As illustrated in bellow diagram, the basic structure of a website with the theme files mentioned. The header is controlled by the file “header.php”, sidebarby file “sidebar.php” and footer by file “footer.php”.

You may notice that i skipped about mentioning Content Section, this part basically is bit tricky but we have it covered very well by Template Hierarchy.


Now lets understand what files used for generating the content section of a WordPress website. The Content section of a website is dynamic, which means it changes from page to page, and thus uses specific files based on the type of WordPress page is being loaded.

The default file for content section is “index.php“, WordPress uses this as the last file in your theme. However it first look your theme for other specific files by name and use it instead of “index.php”.

WordPress Posts

This refers to a Single Post, for this WordPress uses file”single.php” if available for generating the Content Section. However in Underscores theme this file only provides the structure mainly and includes another file in the “template-parts” directory named “content-single.php“. Which displays the single post content, thus if a WordPress post is loaded those 2 files are responsible for generating Content Section’s content.

WordPress Pages

Now if a WordPress page is loaded, the file “page.php” is being loaded (if available) and again this file also includes another file in the “template-parts” directory called “content-page.php” which displays the content of a page.

Read more about Posts VS Pages. If you are confused !

Archives, Search Results, and Error Pages

Beside the Posts & Pages there are other type of WordPress pages as well, lets look at them as a list with files classification:

  • Archive Pages, Files (archive.php, content.php). This may further classify as: 
    • Category Archive Pages
    • Tag Archive Pages
    • Date Archive Pages
    • Author Archive Pages
  • Search Result Page, Files (search.php, content-search.php)
  • Error Page, Files (404.php)

Default File

As mentioned above the default theme file is “index.php” and if any of the above files will be missing from your WordPress theme (however underscores has all those files) the default index file will be loaded in place of it.

Thus now you should be clear how the files in Underscores theme are structured as per WordPress standards. And Understand the theme structure very well, lets revise the above diagram here as follows:



The above completes the entire structure of any kind of WordPress page, however if you look into the underscores theme folder you will notice more files as well, lets have a look at them.

Comment File

In root there is a file “comments.php” which is responsible for the WordPress comments functionality. It makes the comments display, pings & displays comments form on a WordPress post or page. This is being included in “single.php” & “page.php” files.

Functions File

This is an important file as well in a WordPress theme and WordPress looks for it in a theme root. It is used to setup theme functionality mainly.  Underscores includes a lot of useful and necessary functionality already in functions.php file, such as:

  • Make theme available for translation.
  • Enable support for Post Thumbnails on posts and pages.
  • Primary Menu Registration.
  • Enable support for Post Formats.
  • Custom background feature.
  • Register widget areas.
  • Enqueue scripts and styles.
  • Custom Header feature.
  • more…

Stylesheet File

There is also stylesheet files in a WordPress theme. Underscores comes with a “style.css” file which contains the very basic css to give you a foundation to further style your theme/website. There is also another stylesheet file you can see which is “rtl.css” which is an RTL (right to left) stylesheet. This is being used for right to left languages such as (urdu, arabic, etc).

Screenshot File

There is also a file called “screenshot.png” which is an image file and uses at different spots such as theme’s section in WordPress. Underscores includes a blank screenshot file, however you may update it to your theme’s screenshot.

More Files & Directories

Underscore includes some more files and organized in some directories. However there is no restriction of using the same directories, but Underscores uses them for the sake of better files organization.

“inc” directory:

This contains some PHP files which are to extend the functions.php file mainly.  Files included are:

  • custom-header.php
  • customizer.php
  • extras.php
  • jetpack.php
  • template-tags.php

“js” directory:

As name defines it includes some javascript files:

  • customizer.js
  • navigation.js
  • skip-link-focus-fix.js

“languages” directory:

If you are willing to make your theme translatable to other languages, than this is the directory to provide necessary files.  Underscores already include a “.pot” file.

“layouts” directory:

This contains 2 stylesheet files:

  • content-sidebar.css
  • sidebar-content.css

As the above structure diagrams shows a 2 column layout with the content section column on left & sidebar column on right. However it depends on your project you may want to change the layout to a left column sidebar (sidebar-content) so these 2 files can help you achieve either layout.

“sass” directory (optional):

If you are a sass user and have ticked the checkbox which says “_sassify!” at the time og generating the new underscores theme. Than you will have this additional directory in your theme. Which contains all the sass files for your theme.

“template-parts” directory:

Lastly we have this directory which is being in discussion above which contains some PHP files for content section.

  • content.php
  • content-none.php
  • content-page.php
  • content-search.php
  • content-single.php

What’s next

Now that you have a detailed understanding with the underscores theme and you have installed a blank theme. However this still looks blank. Now in the next tutorial i will walk you through the process of how we customized the underscores theme to make our CakeWP blog website. That will help you dig deep into custom theme development using underscores.

Stay tuned & Subscribe us to get notified as soon the part 2 gets published!