Easier Documentation, Simpler Websites & Faster Collaboration

Every minute an editor spends managing presentational tweaks is one they can’t spend on critical stories.

Jeff Eaton

Build your site

A command typed in a terminal is a task automated.

Install Awestruct

Check Your Ruby version

$ ruby --version
# ruby 1.9.3p848 (2013-11-22 revision 40747) [x86_64-linux]
You must use the 32-bit version of Ruby 1.9.3 on Windows.
Windows install steps:
  1. Download Ruby Installer from http://tiny.cc/ruby193win
  2. Run installer, select default location
  3. Check "Add Ruby executables to your PATH"
  4. Configure RubyGems:
    (echo install: --no-rdoc --no-ri) > C:\ProgramData\gemrc
    (echo update: --no-rdoc --no-ri) >> C:\ProgramData\gemrc

Install RVM

Linux and OSX
$ \curl -L https://get.rvm.io -o rvm-installer
$ bash rvm-installer --ruby=2.0.0

Use Ruby as normal. Skip any RVM steps.

The RVM equivalent for Windows is named pik.

Create and use a new Ruby gemset (RVM only)

$ rvm use 2.0.0@writeadapt --create
If you want to use Ruby 1.9.3, replace 2.0.0 with 1.9.3.

Install Awestruct

$ gem install tilt --version 1.4.1
$ gem install awestruct --version 0.5.4.rc3
$ gem install asciidoctor
Console output
Successfully installed tilt-1.4.1
1 gem installed

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:


Successfully installed haml-4.0.4
Building native extensions.  This could take a while...
Successfully installed nokogiri-1.5.10
Successfully installed rb-fsevent-0.9.3
Building native extensions.  This could take a while...
Successfully installed ffi-1.9.3
Successfully installed rb-inotify-0.9.2
Successfully installed rb-kqueue-0.2.0
Successfully installed listen-1.1.6
Successfully installed sass-3.3.0.rc.2
Successfully installed multi_json-1.8.2
Successfully installed compass-core-1.0.0.alpha.13
Successfully installed chunky_png-1.2.9
    Compass is charityware. If you love it, please donate on our behalf at http://umdf.org/compass Thanks!
Successfully installed compass-1.0.0.alpha.13
Successfully installed compass-960-plugin-0.10.4
Successfully installed bootstrap-sass-
Successfully installed zurb-foundation-4.3.2
Successfully installed mime-types-1.25
Successfully installed rest-client-1.6.7
Successfully installed ruby-s3cmd-0.1.5
Successfully installed rack-1.5.2
Successfully installed awestruct-0.5.4.rc3
20 gems installed

Successfully installed asciidoctor-0.1.4
1 gem installed

Check version of Awestruct

$ awestruct --version
Console output
Awestruct: 0.5.4.rc3

Setup a new Awestruct project

Create a project folder and switch to it

Make empty project directory
$ mkdir writeadapt
Switch to new directory
$ cd writeadapt
Don’t forget to switch to the new directory or else the website will be generated in the wrong location.

Generate website structure

$ awestruct -i -f foundation
Console output
Create directory: /home/dallen/tmp/awestruct/writeadapt/_config
Create directory: /home/dallen/tmp/awestruct/writeadapt/_layouts
Create directory: /home/dallen/tmp/awestruct/writeadapt/_ext
Create file: /home/dallen/tmp/awestruct/writeadapt/_ext/pipeline.rb
Create file: /home/dallen/tmp/awestruct/writeadapt/.awestruct_ignore
Create file: /home/dallen/tmp/awestruct/writeadapt/Rakefile
Create file: /home/dallen/tmp/awestruct/writeadapt/Gemfile
Create directory: /home/dallen/tmp/awestruct/writeadapt/stylesheets
directory _site/stylesheets/
directory javascripts/foundation/
directory javascripts/vendor/
   create stylesheets/_normalize.scss
   create stylesheets/_settings.scss
   create stylesheets/app.scss
   create humans.txt
   create robots.txt
   create MIT-LICENSE.txt
   create javascripts/foundation/foundation.orbit.js
   create javascripts/foundation/foundation.cookie.js
   create javascripts/foundation/foundation.clearing.js
   create javascripts/foundation/foundation.magellan.js
   create javascripts/foundation/foundation.section.js
   create javascripts/foundation/foundation.alerts.js
   create javascripts/foundation/foundation.topbar.js
   create javascripts/foundation/foundation.joyride.js
   create javascripts/foundation/foundation.interchange.js
   create javascripts/foundation/foundation.forms.js
   create javascripts/foundation/foundation.tooltips.js
   create javascripts/foundation/foundation.abide.js
   create javascripts/foundation/foundation.dropdown.js
   create javascripts/foundation/foundation.placeholder.js
   create javascripts/foundation/foundation.reveal.js
   create javascripts/vendor/custom.modernizr.js
   create javascripts/vendor/jquery.js
   create javascripts/vendor/zepto.js
   create javascripts/foundation/foundation.js
   create index.html
DEPRECATION WARNING on line 224 of /home/dallen/.rvm/gems/ruby-2.0.0-p353@writeadapt/gems/zurb-foundation-4.3.2/scss/foundation/components/_global.scss:
Assigning to global variable "$default-float" by default is deprecated.
In future versions of Sass, this will create a new local variable.
If you want to assign to the global variable, use "$default-float: left !global" instead.

DEPRECATION WARNING on line 225 of /home/dallen/.rvm/gems/ruby-2.0.0-p353@writeadapt/gems/zurb-foundation-4.3.2/scss/foundation/components/_global.scss:
Assigning to global variable "$opposite-direction" by default is deprecated.
In future versions of Sass, this will create a new local variable.
If you want to assign to the global variable, use "$opposite-direction: right !global" instead.

   create _site/stylesheets/app.css

Now you're awestruct!

To generate and run your site in development mode, execute:

  awestruct -d

or, simply:


then visit your site at: http://localhost:4242

Create file: /home/dallen/tmp/awestruct/writeadapt/_config/site.yml
Create file: /home/dallen/tmp/awestruct/writeadapt/_layouts/base.html.haml
Create file: /home/dallen/tmp/awestruct/writeadapt/index.html.haml

Setup Gemfile

$ cat > Gemfile << LINES
source 'https://rubygems.org'
gem 'awestruct', '0.5.4.rc3'
gem 'asciidoctor', '0.1.4'
gem 'tilt', '1.4.1'
gem 'rake', '>= 0.9.2'
gem 'git', '1.2.6'
On Windows, run notepad Gemfile, remove all text and paste the content between LINES from above.

Lock dependencies

$ gem install bundler
$ bundle install
Console output
Fetching: bundler-1.3.5.gem (100%)
Successfully installed bundler-1.3.5
1 gem installed

Fetching gem metadata from https://rubygems.org/...
Resolving dependencies...
Installing rake (10.1.0)
Using asciidoctor (0.1.4)
Installing sass (3.2.12)
Using bootstrap-sass (
Using chunky_png (1.2.9)
Installing fssm (0.2.10)
Installing compass (0.12.2)
Using compass-960-plugin (0.10.4)
Using tilt (1.4.1)
Using haml (4.0.4)
Using rb-fsevent (0.9.3)
Using ffi (1.9.3)
Using rb-inotify (0.9.2)
Using rb-kqueue (0.2.0)
Installing listen (1.3.1)
Using mime-types (1.25)
Using nokogiri (1.5.10)
Using rack (1.5.2)
Using rest-client (1.6.7)
Using ruby-s3cmd (0.1.5)
Using zurb-foundation (4.3.2)
Using awestruct (0.5.4.rc3)
Using bundler (1.3.5)
Your bundle is complete!
Use `bundle show [gemname]` to see where a bundled gem is installed.

Awestruct project file tree

 `-- debug.log
 `-- site.yml
 `-- pipeline.rb
 |-- foundation/
 |   |-- foundation.alerts.js
 |   |-- ...
 |   |-- foundation.js
 |   |-- ...
 |   `-- foundation.topbar.js
 `-- vendor/
     |-- custom.modernizr.js
     |-- jquery.js
     `-- zepto.js
 `-- base.html.haml
 |-- app.scss
 |-- _normalize.scss
 `-- _settings.scss

Preview Site

Generate and preview website

$ rake
The no-argument rake command is a alias for rake preview.
Console output
Running command: bundle exec awestruct -d
Using profile: development
Generating site: http://localhost:4242
Starting preview server at http://localhost:4242 (Press Ctrl-C to shutdown)
[Listen warning]:
The blocking parameter of Listen::Listener#start is deprecated.
Please use Listen::Adapter#start for a non-blocking listener and Listen::Listener#start! for a blocking one.
[2013-12-03 17:20:43] INFO  WEBrick 1.3.1
[2013-12-03 17:20:43] INFO  ruby 2.0.0 (2013-11-22) [x86_64-linux]
[2013-12-03 17:20:43] INFO  WEBrick::HTTPServer#start: pid=19591 port=4242
new awestruct foundation site desktop
Desktop view
new awestruct foundation site phone
Mobile view

Halt the preview server

Press key combo


Console output
[2013-01-01 00:00:00] INFO  going to shutdown ...
[2013-01-01 00:00:00] INFO  WEBrick::HTTPServer#start done.

Structure of generated site

|-- humans.txt
|-- index.html
|-- javascripts/
|   |-- foundation/
|   |   |-- foundation.alerts.js
|   |   |-- ...
|   |   |-- foundation.js
|   |   |-- ...
|   |   `-- foundation.topbar.js
|   `-- vendor/
|       |-- custom.modernizr.js
|       |-- jquery.js
|       `-- zepto.js
|-- robots.txt
`-- stylesheets/
    `-- app.css

Setup Git repository for project

Initialize new git repository

$ git init .
Console output
Initialized empty Git repository in ...

Instruct git to ignore generated files

$ cat > .gitignore << LINES
On Windows, run notepad .gitignore, remove all text and paste the content between LINES from above.

Disable Jekyll

Linux / OSX
$ touch .nojekyll
$ echo "" > .nojekyll

Add all non-ignored files to the git repository

$ git add .

Commit the changes to make the snapshot

$ git commit -m "Initial import of website sources"
Console output
 30 files changed, 18757 insertions(+)
 create mode 100644 .awestruct_ignore
 create mode 100644 .gitignore
 create mode 100644 .nojekyll
 create mode 100644 Gemfile
 create mode 100644 Rakefile
 create mode 100644 _config/site.yml
 create mode 100644 _ext/pipeline.rb
 create mode 100644 _layouts/base.html.haml
 create mode 100644 humans.txt
 create mode 100644 index.html.haml
 create mode 100644 javascripts/foundation/foundation.alerts.js
 create mode 100644 javascripts/foundation/...
 create mode 100644 javascripts/vendor/custom.modernizr.js
 create mode 100644 javascripts/vendor/jquery.js
 create mode 100644 javascripts/vendor/zepto.js
 create mode 100644 robots.txt
 create mode 100644 stylesheets/_normalize.scss
 create mode 100644 stylesheets/_settings.scss
 create mode 100644 stylesheets/app.scss
Changes are now tracked by git. You can rollback at any time.

Create repository on GitHub

Repository name
Description (optional)
An Awestruct demo site
Don’t check "Initialize this repository with a README"

Connect git repository to GitHub remote

$ git remote add origin https://github.com/%USERNAME%/writeadapt-%USERNAME%
$ git push origin master
Replace %USERNAME% with your GitHub username.

Configure website metadata

Configure site identity

name: Write__Adapt__
title: WriteAdapt - For People Who Love Content
org: Strategy Media
author: The Octocat
author_url: https://github.com/octocat
base_url: ''
ctx_path: ''

Additional configuration to customize processor

# append
interpolate: false (1)
  :ugly: true (2)
1Disables interpolation of Ruby variable expressions in content (e.g., #{name})
2Disables pretty printing (indentation) of HTML output

Clean and preview site to see changes

$ rake clean preview
The clean step is required since a change to the configuration file, _config/site.yml, does not force pages to be regenerated automatically.

Write in plain text

I do not believe that on-page, in-context editing should be the primary edit mode of a CMS.

Deane Barker

Activate AsciiDoc content

Configure Asciidoctor

# append
  :safe: safe
    sitename: WriteAdapt
    base_url: ''
    ctx_path: ''
    idprefix: ''
    idseparator: '-'
    sectanchors: ''
    icons: font

Create a page in AsciiDoc format

about.adoc (NOT about.adoc.txt) in project folder
= About {sitename} (1)
Your Name
:page-layout: base (2)
:showtitle: (3)

{sitename} was founded by {author} during a conference workshop.
It's quickly becoming much bigger than this humble beginning.

This page is written in http://asciidoc.org[AsciiDoc].
It's transformed by http://awestruct.org[Awestruct] and http://asciidoctor.org[Asciidoctor] into a webpage for this static website.
1Becomes main heading on the page
2Specifies the layout to use to frame this content
3Shows the page title as an h1 heading

Add About link to navbar

            %a(href="#{site.ctx_path}/about.html") About

Make it Sassy!

Append to stylesheets/app.scss
.paragraph.lead > p {
  @extend %lead;

Clean and preview site to see changes

$ rake clean preview

Publish your site

Deploy to GitHub Pages

Commit and push any outstanding changes

$ git commit . -m "Enhancements"
$ git push origin master

Create the publish branch, gh-pages

$ git checkout --orphan gh-pages
$ rm -rf *
$ rm -rf .awestruct* .sass-* .gitignore .gitmodules
$ git rm --cached *
$ echo "GitHub Pages placeholder" > index.html
$ git add index.html .nojekyll
$ git commit -m "Seed publish branch for GitHub Pages"

Push the publish branch

$ git push origin gh-pages
$ git checkout master
By pushing the gh-pages branch, you also activated GitHub Pages to publish your website.
View your website

Setup the Awestruct GitHub Pages deployer

Append to _config/site.yml
    deploy: nil (1)
    base_url: http://%USERNAME%.github.io/writeadapt-%USERNAME%
    ctx_path: /writeadapt-%USERNAME%
        base_url: http://%USERNAME%.github.io/writeadapt-%USERNAME%
        ctx_path: /writeadapt-%USERNAME%
        imagesdir: http://%USERNAME%.github.io/writeadapt-%USERNAME%/images (2)
      host: github_pages
      branch: gh-pages
1nil deploy config forces development as default profile
2imagesdir must be absolute to work around Atom feed bug
Replace %USERNAME% with your GitHub username.

Commit deployer configuration

$ git commit _config/site.yml -m "Add profile for GitHub Pages deployment"
$ git push origin master

Deploy to GitHub Pages

$ rake clean deploy
View your website again
Your Awestruct-based website is now live, and available worldwide!

Content Write, Read and Chunk

Write once, use anywhere and everywhere

Read in the raw

Write the chunk