A 1000-Hour Head Start: Introducing The _s Theme

Have you checked out the Toolbox theme? Up until recently it was the starter theme we used to build free and premium themes on WordPress.com. Toolbox was (and is!) a great theme, but it could be better. Unfortunately, we wound up in a situation with Toolbox where we wanted to make some more drastic improvements to it as a starter theme but got a little stuck. We had people using it as a Parent Theme and that meant that the simplest id or class change could become a problem. Simply changing an id of #branding to #masthead in the template is enough to break most CSS.

And there were other more beneficial but potentially more disruptive changes we thought would be great to add to it. Changes like better starter styles, including a generic framework for adding your own responsive CSS; a script for elegantly handling menus on small screens; and easy-to-rework sample theme options. And whole lot more. The sort of things we found ourselves adding to 80% of the themes we were building. You know, the sort of things that you really need in a starter theme.

So, we forked Toolbox — don’t worry it’s still being updated — and made a better, faster, stronger, starter theme. A developer-only theme that gives us the freedom — us being the WordPress.com Theme Team — to iterate with abandon on the idea of WordPress starter themes. Since that theme underscores the new themes we build we call it the Underscores Theme, or _s for short.

And it’s pretty darn awesome.

It’s a starter theme — blank seems appropriate

So, what’s so different about _s? Well, most importantly it’s that it will always be more or less in flux. It’ll be looked at again and again, always with an eye to the future of WordPress themes. But it will also always have one foot in the past. In fact that past goes pretty deep. It incorporates code and tough lessons learned from the best WordPress themes: Kubrick, The Sandbox, Thematic, Twenty Ten, Toolbox, Twenty Eleven —and probably more I’ve forgotten about! — and then, any future theme that continues to shoot for the very best in WordPress and web standards, including every version of the yearly default theme. As each new default theme is released, _s will be reviewed and updated. New techniques and best practices will continue to make their way into _s. Likewise with every theme the WordPress.com Theme Team builds using _s. As we come up with new best practices and learn new lessons in our themes, all that code makes its way back to _s.

And we’re pretty excited about making that code available for you.

Free Open Source Software FTW

This is why: The lineage and continual development process of _s gives you what I like to call a a 1000-hour head start. That’s the approximate number of design and development hours you get for free every time you use it in a project. Weeks and weeks of refinement by dozens of WordPress theme experts over several years that you don’t have to do. And because we want you to be able to take advantage of that 1000-hour head start we’re making _s available through GitHub for all your WordPress theme projects. When we make updates to _s, those changes get pulled from the same Automattic theme repository we’re using live on WordPress.com and pushed out to GitHub where you can quickly take advantage of them.

And it’s free.

Here’s what’s currently in _s:

  • A just right amount of lean, well-commented, modern, HTML5 templates.
  • A helpful 404 template.
  • A sample custom header implementation in inc/custom-header.php that can be activated by uncommenting one line in functions.php and adding the code snippet found in the comments of inc/custom-header.php to your header.php template.
  • Custom template tags in inc/template-tags that keep your templates clean and neat and prevent code duplication.
  • Some small tweaks in /inc/extras.php that can improve your theming experience. They can be activated by uncommenting one line in functions.php.
  • Keyboard navigation for image attachment templates. The script can be found in js/keyboard-image-navigation.js and is enqueued from the image attachment template, image.php.
  • A script at js/navigation.js that makes your menu a toggled dropdown for small screens (like your phone) ready for CSS artistry. It’s enqueued in functions.php.
  • 5 sample CSS layouts in /layouts: Two sidebars on the left, two sidebars on the right, a sidebar on either side of your content, and two-column layouts with sidebars on either side.
  • Smartly organized starter CSS in style.css that will help you to quickly get your design off the ground.
  • The GPL license in license.txt. 🙂 Use it to make something cool.

There’s more development on the way but you can start using it right now. We are. 🙂

Get the _s Theme

Fork or download _s on GitHub or generate your own custom version at Underscores.me and have fun making awesome new WordPress themes! I know that’s what I’ll be busy trying to do.

166 thoughts on “A 1000-Hour Head Start: Introducing The _s Theme”

  1. You should really fix that mess inside <title> tag and replace it with a simple wp_title filter in functions.php. And bloginfo( 'stylesheet_url' ) CSS along with wp_enqueue_script( 'comment-reply' ); should be moved too. Otherwise you have _s_scripts in functions.php and the rest in header.php, which doesn’t look good.

      1. That’s good to hear because that “title” tag thing has been bothering me since the release of TwentyTen (see this blog post).

        One question though — why are you calling if ( ! function_exists( '_s_setup' ) ): only for _s_setup and not for _s_scripts and _s_widgets_init. They all have add_action calls which can be easily removed if one wishes.

      1. I guess so. However, I think it’s better to use standard action calls to add or remove specific parent theme functionality. In order to have your own child _s_setup() function, simply call remove_action('after_setup_theme', '_s_setup') and add your own add_action('after_setup_theme', '_s_child_setup').

        No child theme should have the same function names as the parent theme.

    1. Not yet. I think that moves into the 20% realm of user concerns. That said that’s one of the reasons I’m glad we’ve put _s on GitHub. Someone will consider adding more developed layout styles to _s and maintain a fork of it there for all of us to use. Maybe it’ll be you—or me! I’m hoping to see lots eventually. 🙂

  2. Had a quick peek earlier, I’ve got to say, it’s an interesting name to go for! 😉 Would I be wrong in saying Twenty Twelve has probably been developed (so far) from _s or not? I’m almost positive the code looks similar, that or I’m going crazy? OK no need to answer that one! 😛

    1. Great eyes, Mark!

      In fact, Twenty Twelve did *not* have _s code in it at the start. The fact that they look so similar was a funny, but true, story.

      What I mean is, we didn’t just take _s and change some names and submit it to core as Twenty Twelve. Here’s the story of what happened.

      Ian had been hacking on _s for a while, taking the best of Toolbox and all the things we’ve been learning, feedback from tons of bug reports, and adding things in, cutting things out, et cetera. All the stuff he talked about in this blog post.

      Independently and around the same time, without looking at the code in _s very closely, I had already started on the base code for Twenty Twelve (no styles, just the bare bones template).

      Steps I took:

      1. I opened both Twenty Ten and Twenty Eleven in TextMate and in a file comparison app (FileMerge.app)
      2. I duplicated Twenty Eleven to make a new theme in my working directory, then opening it in TextMate I went through and changed “eleven” to “twelve” everywhere in the new theme (about 15 minutes)
      3. Then using FileMerge and TextMate I went line-by-line and file-by-file; this took about 4-5 hours.
      4. I deleting a whole bunch of stuff from the new theme, while closely comparing it to the previous 2 default themes to make sure I kept the important pieces
      4. A day or two passed by …
      5. Ian mentioned in our work chatroom, something about the _s theme he was working on, and I thought to myself, “Self, you should really go see what he’s doing over there”
      6. I took my modified Twenty Twelve theme and opened it side-by-side in FileMerge with _s, and did a visual diff on the two, file-by-file. Surprise!! We’d reached almost the exact same end point in the code, without talking about it or planning it.

      Pretty cool.

      Of course now that a bunch of people are hacking away at _s I’ll keep an eye on it, and see if any of the bug fixes would be good to have in the default WordPress theme. Other than than they are two very different themes.

      Same with Twenty Twelve; having it in core will mean hundreds of expert eyes on it, and millions using it eventually. Those bugs and fixes I’ll try to bring back to _s if I can.

      They are really for different purposes:

      _s is a starter theme to hack on and fork and make your own. We fork it each time we make an Automattic theme.

      Twenty Twelve is the default WP theme, and has to include certain core features. If I were to use it for a project I’d probably use a child theme.

    2. Just for fun—and to bore our grandkids with WP theme history lessons, here’s the actual chat logs of my “AHA” moment.

      Jan 17 21:48:39 in the Theme Team chatroom

      lance: ian-support: Something funny happened to me today :)
      lance: I took Twenty Eleven and "cleaned it out" to just what I thought were the basics, for Drew to use
      lance: Then I diffed with _s, and was really surprised :)
      lance: I lol'd
      ian-support: What did you see?
      lance: My results were almost exactly the same result
      lance: As your rework
      ian-support: This does not surprise me :)
      lance: It was a good exercise
      lance: Anyway, thought it was a cool thing
      ian-support: It should be better than a cleaned up twenty eleven by the end of the month
      ian-support: Anyway, so Twenty Ten > Toolbox > Duster > Twenty Eleven and then I reviewed Toolbox for improvements after Twenty Eleven launched and then Toolbox > _s
      ian-support: _s will be compared against the default theme every time it launches
      lance: It's a logical progression, for sure
      ian-support: So, that's why a cleaned up Twenty Eleven looks like _s
      lance: I'm in agreement, and happy with the findings
  3. Love your work Ian. This is totally cool and I hope Automattic support it for the long haul… especially since we’ve just started building our first _s theme for gamefroot.com – which is coming soon to an interwebs near you 😛

  4. Why you remove this code

    <html id="ie6" >
    <html id="ie7" >
    <html id="ie8" >
    <html >

    I think this line important to get a unique ID’s for IE ?

    1. We no longer support IE6 and 7 in new themes (and I don’t think anyone should as a blanket principle) so it didn’t make sense for it to remain there. In the rare cases where you need to target IE8 in your CSS it’s easily added back in.

  5. Some nice additions to Toolbox here. Great work.

    Q: Did the basic responsive setup not make the cut? I don’t see any responsive-ness built in to _s….unless I’m missing it somewhere.



    1. It’s in there in the fluid layouts and the responsive menu script but there could be and likely will be more. I’m just really conservative about throwing in a bunch of arbitrary breakpoints and calling it an improvement to responsive theme development.

  6. Great! I’d be interested to see a derivative of this combined with Twitter Bootstrap as well.

    I didn’t see anything that would register and enqueue the supplied css layouts, not even commented out as you did for template tags, tweaks and theme options… I had to add it manually to check the layouts out. I guess more elaborative instructions would help on how to start. I also noticed there are no page templates to select from within the page editor, so they should be created separately with appropriate headings/names.

    Otherwise great start! I hope you guys stick with it for the future default themes and may be even push it as desired clean slate for building a theme for Theme Directory submissions. This way you’ll definitely have enough case studies to polish it out as well as receive help from the community 🙂

    1. The current exclusion of a method for including the sample layouts (and the exclusion of page templates) is intentional. It’s meant to be really light. That said we might have something neat to do with that in the future.

  7. Pingback: _s | Nick Hamze
  8. I just found out about this theme from Dan Milward’s tweet. It’s interesting what you have here. Where can I see the demo site? Is this theme available for wordpress.com users? Thanks

  9. Great news, thanks Automattic! Just wanted to add a +1 for Twitter Bootstrap and basic starter page templates.

    Justin, can you explain a bit more about why you didn’t include page templates? Do you see responsive CSS as the ultimate replacement for page templates?

    1. I’m not sure in what way responsive design could replace custom page templates but my reasoning for not including them in _s is pretty simple. They’re custom and should be created on per-theme, case by case. No reason other than that really.

      I am starting to see an interest and need in more designed alternate stylesheets for _s though. It’s something I’ve been thinking about.

  10. Thanks for the new code source. I’ve been looking at TwentyTwelve hecticly for the best features for my new framework, so this should make for interesting ‘reading material’.

    I’d like to stay on top of these developments. How can I get more involved?

    Cheer and great work btw.

  11. So, if I clone from GitHub, rename each instance of _s with my own name as per the readme.txt, then do a git pull after an update, all my edits are overwritten?

      1. Yeah but:

        When we make updates to _s, those changes get pulled from the same Automattic theme repository we’re using live on WordPress.com and pushed out to GitHub where you can quickly take advantage of them.

        So if you make and edit a copy of the cloned theme, it won’t get the updates, ever. So you’ll never take advantage of them.

      2. This is where I am stuck too. Maybe it is my lack of knowledge on Git. If I clone and create a fork, how I do stay in sync with any updates made to _s ? What am I missing? I want to build on top of _s and not necessarily create a derivative of _s.

    1. This is what I’m curious about too…

      So if I want to build my own theme upon _s, I just clone and build out my style.css and work in my theme options and functionality? Then I merge it in the future _s releases? Or do I fork it, then build upon my fork?

      Sorry, I am new go versioning and git. Perhaps I need to find more tutorials… if anyone has links to WP + github related tutorials I would love your face forever ❤

  12. The small-menu script doesn’t seem to work for me. When i manually reduce the size of my Chrome (v.18-beta) window to below 600px the pages dissapear and the ‘menu’ button appears, however whien i click it, it doesn’t work. Also when i visit http://underscore.wordpress.com on my iPhone, the link to ‘about’ is still visible. Just tought i’d let you know.

    1. Sorry, my bad, the about-link i tough i was seeing was actually the header of the about-page. Mea culpa… The comment about the menu-button not functioning after resizing Chrome still stands though! On further investigation, it seems $( this ).toggleClass( 'toggled-on' ); gets triggered 4 times in this scenario when the h1 with class menu-toggle is clicked.

      1. It’s working correctly for me in Chrome but the menu toggle is a little buggy until it gets some styling on it. Let me know if you’re still running into issues with it.

      2. @Ian- I’m experiencing the same problem on chrome, my cursor turns to a pointer but the menu does not toggle unless i refresh the page at under the 600px.

  13. Gee, thanks Ian… you’ve just made more work for me, because I immediately want to rebuild my own starter theme with all the stuff you’ve put into this one. So thanks a lot for putting enough into this one that I can’t put off rebuilding my own starter theme. Yeah. Thanks.


  14. Good Evening,

    I am totally interested in the progression of this new Starter Theme for Automattic AND the upcoming Twenty Twelve default theme. What are the chances of seeing the integration of “Adaptive Images” into the core of WordPress?

  15. Hi Ian, this is absolutely fantastic. I’ve given _s a cursory glance so far, love what I see, and will definitely be using it as a base for my next theme to give it a proper go.

    Looking forward to seeing what things make their way in (and out?) as time goes on too!

  16. Just watched the project on GitHub. It’s very interesting when WP.com jumps into the theme starter battle :D. There’re many of them over there, but I want something well documented, WP focused and good coding style (standards + practices). I found that in TwentyTen + TwentyEleven and really exciting about the _s. Definitely will use it for my themes!

  17. Taking a look at it, and noticed this in the readme:

    1. Search for _s inside single quotations to capture the text domain.
    2. Search for _s_ for to capture all the function names
    3. Search for _s with a space before it to replace all the occurrences of it in comments.

    I realize there are lots of ways to do search/replace.
    Here is one way (tested in cygwin):

    perl -pi -e "s/'_s'/'mytheme'/g;s/_s_/mytheme_/g;s/ _s/MyTheme/g" $(find . -name '*.php' -o -name '*.css')

  18. Wow. Amazing. Just what I was looking for. I tried some frameworks first, but then I came at themeshaper.com and found this _s! Thank You Ian. 🙂

  19. Sorry if this is a dumb question but I don’t really understand the licence terms. The licence seems to say that I can do whatever I want as long as I let other people redistribute my modified version in any way they want too. So, can I use this as a basis to create a commercial (for profit) theme? Thanks!

    1. Yep! It’s the same license all the best commercial theme guys (StudioPress, WooThemes, Theme Foundry, Press75, etc.) all use. Do what they do and you’ll be doing it right.

      1. Still a little confused by this. If we use this as a starter theme which we then build a custom theme off of and sell on themeforest, people are only allowed to use the theme which we created on one website (per themeforest license). Is this ok, because it sounds a little different than “as long as I let other people redistribute my modified version in any way they want too”.. they can’t redistribute a theme they buy on themeforest.

        If it was MIT license I would understand, but the GNU license is a little confusing when you are selling a theme.

        1. You can do whatever you want with _s as long as you continue to let other people do whatever they want with what you build and distribute with it. The MIT license and the GPL license are compatible.

  20. Hey and BIG THANXX for this new blank theme!
    …but i wann build a 3 column layout (sidebar content sidebar). But when i code this i never get a tertiary div….. even when i try the samples, i dont will got any success!..
    how i have to do this???
    greetz from berlin/germany!!

  21. Loving _s, and building a new theme on it has been great!

    I’ve never seen comment_form() before, and the codex doesn’t make the use of this function much clearer – how does one best go about customizing the comment form now?

  22. Hey, next dumb question XD…
    whem i rename “” in my own like “”, the loop and the admin bar disappear??? i renamed every other “_s”, but this gets an error. what im doing wrong???

      1. Oh yeah, I think this too! But here, I have only design standard adobe package… without the dreamweaver I love so much 8D.
        I did it with aptana studio and there, you cant search and replace at the whole project. This isnt cool! I’ll try it, when I’m back home for sure!

        Big up to you for your personal support! Go on!

  23. Do you folks have a guide to creating a new theme using _s as a starter? I’ve been hand coding sites with html and css for ages using MovableType as a CMS (not using themes) where I’d build a site from scratch with my own css class and ID structure, and then I’d insert MovableType code into the finished html page templates. I understand how WordPress works, but I’m baffled by all of the built in css structure (classes and IDs already defined by the system rather than the site designer, which I guess explains the need to reset css. Reseting css on a page that’s being loaded seems like such an odd practice).

    I’d really like to use _s, and I’d very much like to find a step by step guide if one exists. I assume I have to do more than search/replace _s and then style the pre-existing style.css, yes?

  24. Hi,
    I just started using ‘Toolbox’ yesterday for my first time in a new site I’m developing when I realized you have launched ‘_s’. I have a couple of newbie questions:
    – Should I modify _s or create a child theme ( with other themes I always have done the second). Pros and cons?
    – Is there anything for what Toolbox is better than _s?
    Thank you!

    1. _s is made for modifying so go ahead and do that. That also points to Toolbox’s strength: if you want to use it as a parent theme, go for it, it won’t be changing much.

  25. I’m LOVING _s! I started learning WordPress last year by dabbling with finished themes, but that was frustrating. I’m learning so much more, and so much faster, by creating my own theme with _s.

    Question: Is there a reason for the “main” div that begins at the end of the header and ends at the beginning of the footer? I feel like I’m missing something obvious. It seems like “main” only contains the “primary” div, but I’m not sure why.


    1. Glad it’s helping, Rob! To be honest, the main div is a little crufty but it can come in handy with the occasional design and, in my opinion, a good little div that helps the code look better when I’m inspecting it in the browser. That said, I might get rid of it one day and you certainly can too if you’re not using it. In fact, I encourage it. 🙂

  26. Ian, I just came across this on my way to the Thematic guide. My question: is there any relation at all to the Thematic project here?

    There’s a few of us Thematic users that are looking to see the project continue and grow. Part of the community is taking an active role in that. Is _s the answer to our concerns?

    1. Hey Rob. No relation except that they’re both themes that attempt to give you a leg up on theme creation. If I was going to rebuild a theme framework from scratch — or if you wanted to make your own — I would start with _s.

      1. Excuse me, I’m a newbie, maybe my question is stupid:
        how about when you update “_s”? Then won’t I become crazy to update my sites made starting upon “_s”?
        (I’m sure you’ll care about that, but you can say somethign that soothes me from now).
        Thank you!

  27. I’m curious – what editor/IDE are you using for the CSS work (and in general)?
    Looking at the pattern of the comment headings in the CSS suggests that there’s something nice going on in your dev environment..

    /* =Content
    ----------------------------------------------- *

  28. Hello,

    I am having an issue with all the drop down menus falling behind text. This is also present in the demo link you posted earlier. Can you please fix that? I would appreciate it greatly.

  29. Here is a good question that I was waiting for someone else to ask:
    Does it automatically add some useful classes to posts and pages like the famous Thematic framework?

Comments are closed.