Add new theme documentation

CHANGELOG.md

@@ -1,4 +1,5 @@
 ### HEAD
+* Add bundled docs
 * Update all templates to use [PHP Alternative Syntax](http://php.net/manual/en/control-structures.alternative-syntax.php)
 * Update to Bootstrap 2.1
 * Add MIT License

README.md

@@ -5,12 +5,16 @@ Roots is a starting WordPress theme made for developers that’s based on [HTML5
 ## Installation
 
 * Clone the git repo - `git clone git://github.com/retlehs/roots.git` - or [download it](https://github.com/retlehs/roots/zipball/master)
-* Read [Theme Activation](https://github.com/retlehs/roots/wiki/Theme-activation) to understand everything that happens once you activate Roots
+* Reference the [theme activation](/retlehs/roots/blob/master/doc/activation.md) documentation to understand everything that happens once you activate Roots
 
 ## Configuration
 
 Edit `lib/config.php` to enable support for major functionality and to define constants that are used throughout the theme.
 
+## Documentation
+
+Take a look at the [documentation table of contents](/retlehs/roots/blob/master/doc/README.md).
+
 ## Features
 
 * HTML5 Boilerplate’s markup and `.htaccess`
@@ -30,17 +34,15 @@ Everyone is welcome to help improve this project. There are several ways you can
 
 * Reporting issues (please read [issue guidelines](https://github.com/necolas/issue-guidelines))
 * Suggesting new features
-* Writing or editing [docs](https://github.com/retlehs/roots/wiki)
+* Writing or editing [docs](/retlehs/roots/blob/master/doc/README.md)
 * Writing or refactoring code
 * Fixing [issues](https://github.com/retlehs/roots/issues)
 * Replying to questions on the [mailing list](http://groups.google.com/group/roots-theme)
-* [Donating](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=4K7D3BCQZ4Z72&lc=US&item_name=Roots%20Theme&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted)
 
 ## Project information
 
 * Source: [https://github.com/retlehs/roots](https://github.com/retlehs/roots)
 * Web: [http://www.rootstheme.com/](http://www.rootstheme.com/)
-* Docs: [https://github.com/retlehs/roots/wiki](https://github.com/retlehs/roots/wiki)
 * Mailing list: [http://groups.google.com/group/roots-theme](http://groups.google.com/group/roots-theme)
 * Twitter: [@retlehs](https://twitter.com/#!/retlehs)
 * Contributors: [https://github.com/retlehs/roots/contributors](https://github.com/retlehs/roots/contributors)

doc/README.md

@@ -0,0 +1,21 @@
+[Roots Theme homepage](http://www.rootstheme.com/)
+
+# Roots Theme documentation
+
+Roots is a starting WordPress theme made for developers that’s based on [HTML5 Boilerplate](http://html5boilerplate.com/) and [Bootstrap from Twitter](http://twitter.github.com/bootstrap/).
+
+## Getting started
+
+* [Usage](usage.md) — Overview of the project contents.
+* [FAQ](faq.md) — Frequently asked questions, along with their answers.
+
+## The core of Roots
+* [Theme library](lib.md) — A guide to the `lib/` directory which contains all of the theme functionality, including: [theme activation](activation.md), the [theme wrapper](wrapper.md), [clean up](cleanup.md), and [rewrites](rewrites.md).
+* [Theme templates](templates.md) — A guide to the `templates/` directory which contains all of the theme templates.
+
+## Development
+
+* [Contributing to Roots](contribute.md) — Guidelines on how to
+  contribute effectively.
+* [Extending and customizing Roots](extend.md) — Going further with
+  Roots.

doc/activation.md

@@ -0,0 +1,28 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Theme activation
+
+Theme activation is handled by `lib/activation.php`.
+
+After you activate Roots from the WordPress admin you'll be redirected to an activation options page where you can choose to:
+
+### Create static front page	
+
+Create a page called Home and set it to be the static front page. This is normally handled from the Reading settings.
+
+### Change permalink structure
+
+Change permalink structure to `/%postname%/`. This is normally handled from the Permalinks settings.
+
+### Change uploads folder
+
+Change uploads folder to `/assets/` instead of `/wp-content/uploads/`. This is normally handled from the Media settings.
+
+### Create navigation menu
+
+Create the Primary Navigation menu and set the location. This is normally handled from the Menus section under Appearance.
+
+### Add pages to menu
+
+Add all published pages to the Primary Navigation. On a fresh install, this will add the new Home page and existing Sample Page to the navigation.

doc/cleanup.md

@@ -0,0 +1,88 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Clean up
+
+Clean up is handled by `lib/cleanup.php`. Major parts include:
+
+### wp_head() clean up
+
+1. Remove unnecessary `<link>`'s
+2. Remove inline CSS used by Recent Comments widget
+3. Remove inline CSS used by posts with galleries
+4. Remove self-closing tag and change `'`'s to `"`'s on `rel_canonical()`
+
+### Add and remove body_class() classes
+
+1. Add `top-navbar` class to `<body>` if using Bootstrap's navbar (enabled in `lib/config.php`). Used to add styling in `app.css` to account for the WordPress admin bar.
+2. Add post/page slug class to `<body>`
+3. Remove `page-template-default` class
+
+### Root relative URLs
+
+Root relative URLs are enabled from `lib/config.php`. 
+
+Return URLs such as `/assets/css/app.css` instead of `http://example.com/assets/css/app.css`.
+
+### Wrap embedded media as suggested by Readability
+
+The [Readability article publishing guidelines](http://www.readability.com/developers/guidelines#publisher) suggest wrapping embedded media with a class of `entry-content-asset`. 
+
+### Use HTML5 figure and figcaption for images with captions
+
+Any images that contain captions will be returned with `<figure>` and `<figcaption>` elements. They also get a `caption` class for additional styling from Bootstrap.
+
+### Clean up gallery_shortcode()
+
+The `[gallery]` shortcode has been re-created to use Bootstrap thumbnail styling.
+
+### Remove unnecessary dashboard widgets
+
+1. Remove Incoming Links
+2. Remove Plugins
+3. Remove WordPress Blog
+4. Remove Other WordPress News
+
+### Clean up the_excerpt()
+
+The excerpt length is defined in `lib/config.php`. Excerpts are ended with anchor to the post and with "… Continued" instead of "[…]".
+
+### Cleaner walker for wp_nav_menu()
+
+Walker_Nav_Menu (WordPress default) example output:
+
+     <li id="menu-item-8" class="menu-item menu-item-type-post_type menu-item-object-page menu-item-8"><a href="/">Home</a></li>
+     <li id="menu-item-9" class="menu-item menu-item-type-post_type menu-item-object-page menu-item-9"><a href="/sample-page/">Sample Page</a></l
+ 
+Roots_Nav_Walker example output:
+
+    <li class="menu-home"><a href="/">Home</a></li>
+    <li class="menu-sample-page"><a href="/sample-page/">Sample Page</a></li>
+    
+If using the Bootstrap top navbar (enabled in `lib/config.php`), the proper markup is added to the items and the depth is restricted to 2 (Bootstrap doesn't support multi-level dropdowns).
+
+Instead of the many different active class varities that WordPress usually uses, only `active` is returned on active items. 
+
+### Remove unnecessary self-closing tags
+
+Self-closing tags aren't necessary with HTML5. They're removed on:
+
+1. `get_avatar()` (`<img />`)
+2. `comment_id_fields()` (`<input />`) 
+3. `post_thumbnail_html()` (`<img />`)
+
+### Don't return the default description in the RSS feed if it hasn't been changed
+
+If your site tagline is still `Just another WordPress site` then the description isn't returned in the feed.
+
+### Allow more tags in TinyMCE
+
+Allow `<iframe>` and `<script>` to be used without issues.
+
+### Add additional classes onto widgets
+
+Add `widget-first`, `widget-last`, and `widget-X` (X is the position) classes to widgets.
+
+### Clean up search URLs
+
+Redirect `/?s=query` to `/search/query/`, convert `%20` to `+`.

doc/contribute.md

@@ -0,0 +1,93 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Contributing to Roots Theme
+
+## Reporting issues
+
+A bug is a _demonstrable problem_ that is caused by the code in the
+repository.
+
+Please read the following guidelines for reporting bugs:
+Please read the following guidelines before you [report an issue](https://github.com/retlehs/roots/issues):
+
+1. **Use the GitHub issue search** — check if the issue has already been
+   reported. If it has been, please comment on the existing issue.
+
+2. **Check if the issue has been fixed** — the latest `master` or
+   development branch may already contain a fix.
+
+3. **Isolate the problem to Roots** — make sure that the code in the
+   Roots repository is _definitely_ responsible for the issue. Switch to a default WordPress theme to confirm problems before reporting an issue. Any issues related to HTML5 Boilerplate or Bootstrap should be reported to their respected repositories.
+
+Please try to be as detailed as possible in your report too. What is your
+environment? What steps will reproduce the issue? What browser(s) and OS
+experience the problem? What would you expect to be the outcome? All these
+details will help people to assess and fix any potential bugs.
+
+### Example of a good bug report:
+
+> Short and descriptive title
+>
+> A summary of the issue and the server OS environment in which it occurs. If
+> suitable, include the steps required to reproduce the bug.
+>
+> 1. This is the first step
+> 2. This is the second step
+> 3. Further steps, etc.
+>
+> Any other information you want to share that is relevant to the issue being
+> reported. This might include the lines of code that you have identified as
+> causing the bug, and potential solutions (and your opinions on their
+> merits).
+
+A good bug report shouldn't leave people needing to chase you up to get further
+information that is required to assess or fix the bug.
+
+**[File a bug report](https://github.com/retlehs/roots/issues)**
+
+
+## Pull requests
+
+Good pull requests — patches, improvements, new features — are a fantastic
+help. They should remain focused in scope and avoid containing unrelated
+commits.
+
+If your contribution involves a significant amount of work or substantial
+changes to any part of the project, please open an issue to discuss it first.
+
+Please follow this process; it's the best way to get your work included in the
+project:
+
+1. [Fork](http://help.github.com/fork-a-repo/) the project.
+
+2. Clone your fork (`git clone
+   https://github.com/<your-username>/roots.git`).
+
+3. Add an `upstream` remote (`git remote add upstream
+   https://github.com/retlehs/roots.git`).
+
+4. Get the latest changes from upstream (e.g. `git pull upstream
+   <dev-branch>`).
+
+5. Create a new topic branch to contain your feature, change, or fix (`git
+   checkout -b <topic-branch-name>`).
+
+6. Make sure that your changes adhere to the current coding conventions used
+   throughout the project - indentation, accurate comments, etc. Please update
+   any documentation that is relevant to the change you are making.
+
+7. Commit your changes in logical chunks; use git's [interactive
+   rebase](https://help.github.com/articles/interactive-rebase) feature to tidy
+   up your commits before making them public. Please adhere to these [git commit
+   message
+   guidelines](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+   or your pull request is unlikely be merged into the main project.
+
+8. Locally merge (or rebase) the upstream branch into your topic branch.
+
+9. Push your topic branch up to your fork (`git push origin
+   <topic-branch-name>`).
+
+10. [Open a Pull Request](http://help.github.com/send-pull-requests/) with a
+    clear title and description. Please mention which browsers you tested in.

doc/extend.md

@@ -0,0 +1,8 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Extend and customize Roots
+Here is some useful advice for how you can make your project with Roots even better.
+
+* [Recommended plugins](plugins.md)
+

doc/faq.md

@@ -0,0 +1,16 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Frequently asked questions
+
+### Do I need to upgrade my sites each time a new version of Roots is released?
+
+No. You don't normally replace the foundations of a house once it has been
+built. There is nothing stopping you from trying to work in the latest changes
+but you'll have to assess the costs/benefits of doing so.
+
+
+### Where can I get help for support questions?
+
+Please ask for help on the
+[Google Group](https://groups.google.com/forum/?fromgroups#!forum/roots-theme).

doc/lib.md

@@ -0,0 +1,129 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Theme library
+
+### actions.php
+
+This file is used to hook into [WordPress actions](http://codex.wordpress.org/Plugin_API/Action_Reference). 
+
+The `roots_feed_link()` function is used to hook into `wp_head()` to return a feed link if your site has any posts.
+
+The `roots_google_analytics()` function is used to hook into `wp_footer()` to return the [asynchronous Google Analytics snippet](http://mathiasbynens.be/notes/async-analytics-snippet) from HTML5 Boilerplate if an ID is defined in `config.php`.
+
+### activation.php
+
+This file handles the theme activation. [About the theme activation](activation.md).
+
+### cleanup.php
+
+This file handles the various WordPress clean up. [About the clean up](cleanup.md).
+
+### config.php
+
+This file is used to enable various theme features, define which pages get the sidebar, set the CSS classes for `#main` and `#sidebar`, set a Google Analytics ID, and set the post excerpt length.
+
+#### Enable theme features
+
+`add_theme_support()` is used to enable/disable:
+
+1. Root relative URLs
+2. [Rewrites](rewrites.md)
+3. HTML5 Boilerplate's `.htaccess`
+4. Bootstrap's top navbar
+
+If you don't want to use one of the features, either comment out the line or remove it.
+
+#### Define which pages shouldn't have the sidebar
+
+`roots_sidebar()` is used to define which pages shouldn't get the sidebar. By default, the 404 and `page-custom.php` template are full width. If you would like to remove the sidebar from additional pages, add in a proper conditional to the first `if` statement.
+
+If you had a page named Contact, you would update the statement to look like:
+
+    if (is_404() || is_page_template('page-custom.php') || is_page('contact')) {
+
+
+### h5bp-htaccess
+
+This file contains HTML5 Boilerplate's `.htaccess` which is automatically added by `htaccess.php` if enabled in `config.php`. There are a few changes to the H5BP version:
+
+* Added block to access WordPress files that reveal version information (`wp-config.php`, `readme.html`, `license.txt`)
+* Commented out expires headers (we recommend the use of [W3 Total Cache](http://wordpress.org/extend/plugins/w3-total-cache/))
+* Commented out ETag removal (we recommend the use of [W3 Total Cache](http://wordpress.org/extend/plugins/w3-total-cache/))
+* Commented out start rewrite engine (handled by WordPress)
+* Commented out suppress/force www (handled by WordPress)
+* Commented out `Options -MultiViews` (causes a server 500 error on most shared hosts)
+* Commented out custom 404 page (handled by WordPress)
+
+### htaccess.php
+
+This file handles the clean URL rewrites and HTML5 Boilerplate `.htaccess`. [About the rewrites](rewrites.md).
+
+### metaboxes.php
+
+This file is a placeholder for you to put in custom metaboxes. We recommend the use of [Custom Metaboxes and Fields for WordPress](https://github.com/jaredatch/Custom-Metaboxes-and-Fields-for-WordPress).
+
+### post-types.php
+
+This file is a placeholder for you to put in [custom post types](http://codex.wordpress.org/Function_Reference/register_post_type) and [taxonomies](http://codex.wordpress.org/Function_Reference/register_taxonomy).
+
+### scripts.php
+
+This file handles all of the CSS and JavaScript. 
+
+#### Stylesheets
+
+Stylesheets are enqueued in the following order:
+
+1. `/theme/assets/css/bootstrap.css`
+2. `/theme/assets/css/bootstrap-responsive.css`
+3. `/theme/assets/css/app.css`
+4. `/child-theme/style.css` (if a child theme is activated)
+
+`app.css` should be used for your site specific styling. 
+
+If you're using LESS, make sure you compile the files to the proper locations:
+
+1. `css/less/bootstrap.less` -> `css/bootstrap.css`
+2. `css/less/responsive.less` -> `css/bootstrap-responsive.css`
+
+#### JavaScript
+
+JavaScript is loaded in the following order:
+
+1. `/theme/assets/js/vendor/modernizr-2.6.1.min.js` (in `head.php`)
+2. `jquery-1.8.0.min.js` via Google CDN with local fallback (in `head.php`)
+3. `/theme/assets/js/plugins.js`
+4. `/theme/assets/js/main.js`
+
+jQuery is loaded in `head.php` using the same method from HTML5 Boilerplate: grab Google CDN's jQuery, with a protocol relative URL; fall back to local if offline. It's kept in the header instead of footer to avoid conflicts with plugins.
+
+`plugins.js` contains a minified version of all the latest Bootstrap plugins.
+
+Learn about `plugins.js` and `main.js` in the HTML5 Boilerplate [JavaScript docs](https://github.com/h5bp/html5-boilerplate/blob/master/doc/js.md). 
+
+##### jQuery in the footer
+
+It's safe to move jQuery to the footer if you're able to avoid problems with certain plugins that improperly use jQuery. Copy the necessary lines from `head.php` to `footer.php` right before `wp_footer()`, then update the `wp_register_script()` calls `scripts.php` to have scripts in the footer by setting the last argument to `true`.
+
+### template-tags.php
+
+This file contains custom template tags. 
+
+`roots_entry_meta()` is used by the [theme templates](templates.md) to return the author byline and post time and date information.
+
+
+### utils.php
+
+This file contains utility functions used by other files in the theme.
+
+The theme wrapper is used to serve all of the template files. [About the theme wrapper](wrapper.md).
+
+### widgets.php
+
+This file registers the custom sidebars and custom widgets. There are two initial sidebars:
+
+1. Primary Sidebar (used by `templates/sidebar.php`, included from `base.php` within `#sidebar`)
+2. Footer (used by `templates/footer.php`)
+
+The included vCard widget can be used to build additional, custom widgets.

doc/plugins.md

@@ -0,0 +1,29 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Recommended Plugins
+
+| **Plugin Name** | **Plugin Description**
+|:----------------|:----------------------
+| [**Gravity Forms**](http://www.rootstheme.com/gravity-forms/) | With Gravity Forms you can build complex, interactive contact forms in minutes.
+| [**WPML**](http://www.rootstheme.com/wpml/) | WPML makes it easy to build multilingual sites and run them. Roots already includes translations for:<br> English, Spanish, French, Italian, Dutch, Brazilian Portuguese, Macedonian, Finnish, Danish, Turkish, Swedish, Bulgarian, Norwegian, Catalan, Polish, Hungarian, Russian.
+| [**WordPress SEO**](http://yoast.com/wordpress/seo/) | Yoast's all in one SEO solution: titles, meta descriptions, XML sitemaps, breadcrumbs & more.
+| [**WP Super Cache**](http://wordpress.org/extend/plugins/wp-super-cache/) | WP Super Cache is a static caching plugin that generates HTML files.
+| [**W3 Total Cache**](http://wordpress.org/extend/plugins/w3-total-cache/) | Improve site performance and user experience via caching.
+| [Analytics 360](http://wordpress.org/extend/plugins/analytics360/) | Pull Google Analytics and MailChimp data directly into your dashboard. 
+| [Custom Metaboxes & Fields](https://github.com/jaredatch/Custom-Metaboxes-and-Fields-for-WordPress) | Easily create metaboxes with custom fields.
+| [Front-end Editor](http://scribu.net/wordpress/front-end-editor) | A WordPress plugin that enables "edit in place" functionality on your site.
+| [Options Framework](https://github.com/devinsays/options-framework-plugin) | An Options Panel Framework to help speed theme development.
+| [Page Links To](http://wordpress.org/extend/plugins/page-links-to/) | Make a WordPress post link to an external URL of your choosing instead of its WordPress URL.
+| [Post Types Order](http://wordpress.org/extend/plugins/post-types-order/) | Order  posts, pages, and custom post types using a drag and drop interface.
+| [Posts 2 Posts](http://scribu.net/wordpress/posts-to-posts) | Create many-to-many connections between posts of all kinds.
+| [Query Multiple Taxonomies](http://scribu.net/wordpress/query-multiple-taxonomies) | Filter posts through multiple custom taxonomies.
+| [Simple Footnotes](http://wordpress.org/extend/plugins/simple-footnotes/) | Create simple, elegant footnotes on your site. Use the [ref] shortcode and the plugin takes care of the rest.
+| [SLD Custom Content Types](https://github.com/jkudish/sld-custom-content-and-taxonomies) | Register new custom post types easily, with good default values and some extended functionality.
+| [WordPress Domain Changer](https://github.com/veloper/WordPress-Domain-Changer) | A self-contained script that helps ease the migration of WordPress sites from one domain to another.
+| [WPAlchemy MetaBox Class](http://www.farinspace.com/wpalchemy-metabox/) | Create custom WordPress meta boxes quickly.
+| [WP-DB-Backup](http://wordpress.org/extend/plugins/wp-db-backup/) | WP-DB-Backup allows you easily to backup your WordPress database tables.
+| [WP-PageNavi](http://wordpress.org/extend/plugins/wp-pagenavi/) | Adds a more advanced paging navigation interface.
+| [WP Database Optimizer](http://www.matthewaprice.com/wp-database-optimizer/) | Automated scheduled database optimization.
+| [WP Mail SMTP](http://wordpress.org/extend/plugins/wp-mail-smtp/) | Reconfigures the wp_mail() function to use SMTP instead of mail().
+| [Taxonomy Images](http://wordpress.org/extend/plugins/taxonomy-images/) | Associate images from your media library to categories, tags and custom taxonomies.

doc/rewrites.md

@@ -0,0 +1,38 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Rewrites
+
+Rewrites are handled by `lib/htaccess.php`. Rewrites currently do not happen for child themes or network installs.
+
+Rewrite:
+
+1. `/wp-content/themes/themename/assets/css/` to `/assets/css/`
+2. `/wp-content/themes/themename/assets/js/` to `/assets/js/`
+3. `/wp-content/themes/themename/assets/img/` to `/assets/img/`
+4. `/wp-content/plugins/` -> `/plugins/`
+
+If HTML5 Boilerplate's `.htaccess` support is enabled in `lib/config.php`, then the `generate_rewrite_rules()` filter is used to automatically add the contents of `lib/h5bp-htaccess` to your `.htaccess` file.
+
+## Alternative configuration
+
+First remove the `if` statement that wraps everything, since if you're not on Apache or Litespeed then Roots will not apply the functionality.
+
+### Nginx
+
+    if (!-e $request_filename) {
+      rewrite ^/assets/css/(.*)$ /wp-content/themes/roots/assets/css/$1 last;
+      rewrite ^/assets/js/(.*)$ /wp-content/themes/roots/assets/js/$1 last;
+      rewrite ^/assets/img/(.*)$ /wp-content/themes/roots/assets/img/$1 last;
+      rewrite ^/plugins/(.*)$ /wp-content/plugins/$1 last;
+      break;
+    }
+   
+### Lighttpd
+
+    url.rewrite-once = (
+      "^/css/(.*)$" => "/wp-content/themes/roots/css/$1",
+      "^/js/(.*)$" => "/wp-content/themes/roots/js/$1",
+      "^/img/(.*)$" => "/wp-content/themes/roots/img/$1",
+      "^/plugins/(.*)$" => "/wp-content/plugins/$1"
+    )

doc/templates.md

@@ -0,0 +1,48 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Theme templates
+
+### comments.php
+
+The comments template wraps each comment in an `<article>` and the vCard microformat is used for comment author information. 
+
+### content.php
+
+The `content.php` template is included by archive templates in the theme root.
+
+### content-page.php
+
+The `content-page.php` template is included by page templates in the theme root.
+
+### content-single.php
+
+The `content-single.php` template is included by single post templates in the theme root.
+
+### footer.php
+
+`footer.php` includes the Footer sidebar area and displays the site copyright information.
+
+### head.php
+
+`head.php` includes everything in the `<head>`.
+
+### header.php
+
+`header.php` is used if the Bootstrap navbar isn't enabled in `lib/config.php`. The `wp_nav_menu()` outputs with a `nav-pills` class for some basic styling from Bootstrap.
+
+### header-top-navbar.php
+
+`header-top-navbar.php` is used if the Bootstrap navbar is enabled in `lib/config.php`.
+
+### page-header.php
+
+`page-header.php` is included at the top of files in the theme root to display the `<h1>` on pages before the page content.
+
+### searchform.php
+
+`searchform.php` is the template used when `get_search_form()` is called.
+
+### sidebar.php
+
+`sidebar.php` includes the Primary Sidebar.

doc/usage.md

@@ -0,0 +1,140 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Usage
+
+The HTML, CSS and JavaScript in Roots comes from a combination of HTML5 Boilerplate and Twitter Bootstrap.
+
+* [HTML5 Boilerplate documentation](https://github.com/h5bp/html5-boilerplate/blob/master/doc/README.md)
+* [Twitter Bootstrap documentation](http://twitter.github.com/bootstrap/getting-started.html)
+
+## Basic structure
+
+A basic Roots theme initially looks like this:
+
+```
+.
+├── assets
+│   ├── css
+│   │   ├── less
+│   │   │   │── bootstrap.less
+│   │   │   └── responsive.less
+│   │   │── app.css
+│   │   │── bootstrap.css
+│   │   │── bootstrap-responsive.css
+│   │   │── editor-style.css
+│   ├── img
+│   └── js
+│       ├── main.js
+│       ├── plugins.js (includes bootstrap.js)
+│       └── vendor
+│           ├── jquery-1.8.0.min.js
+│           └── modernizr-2.6.1.min.js
+├── doc
+├── lang
+│   └── roots.pot
+├── lib
+│   ├── actions.php
+│   ├── activation.php
+│   ├── cleanup.php
+│   ├── config.php
+│   ├── custom.php
+│   ├── h5bp-htaccess
+│   ├── htaccess.php
+│   ├── metaboxes.php
+│   ├── post-types.php
+│   ├── scripts.php
+│   ├── template-tags.php
+│   ├── utils.php
+│   └── widgets.php
+├── templates
+│   ├── comments.php
+│   ├── content.php
+│   ├── content-page.php
+│   ├── content-single.php
+│   ├── footer.php
+│   ├── head.php
+│   ├── header.php
+│   ├── header-top-navbar.php
+│   ├── page-header.php
+│   ├── searchform.php
+│   └── sidebar.php
+├── 404.php
+├── base.php
+├── functions.php
+├── index.php
+├── page.php
+├── page-custom.php
+├── screenshot.png
+├── single.php
+└── style.css
+```
+
+What follows is a general overview of each major part and how to use them.
+
+### assets/css/
+
+This directory should contain all your project's CSS files. If you're using LESS, you should have `less/bootstrap.less` compile to `css/bootstrap.css`, and `less/responsive.less` compile to `css/bootstrap-responsive.css`. Any additional LESS files that aren't from Bootstrap should compile to `css/app.css`.
+
+### assets/img/
+
+This directory should contain all your project's image files.
+
+### assets/js/
+
+This directory should contain all your project's JS files. Libraries, plugins,
+and custom code can all be included here. It includes some initial JS to help
+get you started.
+
+The files and directory structure are adopted from [HTML5 Boilerplate's JavaScript](https://github.com/h5bp/html5-boilerplate/blob/master/doc/js.md).
+
+### doc/
+
+This directory contains all the Roots documentation. You can use it
+as the location and basis for your own project's documentation.
+
+### lang/
+
+This directory contains all of the theme translations. [About translating the theme](http://www.icanlocalize.com/site/tutorials/how-to-translate-with-gettext-po-and-pot-files/).
+
+### lib/
+
+This directory contains all of the theme functionality. [About the theme library](lib.md).
+
+### templates/
+
+This directory contains all of the theme templates. [About the templates](templates.md).
+
+
+### 404.php
+
+A helpful custom 404 to get you started.
+
+### base.php
+
+This is the default HTML skeleton that forms the basis of all pages on
+your site. [About the theme wrapper](wrapper.md).
+
+### functions.php
+
+This file loads all of the [theme library](lib.md) files, sets up the default navigation menus, and adds support for post thumbnails.
+
+### index.php
+
+This file is used to serve all of the archive templates.
+
+### page.php
+
+This file is used to serve the page template.
+
+### page-custom.php
+
+An example of a custom page template. By default, this page is full width and doesn't contain a sidebar as defined in `lib/config.php`'s `roots_sidebar()` function.
+
+### single.php
+
+This file is used to serve the single post template.
+
+### style.css
+
+This file is used to tell WordPress that we're a theme. None of the actual CSS is contained in this file.

doc/wrapper.md

@@ -0,0 +1,14 @@
+[Roots Theme homepage](http://www.rootstheme.com/) | [Documentation
+table of contents](README.md)
+
+# Theme wrapper
+
+The theme wrapper functionality is found in `lib/utils.php`. This code comes directly from [scribu's theme wrapper](http://scribu.net/wordpress/theme-wrappers.html) post.
+
+`base.php` is used to serve all of the templates for your site. In the theme root, the following files are only used to include files in the `templates/` directory, which contains all of the [theme templates](templates.md):
+
+1. `index.php` (archive page templates) includes `templates/content.php`
+2. `page.php` includes `templates/content-page.php`
+3. `single.php` includes `templates/content-single.php`
+
+The [Template Hierarchy](http://codex.wordpress.org/Template_Hierarchy) is traversed as normal before the wrapper is loaded.