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.
To correctly install rvm open a terminal and execute:
$ curl -L https://get.rvm.io | bash -s stable --ruby=1.9.3
This will download and install the latest stable version of Ruby version 1.9.3 in a directory in your HOME directory, eliminating the need to have root access to update or install new gems.
Now you have a pristine Ruby environment 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
$ mkdir myproj $ cd myproj $ awestruct --init --framework foundation
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.
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:
You can uncomment the dependencies you need for your site, or add others as needed.
You MUST add
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:
This will install all the gems defined in your Gemfile and you’ll be ready to start building sites!
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
If you need to clear out the generated site from a previous run, simply run
$ rake clean preview
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.
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
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
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.
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.