framework/bedrock
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add new theme documentation

Browse Source
This commit is contained in:
Ben Word
2012-09-03 11:01:29 -05:00
parent f538aa0116
commit 7fdb2f07f5
14 changed files with 659 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@@ -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

10
README.md
View File

@@ -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)

21
doc/README.md Executable file
View File

@@ -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.

28
doc/activation.md Normal file
View File

@@ -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.

88
doc/cleanup.md Normal file
View File

@@ -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 `+`.

93
doc/contribute.md Executable file
View File

@@ -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** &mdash; 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** &mdash; the latest `master` or
development branch may already contain a fix.
3. **Isolate the problem to Roots** &mdash; 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.

8
doc/extend.md Executable file
View File

@@ -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)

16
doc/faq.md Executable file
View File

@@ -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).

129
doc/lib.md Normal file
View File

@@ -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.

29
doc/plugins.md Normal file
View File

@@ -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.

38
doc/rewrites.md Normal file
View File

@@ -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"
)

48
doc/templates.md Normal file
View File

@@ -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.

140
doc/usage.md Executable file
View File

@@ -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.

14
doc/wrapper.md Normal file
View File

@@ -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.