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 to install the Ruby environment. You can use Ruby 2.6 or later with Awestruct.
To correctly install rvm open a terminal and execute:
$ curl -L https://get.rvm.io | bash -s stable --ruby=3.2.0
This will download and install the latest specified version of Ruby in a directory in your HOME directory, eliminating the need to have root access to update or install new gems.
Creating a great working environment on Windows can be difficult. We recommend using the RubyInstaller for Windows. Download the latest version of Ruby 3.2.0 and follow any instructions it gives you.
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.
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
|
Note
|
--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.
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 'https://rubygems.org' # 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.
|
Important
|
You MUST add _ext/pipeline.rb
require 'zurb-foundation' |
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!
|
Note
|
If you get the error "libxml2 is missing", then try jruby instead: rvm install jruby rvm use jruby |
$ 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
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 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.