stasis

Follow @wintonius
Static Sites Made Powerful

Install

$ gem install stasis

Install via RubyGems

Example

At its most essential, Stasis takes a directory tree with supported template files and renders them.

project/
    index.html.haml
    images/
        image.png

Example directory structure

$ cd project
$ stasis

Run stasis

project/
    index.html.haml
    images/
        image.png
    public/
        index.html
        images/
            image.png

Stasis creates a public directory

index.html.haml becomes public/index.html.

Unrecognized extensions are copied as-is (image.png).

Controllers

Controllers contain Ruby code that executes once before all templates render.

project/
    controller.rb
    index.html.haml
    styles/
        controller.rb
        style.css.sass

Example directory structure

You may have a controller at any directory level.

Before

Use before blocks within controller.rb to execute code before a template renders.

before 'index.html.haml' do
  @something = true
end

controller.rb

@something is now available to the index.html.haml template.

before 'index.html.haml', /.*html\.erb/ do
  @something = true
end

The before method can take any number of paths and/or regular expressions

Layouts

%html
  %body= yield

layout.html.haml

layout 'layout.html.haml'

In controller.rb, set the default layout

layout 'index.html.haml' => 'layout.html.haml'

Set the layout for a particular template

layout /.*html.haml/ => 'layout.html.haml'

Use a regular expression

before 'index.html.haml' do
  layout 'layout.html.haml'
end

Set the layout from a before block

Render

%html
  %body= render '_partial.html.haml'

Within a template

before 'index.html.haml' do
  @partial = render '_partial.html.haml'
end

Within a before block

render :text => 'Hello'

Text

render 'index.html.haml', :locals => { :x => true }

Local variables

render 'index.html.haml' { 'Hello' }

Include a block for the template to yield to

Instead

before 'index.html.haml' do
  instead render('subdirectory/index.html.haml')
end

The instead method changes the output of the template being rendered

Helpers

helpers do
  def say_hello
    'Hello'
  end
end

controller.rb

The say_hello method is now available to all before blocks and templates.

Ignore

Use the ignore method in controller.rb to ignore certain paths.

ignore /\/_.*/

Ignore filenames with an underscore at the beginning

Priority

Use the priority method in controller.rb to change the file process order.

priority /.*txt/ => 2, 'index.html.erb' => 1

Copy .txt files before rendering the index.html.erb template

The default priority is 0 for all files.

Usage

Command Line

Always execute the stasis command in the root directory of your project.

$ stasis -d

Development mode (auto-regenerate on save)

$ stasis -d 3000

Specify a port to start an HTTP server

$ stasis -o index.html.haml,subdirectory

Only render specific files or directories

$ stasis -p ../public

Change the public (destination) directory

Ruby Library

stasis = Stasis.new('/path/to/project/root')

Instantiate a Stasis object

stasis = Stasis.new('/project', '/html')

Optionally specify a destination directory

stasis.render

Render all templates

stasis.render('index.html.haml', 'subdirectory')

Render a specific template or directory

More

Supported Markup Languages

ENGINE                     FILE EXTENSIONS
-------------------------- -----------------------
ERB                        .erb, .rhtml
Interpolated String        .str
Erubis                     .erb, .rhtml, .erubis
Haml                       .haml
Sass                       .sass
Scss                       .scss
Less CSS                   .less
Builder                    .builder
Liquid                     .liquid
RDiscount                  .markdown, .mkd, .md
Redcarpet                  .markdown, .mkd, .md
BlueCloth                  .markdown, .mkd, .md
Kramdown                   .markdown, .mkd, .md
Maruku                     .markdown, .mkd, .md
RedCloth                   .textile
RDoc                       .rdoc
Radius                     .radius
Markaby                    .mab
Nokogiri                   .nokogiri
CoffeeScript               .coffee
Creole (Wiki markup)       .wiki, .creole
WikiCloth (Wiki markup)    .wiki, .mediawiki, .mw
Yajl                       .yajl

Stasis uses Tilt to support the following template engines

Server Mode

Stasis can run as a server that uses redis to wait for render jobs.

$ stasis -s localhost:6379/0

Stasis server that uses redis on port 6379

Stasis::Server.push(
  # Paths to render
  :paths => [ "index.html.haml", "subdirectory" ],

  # Made available to views as `params`
  :params => {},

  # Redis address
  :redis => "localhost:6379/0",

  # Return rendered templates (false by default)
  :return => false,

  # Block until templates generate (false by default)
  :wait => false,

  # Write to the filesystem (true by default)
  :write => true,

  # Cache ttl for returned templates (nil by default)
  :ttl => nil,

  # Force write even if cached (false by default)
  :force => false
)

Push to the server (in Ruby)

This Web Site

Take a look at the Stasis project that automatically generated this web site from the project README.

Thanks

Please follow the project on Github.
Follow Winton Welsh on Twitter for updates: