Build Status


Awestruct 0.5.0 Released

We’re thrilled to announce the release of Awestruct 0.5.0!

Awestruct 0.5.0 marks a significant evolution in the history of the project. The focus of this release has been on ease of installation, compatibility and flexibility.

The major highlights of this release are:

  • Integration of Tilt to handle rendering

  • Dependencies cut in half (from 22 down to 11)

  • Improved compatibility with JRuby

  • Tight AsciiDoc integration powered by Asciidoctor

  • An Amazon S3 deployer

  • Switched to Ruby’s Logger class to output messages

This release is an important step towards achieving Awestruct’s primary goal: to make static websites trivially easy to create 'and publish'. We hope when you try it, you’ll agree.



Setup and migration

Awestruct is bundled as a Ruby gem and published to You can install it using:

$ gem install awestruct

If this is your first time using Awestruct, you can create a new website based on Bootstrap by running the following command inside a new directory:

$ awestruct -i -f bootstrap

New in 0.5.0, the setup command adds a rake build file, Rakefile, to the project.

The Rakefile didn’t get bundled in the 0.5.0 gem. Therefore, this feature won’t be available until 0.5.1 is released. Until then, you can retrieve the Rakefile from the git repository.

Using rake is optional, but it does make running Awestruct a little bit easier and helps gets your contributors setup quicker.

If you’re already using Awestruct to bake your website, we strongly recommend that you follow the migration guide to upgrade to this new version.

What’s new?

With this release, the version of Awestruct jumped from 0.4.8 to 0.5.0. The changes described below should help explain why we decided to skip a version.

Tilt integration

The most significant change in 0.5.0 is the integration of Tilt, a generic interface to numerous template engines in Ruby. Tilt is used to render any file written in a template language supported by Tilt.

Here are some of the benefits of using Tilt:

  • As soon Tilt adds support for another template language, it’s available for use with Awestruct

  • Tilt lets you to select between different engines for a given markup language (such as Markdown)

  • You can configure all the template engines from one place, _config/site.yml

Less dependencies

Not only did the switch to Tilt simplify the rendering code in Awestruct, it also cut down the number of Awestruct’s required dependencies. Tilt loads the libraries necessary to render a template language when they are needed. For instance, if you don’t have any Textile files in your project, you don’t need RedCloth—​the Textile implementation in Ruby—​installed.

Some of Awestruct’s built-in extensions were requiring users to install extra libraries. These extensions are now disabled if the library is not available. As a result of this change, you may notice warnings when you start Awestruct such as:

WARNING: Missing required dependency to activate optional built in extension
coffeescripttransform.rb -> cannot load such file -- coffee-script

However, the warning message is a better alternative than making you install libraries you don’t need :)

In all, the number of dependencies has been trimmed from 22 down to 11.

The trade-off of trimming Awestruct’s dependencies is that you need to explicitly install libraries for each of the template languages or built-in Awestruct extensions you want to use (and add them to your Gemfile, if you’re using Bundler).

See the migration guide for a list of libraries you’ll need to install.

'…​in case you were wondering, you no longer have to install less, therubyracer or v8 to use Awestruct ;)'

Ruby compatibility

Each change to Awestruct is now tested on the latest release of all major versions of Ruby (1.8.7, 1.9.3, 2.0.0 and JRuby 1.7.3). Awestruct is also battle tested across multiple platforms (Linux, Mac OSX and Windows).

We’re happy to say Awestruct has finally reached stability when running across all platforms. If issues still remain, we’re eager to hear about them and get them resolved.

AsciiDoc integration

With AsciiDoc, we’re exploring a deeper integration between Awestruct and the content pages, specifically a bidirectional exchange of data.

Instead of adding the typical Awestruct front matter to the top of the document, you can define the front matter using attributes in the AsciiDoc header. Awestruct will also map the AsciiDoc title, author and date to the matching front matter attributes. You can also refer to Awestruct page variables using AsciiDoc attribute references.

The source of this blog entry serves as an example of this integration:

= Awestruct 0.5.0 released
Dan Allen
:awestruct-layout: news

We're thrilled to announce the release of Awestruct 0.5.0!

In other words, an AsciiDoc document can be used in an Awestruct site without any modifications (except for the addition of the :awestruct-layout: attribute).

Amazon S3 deployer

In addition to the rsync and GitHub Pages deployers, Awestruct can now deploy a site to Amazon S3. For instructions on how to set it up, see the site deployment page on the Awestruct website.


Awestruct now adds a Rake build file, Rakefile, to new sites by default.

The Rakefile didn’t get bundled in the 0.5.0 gem. Therefore, this feature won’t be available until 0.5.1 is released. Until then, you can retrieve the Rakefile from the git repository.

The purpose of this build file is to simplify setting up and using Awestruct across the numerous Ruby platforms. It’s not required to use Awestruct, though it does save you time (hopefully).

Now, instead of typing:

$ awestruct -d

you just type:

$ rake

While that may only save a few characters, know that it also auto-detects a Bundler environment and does the right thing. That means if you’re using Bundler, instead of typing:

$ bundle exec awestruct -d

you just type:

$ rake

See, isn’t that nicer?

It also tells you what commands to type to setup an Awestruct environment (as contributors might need to do).

For more details, read the comments at the top of the Rakefile.

If you don’t want to use rake, just ignore or delete the file.

Bootstrap upgrade

Many of you who use Awestruct are probably taking advantage of the Bootstrap integration provided by bootstrap-sass. If you have, note that Awestruct has upgraded to Bootstrap 2.3.1, the latest version of Bootstrap that bootstrap-sass supports at the time of this release. Since Awestruct has a transitive dependency on this library, it will be upgraded when you upgrade Awestruct.

If you want to keep using an older version of Bootstrap, just declare the version explicitly in your Gemfile.

That about wraps it up. For more details about what’s in this release, see the migration guide or just try it for yourself.


Many people rallied together to make this release easier to install, more compatible and more flexible. Without their help, Awestruct wouldn’t be where it is today. Give a shout out on Twitter to the following contributors to let them know how much they mean to this growing community:

Jason Porter - Aslak Knutsen - Dan Allen - Cody Lerum - Lance Ball - Geoffrey De Smet - Xavier Coulon - Jeff Mesnil - Brian Leathem - Torsten Curdt - Sarah White

Also, thanks to everyone who has contributed to Awestruct and those of you who use it, help others to use it and/or evangelize the technology. We’re honored to have you as part of the community!

Now go create awesome sites!

Awestruct 0.2.7 On the Prowl

Uh, we skipped a few release announcements, but it's because...

Development on Awestruct is picking up now that the Arquillian team has started hacking on it for their new project site. They've contributed some improvements to Awestruct and have some other extensions waiting in the wings for a future release. There's also been a lot of chatter about Awestruct recently on twitter.

Here's a taste of the treats in store for you.

Aslak improved the Posts extension to read as a alternative to the post filename, part of the preparation for a feature that enables automatic generation of blog entries for project releases (like this one!).

Aslak also integrated FSSM to monitor files more efficiently in development mode. Your CPU will thank you! He also committed a fix for a divide by 0 bug in the tagger extension that would strike when you least expected it. Additionally, he added support for extensions to define their own transformers.

At Dan's request, Awestruct has been upgraded to Compass 0.11.5 to take advantage of all the latest CSS3 mixins and so the online Compass documentation is actually relevant for developers using Awestruct. If you've been using a lot of the CSS3 mixins already, you may need to do a little migration. Compass spits out deprecation warnings to the console. Holler if the upgrade breaks your stylesheet and you aren't sure how to fix it.

Dan and Aslak figured out how to hack RedCloth to provide custom inline and block markup. The hooks are now in place. We'll be documenting how to make use of them soon. You can see an example here.

Dan documented the Disqus extension, an extension which snuck into a previous release without much ado. He also added an option to have the extension generate the Disqus identifier automatically from the date and slug of the post. Disqus is an alternative JavaScript-based comment system for Awestruct Posts which offers a very elegant interface for both users and administrators.

Finally, Tom's gsub transformer finally got merged in, so you can slice and dice the pages as they exit the pipeline.

Anyhow, check out gem.

gem install awestruct

If I missed something, feel free to mention it in the comments.

Photo Credit: ralph and jenny

Awestruct 0.2.2 Lives

Thanks to recent interest from Torsten Curdt, Emmanuel Bernard and others in the community, activity around Awestruct has increased as of late.

Emmanuel gives us the Flattr extension, plus a really nice blog post.

Torsten gives us RDiscount for Markdown instead of Bluecloth. Holler if it breaks your stuff.

Anyhow, check out v0.2.2.

gem install awestruct