Creating a hassle free Ruby environment

We’ve noticed, and had quite a lot of feedback about it being difficult to get up and running easily with Awestruct. The first thing that makes this difficult is the Ruby environment you’ll be developing your site. We strongly recommend you install and use rvm, and install the latest Ruby 1.9.3 environment. We have found Ruby 1.9.3 to be the best environment at the moment to use with Awestruct.

Installing rvm on Linux and Mac OSX

To correctly install rvm open a terminal and execute:

$ curl -L | bash -s stable --ruby=2.3.0

This will download and install the latest stable version of Ruby version 2.3.0 in a directory in your HOME directory, eliminating the need to have root access to update or install new gems.

Installing Ruby on Windows

Creating a great working environment on Windows can be difficult. We recommend using the RubyInstaller for Windows. Download the latest version of Ruby 2.3.0 and follow any instructions it gives you.

Install Awestruct and start a new project

Install Package Dependencies on RPM Distributions

When you install Awestruct using gem, Ruby builds the components that comprise the Awestruct framework at install time. To achieve this, the gem framework expects certain development libraries to be present so it can leverage them at build time.

Run the following command to install the main group of development tools Ruby requires to compile most Rubygems.

$ sudo yum groupinstall -y development-tools

Additionally, run the following command to install all dependencies required by Awestruct.

$ sudo yum install -y rake ruby-devel libxslt-devel gcc-c++

After you have installed all dependencies, you are ready to proceed with installing Awestruct.

Install Awestruct

Now you have a pristine Ruby environment and have installed all required dependencies, you’re ready to install Awestruct and Bundler:

$ gem install awestruct bundler

This will retrieve the latest version of both Awestruct and Bundler to use on your system. We’ll get to the need for Bundler soon. As soon as the install completes you’ll be placed back at the prompt, ready to use Awestruct!

Create a new empty directory, and run awestruct with the --init parameter. Optionally pick a supported framework with the --framework option.

$ mkdir myproj
$ cd myproj
$ awestruct --init --framework foundation
--framework also accepts bootstrap, and foundation depending on your favorite CSS framework.

This will create a number of folders and files which will be the starting of your Awestruct baked site. More information about this files and directories can be found in the Project layout section.

Setting up your dependencies

Starting with version 0.5.0 the number of dependencies for Awestruct was drastically reduced by removing hard dependencies on the different markup formats. The trade-off in doing this is that you need to pull in the diffent dependencies you are using in your site. The easiest way to do this is using Bundler. We installed this the same time we installed awestruct above. If you do not already have a file called Gemfile in your project’s directory, go ahead and create one using the following base content:

source ''                             # This tells Bundler where to look for gems

gem 'awestruct', '~> 0.5.7'                               # Goes without saying
gem 'rake', '>= 0.9.2'                                    # Needed for the Rakefile to work
# gem 'coffee-script', '~> 2.2.0'                         # If using coffee-script or to remove the warning
# gem 'therubyracer', '0.10.0', :platforms => :ruby       # Javascript runtime on mri (needed for LESS and coffee-script)
# gem 'therubyrhino', '~> 2.0.2', :platforms => :jruby    # Javascript runtime on jruby (needed for LESS and coffee-script)
# gem 'less', '>= 2.2.2'                                  # If using LESS instead of sass
# gem 'org-ruby', '>= 0.8'                                # If using Org-Mode
# gem 'RedCloth', '>= 4.2.9'                              # If using Textile
# gem 'asciidoctor', '>= 0.1.1'                           # If using AsciiDoc syntax, need 0.1.1 for Header support
# gem 'slim', '>= 1.3.6'                                  # If using slim instead of haml
# gem 'kramdown', '>= 0.14.2'                             # If using Markdown
# gem 'uglifier', '>= 1.3.0'                              # If using the minify transformer
# gem 'htmlcompressor', '>= 0.0.3'                        # If using the minify transformer

You can uncomment the dependencies you need for your site, or add others as needed.


You MUST add require 'gem name' at the top of your _ext/pipeline.rb for any CSS or JS gems you use. It is strongly recommended you add markup gems as well, but it is not required. For example, if you’re using Foundation the beginning of your _ext/pipeline.rb should look like:

require 'zurb-foundation'

Using rake

The final step in using Awestruct is to familiarize yourself with the Rake tasks. There are a number of Rake tasks in the Rakefile that correspond to common awestruct tasks. To get started using Rake, which will make things much easier, execute:

rake setup

This will install all the gems defined in your Gemfile and you’ll be ready to start building sites!


If you get the error "libxml2 is missing", then try jruby instead:

rvm install jruby
rvm use jruby

Edit, save, reload, repeat

$ rake

This will execute awestruct in development mode, which generates the files, regenerates pages on changes, and starts a server to preview the site in your browser at http://localhost:4242. This is a shortcut for rake preview. If you need to clear out the generated site from a previous run, simply run

$ rake clean preview

Deploying your site

Information about setting up your site for deployment can be found at the deployment documentation page. As soon as you have your site setup and ready to deploy you can easily run a deploy via rake:

$ rake deploy

This uses the production profile to find all the deployment configurations.

Awestruct Concepts

The goal of Awestruct is to make it trivially easy to create non-trivial static websites. The core concept of Awestruct is that of structures, specifically Ruby OpenStruct structures. The struct allows arbitrary, schema-less data to be associated with a specific page or the entire site.

Site data is loaded from YAML files in the config directory. Page-specific data can be provided on pages using a _front-matter prolog.

As your files are processed, the site variable provides access to any non-page data loaded from YAML files. The page variable contains any page-specific data loaded from the front-matter or other sources.


Additionally, Awestruct allows for recursive layouts, to allow building variation into sites in a consistent manner.