I remember when I first tried to learn the WordPress Codex. It was way more difficult than it had any right to be, not only because of the strange format of WordPress themes (Why would you call a function to start a loop?) but also because WordPress didn't ship with any theme that could serve as a good example.

The default theme was, and still is, too bloated for learners to wrap their heads around. It has too many features, too many branches, and too many sub-templates extending the main template, due to the fact that it also needs to serve as a showcase for all of WordPress's features. I resorted to downloading the most minimalistic third-party theme that I could find, cleaned it up some more, and used it as a base for all the themes I've written since then.

I'm glad that someone finally made an open-source theme specifically for the purpose of being a rock-solid base for other themes. This is something that should have been done by the core developers 10 years ago. I don't know how much longer we'll have to suffer the sprawling spaghetti monster that WordPress is, but since a lot of us are stuck with it anyway, why not make our lives easier for the time being!

P.S. Please add a link to the GitHub repository, too. Some of us prefer git clones to tarballs.

The excellent Automattic-published starter theme Underscores [1] has been around for over a year now, and it's precursor, Toolbox [2], has been around since at least mid-2010. Both were designed by the core developers to be open-source bases for other themes, and indeed have been the base for all the official themes for three years now. There are also other base themes like Bones [3] and Roots [4] which are very popular, but are too heavy for my liking.

[1]: http://underscores.me/ [2]: http://wordpress.org/extend/themes/toolbox [3]: http://themble.com/bones/ [4]: http://www.rootstheme.com/

Also, I'm getting nitpicky here, but you also don't exactly call a function to start a loop. You call a function to fetch the posts in an object. You then use a pretty bog-standard while loop to loop through that object. You do call a method of said post object to determine whether or not the loop should continue - is that considered bad practise generally?

I understand why a lot of people think the WP loop is badly constructed. The start of a typical loop in WP is this:

    if (have_posts()) : while (have_posts()) : the_post();

which is essentially shorthand for this:

    if (have_posts()) {
    	while (have_posts()) {
    		the_post();
    	} 
    }

I think the cause for some misgivings is that people might not realised that have_posts() is actually doing this:

    return $wp_query->have_posts();

So you're actually just running a method on the global post object. You'll make similar post objects for custom queries, and interact with them in an identical fashion.

The reason that many people think the WP loop is badly constructed is because it entirely works by side effects. A (very simple) WP loop looks like this:

    <?php while (have_posts()) : the_post() ?>
      <h2><?php the_title() ?></h2>
      <?php the_content() ?>
    <?php endwhile ?>

There are four unique functions there. All of them depend on non-obvious global state and three of them are used specifically to produce side effects. the_post() invisibly overwrites a global and changes an iterator. It not only mutates global state, but it does something different if you accidentally call it twice. And WP's the_whatever() functions echo something and return nothing?! Want to do some filtering on the title before you print it? Better use get_the_whatever() instead. WTF?! Heres how it should work:

    <?php foreach ($post in $wpdb->get_posts() : ?>
      <h2><?= $post->title ?></h2>
      <?= $post->content ?>
    <?php endforeach ?>

You're completely right on that, and I couldn't agree more; the mystery of the global states is frustrating to a new WP developer.

Additionally, Wordpress has tons and tons of bad functions. If so many themes weren't dependent on them, I'd advocate for entirely stripping out a good chunk of them. Someone needs to write Wordpress: The Good Parts, or at least a really canonical good practise guide. I guess it could be a good weekend project.

For the functions you mention, you're actually not too far off what they really do. the_title() [1] is just slightly formatting get_the_title [2], which is mostly just returning $post->post_title.

Unfortunately, skipping the built-in functions means also skipping the slightly obtuse but powerful filter system. However, if you're not interested in the built in WP stuff, then there's no harm in outputting the titles directly.

Btw, yes, I realise this is mostly academic in the context we're talking about.

[1]: http://core.trac.wordpress.org/browser/tags/3.5.1/wp-include... [2]: http://core.trac.wordpress.org/browser/tags/3.5.1/wp-include...

The experience I related above took place around 2008/9. Sorry if that's a bit out of date. I looked through your links and it does look like there have been recent efforts to produce bare-bones themes, though the OP's theme is much better documented. What I really want to see is a version of the Codex that actually guides the user through an exemplary theme, and OP's theme comes pretty close to that.

And yes, I'm referring to the weird `if (have_posts()): while (have_posts()): the_post();` boilerplate. Back then, for a PHP newbie like me, it looked like a magical one-liner ... until I realized that the loop actually terminates hundreds of lines later with an endwhile/endif statement. It's so easy for newbies to miss the significance of the two colons, especially if they're not familiar with the "alternate syntax for control structures".

Although I now understand how the loop works, it still pisses me off that I have to call a function to populate a bunch of hidden variables/objects that are later fetched by other functions. Too much going on behind the scenes == difficult to grok. A simple foreach() loop would have been much more intuitive. Perhaps this will happen sometime soon using the Iterator interface, now that WordPress has finally left PHP 4 behind.

There were a few others that I think were around in 2008, like Starkers, but my memory's a bit fuzzy so don't take that with any great authority.

I definitely agree that a best-practise step-by-step theme construction guide in the Codex would be very useful. I still see many themes using things like query_posts() instead of creating a new WP_Query or a hooking into the pre_get_posts filter. As I mentioned below, Wordpress would ideally have its built-in functions trimmed dramatically, though this would really murder backwards compatibility.

I don't really think it's Wordpress's fault that the Loop uses the alternative PHP control structure, but I agree that the Loop's Codex page is abominable. You may or may not be aware that the Codex is a wiki, and thus poor quality information can and will be added.

I would like to see a loop using the Iterator class. However, there are quite a few complexities to that, as mentioned in this feature request [1]. They also point out that you can foreach and count on $wp_query->posts, so you can get to your information in a more obvious PHP-friendly way for now.

[1]:http://core.trac.wordpress.org/ticket/20297

Why do you need the if? Shouldn't the while loop run zero times if have_posts() returns NULL or an empty array?

It's idiomatic to use the if so you can do this

    <?php if (have_posts()) : while (have_posts()) : the_post() ?>
      <!-- do loop stuff -->
    <?php endwhile; else : ?>
      <!-- no posts found, show a default or error of some sort -->
    <?php endif ?>

Got it. Thank you.

AGREED! WordPress should actually have a "Naked" theme as one of the defaults, absolutely. Why a well-commented naked theme isn't part of the default WordPress install has never made sense. I had to make my own with each new version of WordPress so far so when I start a new project from scratch I have a clean slate and an updated empty theme.

lol... Readme.md is empty!

This could be useful as a starter theme for people who are still learning wordpress. Thanks!

EDIT: I often have to teach other developers the basics of Wordpress - just pointing someone to the Codex sometimes isn't good enough, especially on a tight deadline. This theme can really help out.

And seriously, enough with the negative comments about Wordpress. Love it or hate it, it's there to stay, and it's in our best interests to educate developers how to theme it correctly.

This is one of the better things to come across Hacker News recently. People will hate on Wordpress all they want, but at the end of the day I still have to support a bunch of clients that use it.

Thanks, and I completely agree with you about clients.

If your job is to make Wordpress websites and you don't know how to make Wordpress websites, then you should not be making Wordpress websites.

On the other hand: if your job is to make websites, and the client wants a wordpress website, then you make a wordpress website. IMO the "design a website" requirement is the creative challenge, not the "slice into files for wordpress" part.

Of course, that could just be the bias of my own skillset talking.

This isn't aimed at people whose job it is to write Wordpress themes. It's aimed at people who want to learn to write Wordpress themes, for fun or profit.

No need to hate on new, useful teaching aids. Everyone needs to start somewhere!

Fixed it: If your desire is to have a job making Wordpress websites and you don't know how to make Wordpress websites, then you should be making Wordpress websites.

There is also http://underscores.me/ which is very well maintained and popular (Github here https://github.com/automattic/_s ).

Bones is a similar project based on HTML5 Boilerplate, source is on GitHub: https://github.com/eddiemachado/bones

I wouldn't think the primary problem with a non-coder working with wordpress would be an inability to look up a function in the docs. Once you've gotten to that point, the actual looking up is trivial. There are a lot of other steps you need to follow first, and knowing how to do them or that they even need to be done would seem to me a greater impediment: setting up a local server, creating a database for the install, getting the wp-config.php file, configuring said file (knowing the database credentials), knowing what a theme is and why you need one, understanding the theme files and hierarchy, being able to read php well enough to understand a functions is even being called, etc.

None of these things are particularly difficult, and they all have good documentation and tutorials, but I would think someone who was resistant to looking up a function signature would probably get bogged down and give up somewhere higher up on the list.

Now, this could still be useful for learners, I just don't know that the target is designers who can't be bothered to learn.

Not sure about the designer part myself, but in the consultation agency where I work, we often do custom themes for clients. Installing wordpress and configuring it is easy enough, even for new developers - but getting them to understand the intricacies of theme development can be a bit tricky.

The themes included with wordpress, twenty-eleven and twenty-twelve can be too complex, and have a lot of cruft we don't need. So we usually start with a skeleton theme, like this one - although this one is a particularly well documented skeleton theme.

Sometimes it takes an example theme like this to make things 'click' for a new developer. For that reason alone, it can be very useful.

Yes, for a new developer. But for a designer who doesn't have time to learn the codex?

I was hoping the solution would include something other than WordPress.

This is cool! but this presentation has one of the worst examples of chrome's windows font rendering issues i've seen.. chrome: http://i.imgur.com/DT6qDKg.jpg ff: http://i.imgur.com/bUG6sxi.jpg

"many designers don’t have the time to learn the WordPress Codex. It’s huge. It’s intimidating. It’s confusing." — maybe it's just because I know Wordpress quite well, but the documentation I found when learning years ago (it's even better now) wasn't difficult at all. The Wordpress community is so big that you can Google solutions to most problems, find solutions and learn at the same time.

Of course being a designer and not a developer, you're going to struggle learning syntax and convention (that goes for any language or application like Wordpress). Stick with it, the Codex is great.

It's true the Twenty Ten and Twenty Eleven default Wordpress themes were bloated and if you were trying to use them as a base or learn, you'd probably be overwhelmed by the kitchen sink approach the core team took when creating those themes. Having said that, if you want a clean starting base for a theme, try using the bundled Twenty Twelve: http://wordpress.org/extend/themes/twentytwelve — which is arguably the best default theme ever to grace Wordpress. Most naked themes you encounter for Wordpress aren't naked at all (Bones especially abstracting an already abstracted CMS even more).

Having said that, this naked theme looks good. It's actually naked and well commented but not naked to the point it's really any less simple than Twenty Twelve (just less files). The benefit of considering a default theme as a starting base is that you get to see how the experts develop a Wordpress theme and the added bonus of how to use the custom background functionality and the Theme Customization API as well.

This kind of reminds me of my Actual Barebones HTML5 Github: https://github.com/Vheissu/Actually-Barebones-HTML5-Template — It's literally a HTML file that gives you a HTML5 structure without assuming you want jQuery or anything of the sorts. The term naked and barebones seems to have lost a lot of meaning in the web world.

This is a good, simple theme, at least in PHP terms, and is certainly well commented.

However, I think it heavily falls down in it's ambition of being a good general-purpose starter theme by making some strongly opinionated decisions out of the box. There's far too much grid code in the CSS. It also bizarrely bundles fittext and fitvid, two excellent libraries which have nothing to do with Wordpress.

I would also argue that anyone building a Wordpress theme should be looking things up on the Codex. You don't have to "learn" the Codex any more than you have to "learn" the dictionary. It's there as a reliable and canonical reference, and telling people not to use it will result in bad code and confused developers.

I never sat down to "learn" the WP Codex either. I began with the most simple and bare-bones WP template there was, and slowly built up on my foundation as I needed the features.

A quick Google search usually brings up the most relevant Codex page and while their code examples aren't always the best, the web usually provides enough user-written tutorials to get my the solution I need.

I appreciate you making this and have downloaded a copy to learn from. While I usually develop websites using Rails, more and more of my clients are asking about WordPress. I cringe a little each time (yes, I'm one of the ones who would rather not build sites with WordPress), but at the end of the day, I am in the business of helping clients get their stuff done online—if that means doing it with WordPress, then I'll dig in and get it done. To that end, this will be a helpful resource for me. Thanks.

I do believe this approach to commenting a basic theme could drastically help Wordpress theming beginners. I would go one step further, however, and also try to add links back to the documentation for the function calls, hooks, filters, etc.

For those interested, this would add a significant amount of reading material so they could have a better understanding.

True. It had occurred to me, but I thought it might gum up the readability quite a bit with URLs in the comments. Probably a good idea, though.

This is pretty great. I've been developing on WordPress for 7 years now. Can write my own plugins and functions and the like, but it's all self taught. I'll be giving this a once-over to see if I can learn something (or more likely learn something I already know, but learn it the "right" way). I'm sure I can.

Looking forward to having a proper look at this.

I mostly use Starkers as a totally bare bones template starting point. If anyone is interested: http://viewportindustries.com/products/starkers/

Starkers is good for barebones, but I don't think it's filling the same void as this theme.

Don't know wordpress? lucky bastards.

A little dramatic? I don't think you do your clients any favors by scaring them with nonsense. What alternatives do you typically push? Are they better because they are more to your taste, or are they better for your clients?

It's not dramatic if you appreciate not having panicked clients calling you at 2am because Turkish hackers have swapped out the main page or worse, RBN is distributing BlackHole from their site. I am not particularly keen on pretending I'm a hosting provider (even if it's extremely profitable), because I don't want phone calls at 2am about problems from something I built six months ago. I'm old enough that I know what I want and what I don't want in life, and I am not ashamed of this.

I'm a developer, not a babysitter, and while I can stand guaranteeing a product I build, I cannot and will not try to guarantee a product that stands a very good chance of being hosed by some retarded exploit (relative to a custom product). Since I'm not in the babysitting business, "better" for my clients is a product that won't be the Turkish graffiti or BlackHole distribution engine in six months' time.

It also needs to be said that for some reason lately, clients have consulted developers who have put it into their heads that using WP automagically brings your price and development time down by half, regardless of the circumstances. That's absurd, but it's usually the first real question I field about the technology we use to build products and services. If a client really wants to know the specific reasons why we don't use WP, you can bet that I don't have a problem explaining this exactly as I've explained it to you, albeit perhaps with different terminology. Simply put, I don't use WP because it is too risky versus the custom product we build, and that whole mess is something I don't want to clean (for free, which is what they'll demand when it happens). Even if I "maximize" some profit margin using it, I still feel that I'd be doing a disservice to my client. I'm totally honest with my clients, and if they insist I use WP, I insist they go somewhere else. And at the end of the day, if you aren't honest with your clients, you're a bad developer and a bad person.

That's my opinion, and I realize other people feel very differently, and that's fine.

Well, I think you are pointing out issues with clients in general. A well maintained and well managed WordPress site is going to be more secure than something custom built. Having said that, if said clients installs all kinds of stuff willy nilly, that is an extra burden I can see that (you could lock that ability down though). If you can fully satisfy a clients needs with something custom and do it cost effectively all the better.

That certain clients have unrealistic expectations because WP should be cutting dev time in half etc, that's an interesting point. I think client education factors in here.

You can be running another CMS or something custom and run into security exploits all the same though, if not more so. Something custom doesn't get the same amount of eyeballs from developers to ensure everything is secure. And even static sites can be hacked and abused if a hacker gains access to the server.

You make a good point here, and it's true that I shop around for "the right kind" of client. I read an article some years ago (on HN) about firing terrible clients at the same time we were having trouble with one client in particular. I resolved to never even negotiate with a client that I think is going to cause problems for myself or my team. We haven't looked back, and it's been one of the best decisions I've ever made for the company. When a potential client starts insisting on this magic time/money saving thing called WordPress even after I explain my concerns, I know that they're probably not a good fit and start recommending other developers in the area that we know that do quality work with WordPress. And there is absolutely no shortage of those kinds of developers, so the client will end up getting what they want.

On security, the custom code we have written and deploy for our customers is stuff that I trust, because it's something we built ourselves and are extremely familiar with. Our products also come with a built-in automated "security service" that helps tremendously in keeping us from being the lowest-hanging fruit. Importantly, not even using WordPress immediately shuts down the near-constant traffic on the internet devoted to finding insecure WP deployments. While I completely agree that a WordPress deployment in the right hands can be as secure as anything out there, I don't trust the codebase in general, and certainly not as much as I trust my own code, despite there being a large number of coders sifting through WP. And all bets are always off if an attacker gains entry into the hosting provider.

As a specific example, WordPress doesn't use PDO at all, instead using the mysql_ functions (not even mysqli_). This is a pretty glaring problem from my point of view. The excuse WP core developers have used is that it's basically too tightly-coupled to use anything but MySQL (and specifically the mysql_ functions). That's a pretty big red flag to me, when a developer says that their product is too tightly-coupled to stop using functions that have been officially deprecated in the language for quite a long time. In fact, the feature request for PDO in WP is a kind of in-joke to outsiders (http://core.trac.wordpress.org/ticket/21663).

Also (and importantly), I don't sell myself as a WordPress developer, but as a custom web and mobile applications developer. I have done this intentionally so that I won't succumb to the temptation to start rolling out quick and dirty WP deployments, but instead focusing on providing a custom-built, quality product that I can honestly say they can trust to function well and function securely for a long time to come.

good job,

I just realised the theme is under GNU General Public License, does this means I have to share my modifications to the theme?, what if i want to build on it and sell it?

thanks

Solution implies there is a problem.

Mui elegante, sir.