The Docs Guy: April 2016

Installing Awestruct on Linux Mint 17.x

References

Introduction

The instructions from the Awestruct website assume quite a bit of existing knowledge. As a result, many of steps lack all the necessary information to complete the task. The notes below may help to fill in some of the blanks and should help you get things going.

Prerequisites

Install GIT & Curl

If you haven’t already done so, install GIT so you can version control your project. Curl will be used to install RVM (assuming you select method # 2 below).

sudo apt-get install git curl

Install a Ruby build environment

To use Awestruct, you essentially need to install a complete Ruby build environment. The latest version of Awestruct requires Ruby version 2.0 (or greater), and to build these things, you also require ruby2.0-dev (or greater).

Installing a Ruby development environment

There are 2 ways to approach this task:

Method # 1 - System Level

Using this method, you will be installing or upgrading your Ruby environment at the system level, which will affect all users of the machine.
- This method also requires the use of sudo for installing gems, etc.

You can search the apt cache to see what versions are available by doing an apt-cache search ruby2 You can check your existing version of Ruby using ruby -v and listing installed gems with gem2.0 list.

The following commands should get things installed OK.

sudo apt-get install ruby2.0 ruby2.0-dev

Next install Awestruct:

sudo gem2.0 install awestruct

Method # 2 - User Level - (preferred method)

Use RVM (Ruby Version Manager)

This is probably the best way to manage a Ruby build environment as it installs everything right into your own home directory. Not only that, but you are then able to install gems without having to elevate permissions using sudo.

To get this to work correctly, I had to do a number of things.

Install the RVM key

gpg2 --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3

Install RVM

curl -L https://get.rvm.io | bash -s stable --ruby=2.3.0

Here is what things looked like when I installed RVM on Linux Mint 17.3.

$~> curl -L https://get.rvm.io | bash -s stable --ruby=2.3.0
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   184  100   184    0     0    724      0 --:--:-- --:--:-- --:--:--   724
100 22865  100 22865    0     0  51150      0 --:--:-- --:--:-- --:--:-- 51150
Downloading https://github.com/rvm/rvm/archive/1.27.0.tar.gz
Downloading https://github.com/rvm/rvm/releases/download/1.27.0/1.27.0.tar.gz.asc
gpg: Signature made Tue 29 Mar 2016 09:49:47 AM EDT using RSA key ID BF04FF17
gpg: Good signature from "Michal Papis (RVM signing) <mpapis@gmail.com>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 409B 6B17 96C2 7546 2A17  0311 3804 BB82 D39D C0E3
     Subkey fingerprint: 62C9 E5F4 DA30 0D94 AC36  166B E206 C29F BF04 FF17
GPG verified '/home/mike/.rvm/archives/rvm-1.27.0.tgz'

Installing RVM to /home/mike/.rvm/
    Adding rvm PATH line to /home/mike/.profile /home/mike/.mkshrc /home/mike/.bashrc /home/mike/.zshrc.
    Adding rvm loading line to /home/mike/.profile /home/mike/.bash_profile /home/mike/.zlogin.
Installation of RVM in /home/mike/.rvm/ is almost complete:

  * To start using RVM you need to run `source /home/mike/.rvm/scripts/rvm`
    in all your open shell windows, in rare cases you need to reopen all shell windows.

# Michael,
#
#   Thank you for using RVM!
#   We sincerely hope that RVM helps to make your life easier and more enjoyable!!!
#
# ~Wayne, Michal & team.

In case of problems: https://rvm.io/help and https://twitter.com/rvm_io
rvm 1.27.0 (latest) by Wayne E. Seguin <wayneeseguin@gmail.com>, Michal Papis <mpapis@gmail.com> [https://rvm.io/]
Searching for binary rubies, this might take some time.
No binary rubies available for: mint/17.3/x86_64/ruby-2.3.0.
Continuing with compilation. Please read 'rvm help mount' to get more information on binary rubies.
Checking requirements for mint.
Installing requirements for mint.
Updating system...........
Installing required packages: libreadline6-dev, zlib1g-dev, libssl-dev, libyaml-dev, libsqlite3-dev, sqlite3, autoconf, libgmp-dev, libgdbm-dev, libncurses5-dev, automake, libtool, bison, libffi-dev............|
Requirements installation successful.
Found user configured '-j' flag in 'rvm_make_flags', please note that RVM can detect number of CPU threads and set the '-j' flag automatically if you do not set it.
Installing Ruby from source to: /home/mike/.rvm/rubies/ruby-2.3.0, this may take a while depending on your cpu(s)...
ruby-2.3.0 - #downloading ruby-2.3.0, this may take a while depending on your connection...
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 13.5M  100 13.5M    0     0  2905k      0  0:00:04  0:00:04 --:--:-- 2906k
ruby-2.3.0 - #extracting ruby-2.3.0 to /home/mike/.rvm/src/ruby-2.3.0....
ruby-2.3.0 - #configuring..........................................................
ruby-2.3.0 - #post-configuration..
ruby-2.3.0 - #compiling.................................................................................
ruby-2.3.0 - #installing...........................
ruby-2.3.0 - #making binaries executable..
Installed rubygems 2.5.1 is newer than 2.4.8 provided with installed ruby, skipping installation, use --force to force installation.
ruby-2.3.0 - #gemset created /home/mike/.rvm/gems/ruby-2.3.0@global
ruby-2.3.0 - #importing gemset /home/mike/.rvm/gemsets/global.gems...............................................
ruby-2.3.0 - #generating global wrappers........
ruby-2.3.0 - #gemset created /home/mike/.rvm/gems/ruby-2.3.0
ruby-2.3.0 - #importing gemsetfile /home/mike/.rvm/gemsets/default.gems evaluated to empty gem list
ruby-2.3.0 - #generating default wrappers........
ruby-2.3.0 - #adjusting #shebangs for (gem irb erb ri rdoc testrb rake).
Install of ruby-2.3.0 - #complete
Ruby was built without documentation, to build it run: rvm docs generate-ri
Creating alias default for ruby-2.3.0...

  * To start using RVM you need to run `source /home/mike/.rvm/scripts/rvm`
    in all your open shell windows, in rare cases you need to reopen all shell windows.

Sourcing the RVM directory

When you installed RVM, one of the things the installer did was add a path statement to the end of your .bashrc file.

#export PATH="$PATH:$HOME/.rvm/bin" # Add RVM to PATH for scripting

Personally I didn’t have much luck getting this to work unless I explicitly sourced it each and every time I opened a new shell.

Well, that’s far too much work (and something I won’t always remember to do), so I ended up replacing it with the following function. Comment out the line installed by RVM and following that line, paste in the function shown below.

# Load RVM into a shell session *as a function*
if [[ -s "$HOME/.rvm/scripts/rvm" ]] ; then

# First try to load from a user install
  source "$HOME/.rvm/scripts/rvm"

elif [[ -s "/usr/local/rvm/scripts/rvm" ]] ; then

# Then try to load from a root install
  source "/usr/local/rvm/scripts/rvm"

else

  printf "ERROR: An RVM installation was not found.\n"

fi

Now source your ~/.basrc or restart your shell. From this point forward, you should never have to do this again.

To help you determine whether RVM has been properly sourced, perform a which ruby or which gem. The which command will return the respective path to the binary executable (which in this case, should be to your ~/.rvm directory).

Now that we have a build environment established, and the path to the ~/.rvm directory has been sourced, we can go ahead with installing Awestruct and Bundler.

Installing Awestruct, Bundler, and Rake

gem install awestruct bundler rake

On my system (Linux Mint 17.3), this installed a whole lot of things.

$~> gem install awestruct bundler rake
Fetching: tilt-2.0.2.gem (100%)
Successfully installed tilt-2.0.2
Fetching: netrc-0.11.0.gem (100%)
Successfully installed netrc-0.11.0
Fetching: mime-types-2.99.1.gem (100%)
Successfully installed mime-types-2.99.1
Fetching: unf_ext-0.0.7.2.gem (100%)
Building native extensions.  This could take a while...
Successfully installed unf_ext-0.0.7.2
Fetching: unf-0.1.4.gem (100%)
Successfully installed unf-0.1.4
Fetching: domain_name-0.5.20160310.gem (100%)
Successfully installed domain_name-0.5.20160310
Fetching: http-cookie-1.0.2.gem (100%)
Successfully installed http-cookie-1.0.2
Fetching: rest-client-1.8.0.gem (100%)
Successfully installed rest-client-1.8.0
Fetching: rack-1.6.4.gem (100%)
Successfully installed rack-1.6.4
Fetching: parallel-1.8.0.gem (100%)
Successfully installed parallel-1.8.0
Fetching: ast-2.2.0.gem (100%)
Successfully installed ast-2.2.0
Fetching: ansi-1.5.0.gem (100%)
Successfully installed ansi-1.5.0
Fetching: ruby-ll-2.1.2.gem (100%)
Building native extensions.  This could take a while...
Successfully installed ruby-ll-2.1.2
Fetching: oga-1.3.1.gem (100%)
Building native extensions.  This could take a while...
Successfully installed oga-1.3.1
Fetching: multi_json-1.11.2.gem (100%)
Successfully installed multi_json-1.11.2
Fetching: little-plugger-1.1.4.gem (100%)
Successfully installed little-plugger-1.1.4
Fetching: logging-2.1.0.gem (100%)
Successfully installed logging-2.1.0
Fetching: ffi-1.9.10.gem (100%)
Building native extensions.  This could take a while...
Successfully installed ffi-1.9.10
Fetching: rb-inotify-0.9.7.gem (100%)
Successfully installed rb-inotify-0.9.7
Fetching: rb-fsevent-0.9.7.gem (100%)
Successfully installed rb-fsevent-0.9.7
Fetching: listen-3.1.1.gem (100%)
Successfully installed listen-3.1.1
Fetching: haml-4.0.7.gem (100%)

HEADS UP! Haml 4.0 has many improvements, but also has changes that may break
your application:

* Support for Ruby 1.8.6 dropped
* Support for Rails 2 dropped
* Sass filter now always outputs <style> tags
* Data attributes are now hyphenated, not underscored
* html2haml utility moved to the html2haml gem
* Textile and Maruku filters moved to the haml-contrib gem

For more info see:

http://rubydoc.info/github/haml/haml/file/CHANGELOG.md

Successfully installed haml-4.0.7
Fetching: guard-compat-1.2.1.gem (100%)
Successfully installed guard-compat-1.2.1
Fetching: thor-0.19.1.gem (100%)
Successfully installed thor-0.19.1
Fetching: shellany-0.0.1.gem (100%)
Successfully installed shellany-0.0.1
Fetching: slop-3.6.0.gem (100%)
Successfully installed slop-3.6.0
Fetching: method_source-0.8.2.gem (100%)
Successfully installed method_source-0.8.2
Fetching: coderay-1.1.1.gem (100%)
Successfully installed coderay-1.1.1
Fetching: pry-0.10.3.gem (100%)
Successfully installed pry-0.10.3
Fetching: nenv-0.3.0.gem (100%)
Successfully installed nenv-0.3.0
Fetching: notiffany-0.0.8.gem (100%)
Successfully installed notiffany-0.0.8
Fetching: lumberjack-1.0.10.gem (100%)
Successfully installed lumberjack-1.0.10
Fetching: formatador-0.2.5.gem (100%)
Successfully installed formatador-0.2.5
Fetching: guard-2.13.0.gem (100%)
Successfully installed guard-2.13.0
Fetching: http_parser.rb-0.6.0.gem (100%)
Building native extensions.  This could take a while...
Successfully installed http_parser.rb-0.6.0
Fetching: eventmachine-1.2.0.1.gem (100%)
Building native extensions.  This could take a while...
Successfully installed eventmachine-1.2.0.1
Fetching: em-websocket-0.5.1.gem (100%)
Successfully installed em-websocket-0.5.1
Fetching: guard-livereload-2.5.2.gem (100%)
Successfully installed guard-livereload-2.5.2
Fetching: git-1.3.0.gem (100%)
Successfully installed git-1.3.0
Fetching: asciidoctor-1.5.4.gem (100%)
Successfully installed asciidoctor-1.5.4
Fetching: awestruct-0.5.7.gem (100%)
Successfully installed awestruct-0.5.7
Parsing documentation for tilt-2.0.2
Installing ri documentation for tilt-2.0.2
Parsing documentation for netrc-0.11.0
Installing ri documentation for netrc-0.11.0
Parsing documentation for mime-types-2.99.1
Installing ri documentation for mime-types-2.99.1
Parsing documentation for unf_ext-0.0.7.2
Installing ri documentation for unf_ext-0.0.7.2
Parsing documentation for unf-0.1.4
Installing ri documentation for unf-0.1.4
Parsing documentation for domain_name-0.5.20160310
Installing ri documentation for domain_name-0.5.20160310
Parsing documentation for http-cookie-1.0.2
Installing ri documentation for http-cookie-1.0.2
Parsing documentation for rest-client-1.8.0
Installing ri documentation for rest-client-1.8.0
Parsing documentation for rack-1.6.4
Installing ri documentation for rack-1.6.4
Parsing documentation for parallel-1.8.0
Installing ri documentation for parallel-1.8.0
Parsing documentation for ast-2.2.0
Installing ri documentation for ast-2.2.0
Parsing documentation for ansi-1.5.0
Installing ri documentation for ansi-1.5.0
Parsing documentation for ruby-ll-2.1.2
Installing ri documentation for ruby-ll-2.1.2
Parsing documentation for oga-1.3.1
Installing ri documentation for oga-1.3.1
Parsing documentation for multi_json-1.11.2
Installing ri documentation for multi_json-1.11.2
Parsing documentation for little-plugger-1.1.4
Installing ri documentation for little-plugger-1.1.4
Parsing documentation for logging-2.1.0
Installing ri documentation for logging-2.1.0
Parsing documentation for ffi-1.9.10
Installing ri documentation for ffi-1.9.10
Parsing documentation for rb-inotify-0.9.7
Installing ri documentation for rb-inotify-0.9.7
Parsing documentation for rb-fsevent-0.9.7
Installing ri documentation for rb-fsevent-0.9.7
Parsing documentation for listen-3.1.1
Installing ri documentation for listen-3.1.1
Parsing documentation for haml-4.0.7
Installing ri documentation for haml-4.0.7
Parsing documentation for guard-compat-1.2.1
Installing ri documentation for guard-compat-1.2.1
Parsing documentation for thor-0.19.1
Installing ri documentation for thor-0.19.1
Parsing documentation for shellany-0.0.1
Installing ri documentation for shellany-0.0.1
Parsing documentation for slop-3.6.0
Installing ri documentation for slop-3.6.0
Parsing documentation for method_source-0.8.2
Installing ri documentation for method_source-0.8.2
invalid options: -SNw2
(invalid options are ignored)
Parsing documentation for coderay-1.1.1
Installing ri documentation for coderay-1.1.1
Parsing documentation for pry-0.10.3
Installing ri documentation for pry-0.10.3
Parsing documentation for nenv-0.3.0
Installing ri documentation for nenv-0.3.0
Parsing documentation for notiffany-0.0.8
Installing ri documentation for notiffany-0.0.8
Parsing documentation for lumberjack-1.0.10
Installing ri documentation for lumberjack-1.0.10
Parsing documentation for formatador-0.2.5
Installing ri documentation for formatador-0.2.5
Parsing documentation for guard-2.13.0
Installing ri documentation for guard-2.13.0
Parsing documentation for http_parser.rb-0.6.0
Installing ri documentation for http_parser.rb-0.6.0
Parsing documentation for eventmachine-1.2.0.1
Installing ri documentation for eventmachine-1.2.0.1
Parsing documentation for em-websocket-0.5.1
Installing ri documentation for em-websocket-0.5.1
Parsing documentation for guard-livereload-2.5.2
Installing ri documentation for guard-livereload-2.5.2
Parsing documentation for git-1.3.0
Installing ri documentation for git-1.3.0
Parsing documentation for asciidoctor-1.5.4
Installing ri documentation for asciidoctor-1.5.4
Parsing documentation for awestruct-0.5.7
Installing ri documentation for awestruct-0.5.7
Done installing documentation for tilt, netrc, mime-types, unf_ext, unf, domain_name, http-cookie, rest-client, rack, parallel, ast, ansi, ruby-ll, oga, multi_json, little-plugger, logging, ffi, rb-inotify, rb-fsevent, listen, haml, guard-compat, thor, shellany, slop, method_source, coderay, pry, nenv, notiffany, lumberjack, formatador, guard, http_parser.rb, eventmachine, em-websocket, guard-livereload, git, asciidoctor, awestruct after 71 seconds
Fetching: bundler-1.11.2.gem (100%)
Successfully installed bundler-1.11.2
Parsing documentation for bundler-1.11.2
Installing ri documentation for bundler-1.11.2
Done installing documentation for bundler after 5 seconds
Fetching: rake-11.1.2.gem (100%)
Successfully installed rake-11.1.2
Parsing documentation for rake-11.1.2
Installing ri documentation for rake-11.1.2
Done installing documentation for rake after 1 seconds
43 gems installed

Configuring Awestruct

At this point we should be able to create our project directory and initialize it with Awestruct, etc. Again the documentation is severely lacking background information, etc.

Create a project directory and place it under version control

Create your project directory : mkdir myproj
Change directory into it: cd myproj
Initialize version control for the directory: git init

Create your .gitignore

Consult: http://awestruct.org/auto-deploy-to-github-pages/ for details on what to put into your ignore files.

Install missing gem dependencies

Now in a perfect world, you should now be able to initialize your project with Awestruct without any further fuss. Well, that would be nice, but there is a good chance you’re still missing some dependencies.

So, lets go ahead and get those installed.

Awestruct dependencies are a bit of a chicken and egg problem. As part of the Awestruct installation, it generates a Gemfile which you can use with Bundler. The problem is you need that file (along with Bundler) before you can even initialize the project. In some use cases (such as where you are sharing a project with Github, then bundler probably makes sense. Otherwise, you’re stuck installing things manually using gem install. So, there you go. It is what it is.

After that nice little introduction, I’ll qualify things by saying this step may (or may not) be optional (depending on your use case). You could try initializing the project now to see what’s still missing. Only way you’ll find out is by giving it a try.

Alternately, you can just forgo all that by installing what might be missing right now (even if you end up adding some gems you’ll never use).

gem install htmlcompressor uglifier coffee-script therubyracer therubyrhino less sass bootstrap bootstrap-sass compass zurb-foundation

If you don’t install these first, you’ll get all sorts of errors when you attempt to initialize your project.

Initialize your project with Awestruct

awestruct -i -f bootstrap

Awestruct is capable of using either Bootstrap or Foundation as the CSS framework. For a comparison between the Bootstrap and Foundation frameworks, see here: http://blog.teamtreehouse.com/use-bootstrap-or-foundation

Because our project is using Bootstrap, we have specified it as the CSS framework during our Awestruct initialization.

If all goes well, you should see something like the following. If you get more errors, then it’s likely you are still missing additional gem dependencies and will need to install those too.

$~> awestruct -i -f bootstrap
Create directory: /home/mike/website/_config
Create directory: /home/mike/website/_layouts
Create directory: /home/mike/website/_ext
Create file: /home/mike/website/_ext/pipeline.rb
Create file: /home/mike/website/.awestruct_ignore
Create file: /home/mike/website/Rakefile
Create directory: /home/mike/website/stylesheets
Create file: /home/mike/website/Gemfile
   create config.rb

*********************************************************************
Congratulations! Your compass project has been created.

You may now add sass stylesheets to the stylesheets subdirectory of your project.

Sass files beginning with an underscore are called partials and won't be
compiled to CSS, but they can be imported into other sass stylesheets.

You can configure your project by editing the config.rb configuration file.

You must compile your sass stylesheets into CSS when they change.
This can be done in one of the following ways:
  1. To compile on demand:
     compass compile [path/to/project]
  2. To monitor your project for changes and automatically recompile:
     compass watch [path/to/project]

More Resources:
  * Website: http://compass-style.org/
  * Sass: http://sass-lang.com
  * Community: http://groups.google.com/group/compass-users/
Create file: /home/mike/website/_config/site.yml
Create file: /home/mike/website/_layouts/base.html.haml
Create file: /home/mike/website/index.html.haml

Create your .gitignore

Before saving anything using GIT version control, you first need to configure your ignore files.

Awestruct installs a file named awestruct_ignore, but you may need to make additional entries into it. Also, you’ll need to manually create your .gitignore file.

For details on how to complete these steps, consult: http://awestruct.org/auto-deploy-to-github-pages/.

Configuring the Gemfile for Bundler

When you initialized your project using Awestruct, one of the files it created was Gemfile. Bundler uses this file to manage Ruby gem dependencies (much like Vundle and other plugin managers are used to manage plugins for VIM).

Configure the Gemfile

Start by uncommenting a few things in Gemfile. A couple of fixes are required here as well. For example the line with bootstrap-sass was looking for the wrong version. To get things working I also had to add gem opal to the bottom.

For reference, here is a copy of my Gemfile.

# This file is a Bundler dependency descriptor file. Its purpose is to list all of
# the dependencies you are using to build your site. It is highly recommended you use
# this to keep your dependencies up to date and not cause conflicts with other gems
# already on your system.
#
# If you do not already have Bundler installed on your computer, run:
#
#  gem install bundler
#
# To use this dependecy file simply run:
#
#  bundle install
#
# We do recommend that you install the gems into another directory however, to ensure
# your awestruct site is pristine and isn't using versions of gems from other programs.
# To do this execute:
#
#  bundle install --path .bundle
#
# More information about Bundler and its other commands can be found at http://gembundler.com/.
# To add other dependencies for your awestruct site simply follow the same pattern as you'll
# find below. To make use of dependecies listed here, simply remove the '#' from the start of
# the line to uncomment the dependency. We hope you enjoy using Awestruct!

source 'https://rubygems.org'                             # This tells Bundler where to look for gems

gem 'awestruct', '>= 0.5.7'                               # Goes without saying
gem 'webrick', '~> 1.3.1'                                 # The rack webserver to use in dev mode

gem 'bootstrap-sass', '>= 3.2.0.2'
gem 'compass', '>= 1.0.1'

# FIXME
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 'rb-fsevent', '~> 0.9', :require => false           # to remove warning about pulling, Mac OSX
# gem 'rb-inotify', '>= 0.9.0', :require => false         # to remove warning about pulling, Linux
# gem 'wdm', :platforms => [:mswin, :mingw], :require => false # to remove warning about pulling, Windows (ruby 1.9+)
# gem 'rb-fchange', '~> 0.0.6', :require => false         # to remove warning about pulling, Windows (ruby 1.8.7)
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
gem 'opal'

Run Bundler to install the dependencies listed in the Gemfile

bundle install

Again, this is what I saw it do on my system running Linux Mint 17.3:

$~> bundle install
Fetching gem metadata from https://rubygems.org/.......
Fetching version metadata from https://rubygems.org/...
Fetching dependency metadata from https://rubygems.org/..
Using rake 11.1.2
Using ansi 1.5.0
Using asciidoctor 1.5.4
Using ast 2.2.0
Installing execjs 2.6.0
Using git 1.3.0
Using formatador 0.2.5
Using rb-fsevent 0.9.7
Using ffi 1.9.10
Using lumberjack 1.0.10
Using nenv 0.3.0
Using shellany 0.0.1
Using coderay 1.1.1
Using method_source 0.8.2
Using slop 3.6.0
Using thor 0.19.1
Using eventmachine 1.2.0.1
Using http_parser.rb 0.6.0
Using guard-compat 1.2.1
Using multi_json 1.11.2
Using tilt 2.0.2
Using little-plugger 1.1.4
Using mime-types 2.99.1
Using parallel 1.8.0
Using rack 1.6.4
Using unf_ext 0.0.7.2
Using netrc 0.11.0
Installing sass 3.4.21
Installing chunky_png 1.3.5
Installing concurrent-ruby 1.0.1
Installing hike 1.2.3
Installing htmlcompressor 0.3.0
Installing libv8 3.16.14.13
Installing sourcemap 0.1.1
Installing ref 2.0.0
Installing webrick 1.3.1
Using bundler 1.11.2
Using ruby-ll 2.1.2
Installing autoprefixer-rails 6.3.5
Installing uglifier 3.0.0
Using rb-inotify 0.9.7
Using notiffany 0.0.8
Using pry 0.10.3
Using em-websocket 0.5.1
Using haml 4.0.7
Using logging 2.1.0
Using unf 0.1.4
Installing compass-core 1.0.3
Installing compass-import-once 1.0.5
Installing sprockets 3.5.2
Installing therubyracer 0.12.2 with native extensions
Using oga 1.3.1
Installing bootstrap-sass 3.3.6
Installing listen 3.0.6
Using domain_name 0.5.20160310
Installing compass 1.0.3
Installing opal 0.9.2
Using guard 2.13.0
Using http-cookie 1.0.2
Using guard-livereload 2.5.2
Using rest-client 1.8.0
Using awestruct 0.5.7
Bundle complete! 10 Gemfile dependencies, 62 gems now installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.
Post-install message from compass:
    Compass is charityware. If you love it, please donate on our behalf at http://umdf.org/compass Thanks!

As you can see, some of these gems were already installed. Others were missing and were downloaded and installed.

Using rake

At this point (assuming all dependencies have been satisfied), we should be able to launch our Awestruct website.

While it’s possible to directly use the awestruct command to perform various tasks (e.g. serve the site in development mode, deploy it, etc.), it’s easier to use rake for this purpose. For more details about rake see: http://awestruct.org/getting_started/

This page describes several rake tasks (things it can do). There is a fair bit of complexity to all this.

To get things moving, we’ll launch Awestruct in development mode.

rake clean preview

If you received any errors when running rake clean preview, you might need to add some 'requires' to _ext/pipeline.rb I did not have any errors caused by this, but added require 'asciidoctor' as I intend to use Asciidoctor for my text markup.

After fixing all the missing requires and installing any remaining missing gems, etc., you should now get something that looks like this:

$~> rake clean preview
Running command: bundle exec awestruct -d
Generating site: http://localhost:4242
Executing pipeline...
***************************************************************************
Starting preview server at http://localhost:4242 (Press Ctrl-C to shutdown)
***************************************************************************

[2016-03-27 17:56:22] INFO  WEBrick 1.3.1
17:56:22 - INFO - LiveReload is waiting for a browser to connect.
[2016-03-27 17:56:22] INFO  ruby 2.3.0 (2015-12-25) [x86_64-linux]
[2016-03-27 17:56:22] INFO  WEBrick::HTTPServer#start: pid=28187 port=4242

To preview the site in development mode, open your web browser to http:://localhost:4242.

Congratulations

If you have gotten this far, that’s quite an achievement. However, this is just the very beginning of a very long journey.

See the following link for some guidance of what to do next. https://raw.githubusercontent.com/graphitefriction/oscon-2013-docs-workshop/master/awestruct-asciidoc-tutorial.adoc

The URL above is based on using foundation, not bootstrap. Even so, you’ll find something useful in following it. You may also want to read up on the various extensions, etc.

Add a CSS theme

At this point the website does not look like much. To make the site look better, we need to add a CSS theme.

Visit http://bootswatch.com/ and pick a CSS theme.

Once you find a theme you like, download the bootstrap.css and rename it styles.css. Copy this file to your project/stylesheets directory.

Now shut down the site using (CTRL + C) and reload it once more using rake clean preview.

Ah….now that looks much better.

Save the state of the website using Git version control

Shut down the site once more using (CTRL + C) and perform a rake clean.

Perform a git add --all followed by a `git commit -m 'Fresh Awestruct build'.

For assistance using GIT, have a look at the tutorials found on GitHub.

Go Forth and Conquer!

You now have a functional Awestruct static website up and running in development mode. To learn how to use it, you may want to read up further about the various technologies used in Awestruct. You’ll be well advised to read up about using the Bootstrap CSS framework as well. And if you’re new to GIT, read about that too.

You can create your pages using pure HTML, or alternately you may wish to use a text based markup such as Markdown or Asciidoctor. If you have questions, visit the respective sites and Google, Google, Google until you find the answers.

Sunday, April 24, 2016

Installing Awestruct on Linux Mint 17.x

Installing Awestruct on Linux Mint 17.x

Introduction

Prerequisites

Installing a Ruby development environment

Method # 1 - System Level

Method # 2 - User Level - (preferred method)

Installing Awestruct, Bundler, and Rake

Configuring Awestruct

Configuring the Gemfile for Bundler

Using rake

Add a CSS theme

Save the state of the website using Git version control

Go Forth and Conquer!