Contribution Guide

Front end tasks are automated by Grunt to allow front end developers to quickly create custom themes and contribute to the core. In the spirit of open source software development, MODX always encourages community code contribution. To help you get started and before you jump into writing code, be sure to read these important contribution guidelines thoroughly.

What you need

In order to build front end assets, you need to have Ruby, Node.js/npm latest and git 1.7 or later. (Earlier versions might work OK, but are not tested.)

For Windows you have to download and install git and Node.js.

Mac OS users should install Homebrew. Once Homebrew is installed, run brew install git to install git, and brew install node to install Node.js.

Linux/BSD users should use their appropriate package managers to install git and Node.js, or build from source if you swing that way. Easy-peasy.

Installing Ruby and Ruby Gems

You'll need ruby and sass gems installed. If you're on OS X or Linux you probably already have Ruby installed; test with ruby -v in your terminal. When you've confirmed you have Ruby installed, run gem install sass to install Sass.

gem install sass

Make sure you have sass installed by testing:

sass --version

Note: Depending on your ruby setup you may need to install gems using sudo gem install sass.

Installing Grunt & Grunt Packages

First, clone a copy of this git repo by running:

git clone -b master git://github.com/jpdevries/doctext.git

Install the grunt-cli package if you haven't before. This should be done as global install:

npm install -g grunt-cli

Make sure you have gruntinstalled by testing:

grunt --version

Enter the default template directory and install the Node dependencies, this time without specifying a global(-g) install:

cd doctext/_build/templates/default
npm install

Note: npm install updates dependencies and should be run whenever you pull from git.

Optionally enable Growl notifications install terminal-notifier with RubyGems:

gem install terminal-notifier

Note: Depending on your ruby setup you may need to install gems using sudo gem install terminal-notifier.

Grunt Commands

Build
Fetch dependencies (such as bourbon), move items into place and compile by running:

grunt build

Watch
Compile the Sass and watch files for changes type the following:

grunt

Note: grunt is now watching files for changes. When Sass files are changed CSS will automatically be generated.
Install the LiveReload browser extension to inject CSS changes without a page refresh.

Expand
Compile Sass using expanded output style for development by running:

grunt expand

Note: do not check in uncompressed CSS.