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.
$ gem install forge$ forge create your_theme$ cd your_theme$ forge link /wordpress/wp-content/themes/your_theme$ forge watchForge comes with a handful of commands that help make theme development easy.
forge create your_themeCreates 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_themeMust 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.
forge watchMust 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.
forge buildMust 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.
forge packageMust 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.
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.
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.
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.scssSimply 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.
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.jsIncluding 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.jsThis is processed the same way as theme.js, but is output to
your_theme/javascripts/admin.jsRead more about CoffeeScript and Sprockets.
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.pngwould 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.pngThe 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.phpwill translate to this in your theme:
final_theme/index.php
final_theme/my_template.php
final_theme/really_deep.phpForge gives you some default folders that we think make sense, but there’s no specific structure required.
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.jsbecomes
final_theme/includes/struts/options.php
final_theme/includes/theme_library.php
final_theme/includes/javascripts/external.jsForge 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.
config[:live_reload] = true