Notice: Undefined index: order_next_posts in /nas/content/live/gadgetmag/wp-content/plugins/smart-scroll-posts/smart-scroll-posts.php on line 194

Notice: Undefined index: post_link_target in /nas/content/live/gadgetmag/wp-content/plugins/smart-scroll-posts/smart-scroll-posts.php on line 195

Notice: Undefined index: posts_featured_size in /nas/content/live/gadgetmag/wp-content/plugins/smart-scroll-posts/smart-scroll-posts.php on line 196

Create a WordPress theme with underscores

Start building a bespoke WordPress theme using underscores, a starter theme from WordPress’s parent company Automattic

Underscores (or merely _s as it is also known) is a theme made by Automattic, the company behind WordPress itself. It’s not intended to be a parent theme with which to base any number of child themes on. Instead, the whole point is to hack the code of underscore around to do your exact bidding.

When you’re building sites for a client in WordPress, part of the initial labour is in stripping out all the functionality you don’t need from an existing theme. underscores aims to provide the mere essentials, so you can get on with what makes your site unique. Back in issue 197 we looked at using the Roots WordPress theme (, and underscores ( follows a similar vein.
The whole point is to give you what you do want and none of the niceties that aren’t necessary and end up being stripped away.
In this tutorial we’ll grab the underscores theme, see what goodies it has, and how we can use them to potentially streamline your next WordPress build.


Install WordPress

If your hosting platform has a one-click install for WordPress, that’s usually the fastest and easiest option. Alternatively, upload the latest WordPress files manually, create a database and follow the five-minute install. If you are developing locally, create a new WordPress environment in your local LAMP/MAMP/WAMP stack. A quick shortcut if you have Shell (SSH) access is to download and unzip WordPress directly.

001 mkdir underscores
 002 cd underscores
 003 wget
 004 tar xfz latest.tar.gz

Move WordPress into the root

When WordPress is downloaded, after extraction from the zip file it’s usually in its own WordPress folder. Let’s move the WordPress files into the root of our site’s folder (eg underscores). Either drag and drop through the Desktop or use the command line to move the WordPress files and then delete the empty WordPress folder and source ZIP file. Assuming you are currently in the underscores folder:

001 cd wordpress
 002 mv * ../
 003 cd ..
 004 rm -rf wordpress
 005 rm latest.tar.gz

The easy way

While it’s no use if you are cloning underscores direct to a server, when developing locally, the simplest way to create your own personalised version of the WordPress underscores theme is via Just enter your preferred theme naming parameters and it will create a custom ZIP file of underscores with all the files and functions correctly referenced for you.

Download underscores (GitHub)

The quickest way of using the theme on a server is by cloning everything directly from the GitHub repo. Open your command line environment, browse to the site folder and run the following commands. What we are doing is simply moving into the WordPress themes folder, and then copying the underscores theme from GitHub into our themes folder. Once this is all done, we will see a folder called _s in the themes folder.

 001 cd wp-content/themes
 002 git clone git://

Essential changes

If using GitHub to get underscores, it’s necessary before you move on to do a little renaming of the theme. First of all, copy or rename the _s theme folder to something more suitable (we’re using underscores_theme). If you are still at the command line, you can use the command below. Once done, you’ll need to do a theme-wide find and replace. Find _s and replace with: ‘underscores_theme’. Find:_s_ and replace with: underscores_theme_. Find: _s (notice the space before the underscore!) Replace with: underscores_theme (again with a space before). Be sure to use a name that won’t upset PHP functions (eg no hyphens).

001 mv _s underscores_theme

Find and replace

A decent text editor should have a search and replace function that will let the scope be limited to the theme folder. However, if you are happy to use the command line you can also use find and replace there. Here are examples of find and replace commands for renaming references to _s from the OS X command line (substitute references to underscores_theme with your own theme name).

001 find . -type f -print0 | xargs -0 perl -pi -e "s/'_s'/'underscores_theme'/g;"
 002 find . -type f -print0 | xargs -0 perl -pi -e "s/_s_/underscores_theme_/g;"
 003 find . -type f -print0 | xargs -0 perl -pi -e "s/_sb/Underscores_theme/g;"

Activate Underscores

In the WordPress Admin area, browse to Appearance>Themes and then click Activate under your theme name. Now take a look at the theme in the browser. Spartan indeed! First of all, you might want to amend the reference to the underscores theme in the footer. Open up footer.php in your editor of choice and amend or remove the code to suit.

 001 <?php printf( __( 'Theme: %1$s by 
 %2$s.', '_underscores_theme' ), '_underscores_
 theme', '<a href="" 
 rel="designer">Automattic</a>' ); ?>

Amending style.css

You might also want to amend the text in
style.css to suit the needs of your customised theme design. Besides the WordPress theme information up at the top there, it’s organised with some reset and normalize styles first, and then a few essential styles for things like the navigation, images, entry metadata and the like. Remember that you have to alter the style.css info to suit your new theme.

001 Theme Name: Underscores_theme
 002 Theme URI:
 003 Author: Web Designer Magazine
 004 Author URI:
 005 Description: This is a test theme for Web 
 Designer Magazine based on _s!

Basic layouts

underscores has some very basic layout styles stored in the layouts folder. They are named according to their display. For example, content-sidebar.css should put the main content to the left and the sidebar on the right. For a quick structure, copy and paste the layout that best suits your needs into the bottom of the theme’s style.css file. Keep the comments in so you know where they came from.

001 /*
 002 Theme Name: Underscores_theme
 003 Layout: Sidebar-Sidebar-Content
 004 */
 006 .site-content {
 007    float: right;
008    margin: 0 0 0 -40%;
 009    width: 100%;
 010 }
 011 #content {
 012    margin: 0 0 0 40%;
 013 }
 014 #main .widget-area {
 015     float: left;
 016     overflow: hidden;
 017     width: 20%;
 018 }
 019 .site-footer {
 020     clear: both;
 021     width: 100%;
 022 }

Add example content

If you don’t have existing content, it can help to have some example content when building up the basic layout. There are a few WordPress plug-ins that do the job; we are adding WP Example Content. From the Admin screen, go to Plugins>Add New and search for WP Example Content. Install and activate the plug-in, then select the WP Example Content menu on the left and choose Add Bundle of Sample Posts.

Create a menu

underscores supports menus, so add one from the WordPress Admin (Appearance>Menus). Name it accordingly (we’d suggest ‘Menu’) and add in links from the left-side. In this instance we have selected all the pages made by the sample content, and nested them accordingly. By default this creates a basic drop-down menu from the nested ul elements, with lots of classes by default to aid styling:

001 <ul>
 002    <li id="menu-item-29"><a href="http://
 localhost:8888/?page_id=20">Grandchild Page</
 003 </ul>

Responsive friendly

By default, underscores only adds the width attribute (at 100%) to an image; perfect for responsive designs. Furthermore, the primary menu (that we set in step 11) converts to a menu button below a certain viewport width. By default, this is set to 600px. Amend the js/small-menu.js file in these two places.

001 // Check viewport width on first load.
 002    if ( $( window ).width() < 450 )
 003        $.fn.smallMenu();
 004 // and:
 005 if ( browserWidth < 450 )

Template tags

One set of helpers in the underscores theme

is the custom template tags. The file for these can be found at inc/template-tags.php, and it includes
functions for adding classes to things like post metadata, post navigation links, comments, and the like. Just edit the file to suit adding classes where needed for styling purposes. Here, we’re adding a class of article-feedback to comments:

001 <article id="comment-<?php comment_ID(); ?>">

Custom headers

Although not enabled by default, underscores provides a custom header implementation. To enable it, first open the functions.php file and at the bottom of the file is a commented section. Uncomment the following section, save the file and then open inc/custom-header.php.

001 /**
 002 * Implement the Custom Header feature
 003 */
 004 require( get_template_directory() . '/inc/custom-header.php' );

Amending header.php

At the top of the inc/custom-header.php file is a code snippet (starting around line 8). It begins <?php $header_image = get_header_image();. Copy this snippet and open header.php in the root of the theme folder, then copy in that snippet. We added it just after the opening <header id=”masthead” class=”site-header” role=”banner”> tag.

001 <?php $header_image = get_header_image();
 002    if ( ! empty( $header_image ) ) { ?>
 003        <a href="<?php echo esc_url( home_url( 
 '/' ) ); ?>" title="<?php echo esc_attr( 
 get_bloginfo( 'name', 'display' ) ); ?>" 
 004            <img src="<?php header_image(); ?>" 
 width="<?php echo get_custom_header()->width; 
 ?>" height="<?php echo get_custom_header()-
 >height; ?>" alt="" />
 005        </a>
 006    <?php } // if ( ! empty( $header_image ) ) ?>

Including Modernizer

As underscores uses HTML5 markup, it includes the ubiquitous HTML5 shiv for Internet Explorer 9 and below (referenced in the header.php file). However, if you need to provide fallbacks for different browser features you may prefer to include the HTML5 shiv with Modernizr ( instead. Save a version of Modernizr (including the shiv option) to the JS folder and strip this line from header.php:

001 <!--[if lt IE 9]>
 002 <script src="<?php echo get_template_
 directory_uri(); ?>/js/html5.js" type="text/
 003 <![endif]-->

Enqueue Modernizr

Open the functions.php file and look for the section commented as Enqueue scripts and styles. Under the existing small-menu section, insert the following code. This loads Modernizr.js and provides a version of 2.6.1 for Modernizr (amend this to suit the version you are using). Note: if supporting IE8 you may want Modernizr to load in the head instead of the footer.

001 wp_enqueue_script( 'modernizr', get_template_directory_uri() . '/js/modernizr.js', 
 array( 'jquery' ), '2.6.1', true );

Register the sidebar

Now we have the code to display the output of the sidebar, we need to register it with WordPress. Adding the following code under the previous step will add the sidebar into the Widgets section of the WordPress admin. You can now drag the widget onto a sidebar and see the results.

001 wp_register_
 002    ‘author_box_
 003    ‘Author Box’,          
 004    ‘your_widget_display’,  
 005    array(                  
 006        ‘description’ => ‘Display 
 information about the blog author in your 
 007    )
 008 );

Enable theme options

There are sample theme options to play with in underscores. Open the functions.php file, browse to the section commented as Custom Theme Options, uncomment the file load section as below and then open the Admin panel and head to Appearance>Theme Options. You’ll see that it ships with a few types (checkbox, text input, select options, radio buttons and a text area).

001 /**
 002 * Custom Theme Options
 003 */require( get_template_directory() . '/inc/theme-options/theme-options.php' );

Amend Theme Options

To use the theme options, open inc/theme-options/theme-options.php and amend the code to suit the options you want to provide. In this instance, we have amended the text input field to say Disclaimer Title (line 44) and the label (line 186).

001 // line 44
 002 add_settings_field( 'sample_text_input', __( 'Disclaimer Title', '_underscores_theme' ), 'underscores_theme_settings_field_sample_text_
 input', 'theme_options', 'general' );
001 // line 186
 002 <label for="sample-text-input"><?php _e( 'Disclaimer text input', '_underscores_theme' ); ?></label>

Amend the text area

We also want to amend the text area field, so amend that to suit (lines 47 and 243 respectively). If you don’t want the other options to appear in the Admin