1. Overview

Forge was designed to make developing WordPress themes just a little bit easier. It supports tools such as Sass, LESS, CoffeeScript and Sprockets, and helps you organize your theme the way you want to - instead of the flat structure required by WordPress.

1.1 Quick Start

  1. Install Forge (requires Ruby and RubyGems):
    $ gem install forge
  2. Create your new theme project:
    $ forge create your_theme
  3. Change to your project directory:
    $ cd your_theme
  4. Link to your WordPress theme folder:
    $ forge link /wordpress/wp-content/themes/your_theme
  5. Watch for changes and start developing!
    $ forge watch

2. Forge Commands

Forge comes with a handful of commands that help make theme development easy.

2.1 forge create

forge create your_theme

Creates the your_theme directory if it doesn't exist, and sets up a new Forge project in that directory.

A new Forge project contains directories for your assets, templates, functions and includes. Forge also generates a few standard WordPress templates and adds some example Sass / CSS.

See how Forge works for a detailed explanation of how a Forge project is structured.

forge link /wordpress/wp-content/themes/your_theme

Must be run from within a Forge project.

Creates a symbolic link from /path/to/wordpress_install/wp-content/themes/your_theme to the hidden Forge build directory (.forge/build). After running forge link, any changes you make while running forge watch will be reflected in your WordPress installation.

forge link is just a convenient way to run ln -s .forge/build /path/to/wordpress_install/wp-content/themes/your_theme

You'll need to run forge link once for every WordPress install you want to test your theme with.

2.3 forge watch

forge watch

Must be run from within a Forge project.

Watches the source directory in your project for changes and compiles those changes in the Forge build directory (.forge/build), which should be linked to your WordPress installation after running forge link.

forge watch is where the magic happens - you need to leave forge watch running while working on your project.

For a more detailed explanation of what happens during forge watch, check out how Forge works.

2.4 forge build

forge build

Must be run from within a Forge project.

Compiles the theme from the source directory into the build directory. If you want to build somewhere other than build, you can specify the directory by running forge build my_build_directory.

forge build is useful if you want to review Forge's output before releasing your theme.

2.5 forge package

forge package

Must be run from within a Forge project.

Compiles the theme and zips it to package/your_theme.zip. To name the zip file, run forge package your_name and the theme will be compiled to package/your_name.zip.

3. How Forge works

Running forge create generates a skeleton project for developing your theme. All of your development work takes place in the source directory of that project.

When you run forge watch, forge build, or forge package the underlying process is the same - Forge compiles the source directory into a working theme. As we explain how Forge works, we’ll be referring to the final_theme directory, which represents the "compiled" theme.

The source directory is made up of 4 sections: Assets, Templates, Functions, and Includes.

3.1 Assets

Assets are your JavaScript, CSS, and image files. You may use CoffeeScript, Sass, LESS, and Sprockets. If you want to stick with plain CSS and JavaScript, you can do that as well.

Assets fall into 3 categories: Stylesheets, JavaScript, and Images.

3.1.1 Stylesheets

Stylesheets in Forge use Sass or LESS, languages that make stylesheet development quicker and easier. By default, Forge generates source/assets/stylesheets/style.css.scss.

Forge supports both the Sass (.sass) and SCSS (.scss) syntax - just change the extension to style.css.sass if you prefer Sass syntax.

Or, if you prefer LESS to Sass, just name your stylesheet file style.css.less, and the LESS processor will take over.

In addition, Forge supports Compass and Blueprint mixins for Sass.

By default, the only stylesheet included with your theme is the main stylesheet (style.css), which is located at source/assets/stylesheets/style.css.scss.

Sass supports importing of partial stylesheets. Forge allows as many partials you want for breaking up your CSS into an organized structure. For example, assume the following files exist:

source/assets/stylesheets/_pages.scss
source/assets/stylesheets/_reset.scss
source/assets/stylesheets/style.css.scss

Simply edit your source/assets/stylesheets/style.css.scss file to include these partials:

@import "reset";
@import "pages";

body { color: #333; }
…

style.css.scss will be processed and the result output to final_theme/style.css.

3.1.2 JavaScript

JavaScript in Forge harnesses the power of CoffeeScript and Sprockets. The master JavaScript file for your project is source/assets/javascripts/theme.js. In theme.js, you can include any other JavaScript or CoffeeScript files you'll need in your final theme. For example, with these files:

source/assets/javascripts/slider.js
source/assets/javascripts/tags.coffee
source/assets/javascripts/theme.js

Including other files is as easy as

(in source/assets/javascripts/theme.js)
//= require 'slider'
//= require 'tags'

$('#more .javascript .here').show();
...

theme.js will be processed and output to your_theme/javascripts/theme.js

Forge also processes an admin JavaScript file, for scripts to be used only in the WordPress admin.

source/assets/javascripts/admin.js

This is processed the same way as theme.js, but is output to

your_theme/javascripts/admin.js

Read more about CoffeeScript and Sprockets.

3.1.3 Images

Images in Forge are are kept in source/assets/images/

Everything in the images folder will be copied unchanged to final_theme/images/

The only exception to this rule is your screenshot file - named screenshot.png, screenshot.jpg, screenshot.jpeg, or screenshot.gif. This file will be copied directly to the root of your theme.

To clarify with an example - the following images folder setup:

source/assets/images/photo.jpg
source/assets/images/screenshot.png
source/assets/images/animals/wild/lion.jpg
source/assets/images/food/hamburger.png

would translate to the following:

final_theme/images/photo.jpg
final_theme/images/animals/wild/lion.jpg
final_theme/images/food/hamburger.png
// screenshot goes in the root
final_theme/screenshot.png

3.2 Templates

The templates directory is simply a way to organize your template files. In a normal theme, all templates would go in the root directory. With Forge, you can organize your templates however you prefer, and they’ll be moved to the root when the theme is built.

For example, the following set up:

source/templates/index.php
source/templates/pages/my_template.php
source/templates/this/is/getting/really_deep.php

will translate to this in your theme:

final_theme/index.php
final_theme/my_template.php
final_theme/really_deep.php

Forge gives you some default folders that we think make sense, but there’s no specific structure required.

3.3 Functions and Includes

Forge simply copies source/functions/functions.php as-is into final_theme/functions.php.

If you have any libraries you want to include with your project, you can put them into source/includes/ and they will be copied over directly into final_theme/includes/.

To clarify with an example:

source/includes/struts/options.php
source/includes/theme_library.php
source/includes/javascripts/external.js

becomes

final_theme/includes/struts/options.php
final_theme/includes/theme_library.php
final_theme/includes/javascripts/external.js

4. Configuring Forge

Forge requires config.rb to be present at the root of your theme. config.rb can be used to change Compass configuration as well as enable LiveReload.

Forge also looks for a config file located in at ~/.forge/config.rb. Any global configuration you want to apply to all Forge projects can go here. The config.rb of individual projects will take priority over your global settings.

Below is a list of the configuration options.

live_reload
Set to true to use LiveReload with Forge (optional)
config[:live_reload] = true
Help improve this user's manual by forking the Forge repository on Github, making changes to the gh-pages branch, and sending a pull request.