News
0.10.1 Released

Adds haml options & fixes bug with partial options

How to Use

StaticMatic is very easy to work with. It aims to provide just the tools you need and not get in your way.

Developing a site with StaticMatic

Setting up a site

The first thing to do with a StaticMatic site is to set up the folders and files ready for use. A simple command will create everything you need to get started:

staticmatic setup my_site

This will set up a number of directories:

  • site/ - contains your static site and any assets such as images or javascript files
  • src/ - where you'll work on your templates
    • helpers/ - contains any helpers you want to use in your website (write your own or grab some from Helper Central)
    • layouts/ - contains templates that 'wrap' your main content pages
    • pages/ - contains the actual pages of content
    • partials/ - contains any "partial pages" that can be reused in other pages or layouts
    • stylesheets/ - contains any Sass stylesheets you want to create

Previewing your site

When you're ready to start working on your site, you can fire up the preview server to see your changes:

staticmatic preview my_site

This will start a web server on port 3000. Point your web browser to http://localhost:3000 to see your site.

Building your site

When you're happy with the website, you can tell StaticMatic to generate the HTML pages:

staticmatic build my_site

Configuration

You can put a file called configuration.rb in your staticmatic project's basedir/src directory. In this file, you can set configuration settings or whatever else since it's just a ruby file.

configuration.preview_server_port

The default is 3000.

configuration.preview_server_host

The default is localhost.

configuration.use_extensions_for_page_links

The default is true. When false .html and index.html will be stripped off urls generated by the link tag helper.

configuration.sass_options

Default is an empty hash. You can specify any options that Sass can take like :style => :compact

configuration.haml_options

Default is an empty hash. You can specify any options that Haml can take like:

:attr_wrapper => '"'

(have Haml use double quotes instead of single quotes for wrapping HTML attribute values)

Templates

For information on how to use Haml itself, please check out the Haml website.

Layouts

As with web frameworks like Ruby on Rails, StaticMatic uses layouts to 'wrap' up the content contained within page templates.

A layout typically contains the header and footer code for a page - code that is common to all pages on the site.

The only thing a layout *must* contain is a line that tells StaticMatic where to put the content:

= yield

By default, StaticMatic will look for a template named 'application.haml'. If you have a page that needs to use a different layout, this can be specified in the page itself:

contact_us.haml:
- @layout = "contact"

The above code would tell StaticMatic to use the layout called 'contact.haml' when building and previewing the 'contact_us' page.

Helpers

StaticMatic provides a number of 'helpers' on top of those in Haml to handle common code and reduce code.

Additionally you can write your own helpers and put them in your staticmatic src/helpers directory. You can checkout the Helper Central for some helpers that have already been written by others that you can drop in your helper directory.

Links

'link' ('link_to' works too for you Rails types) can automatically set up hyperlinks for you:

= link "Contact Us"
produces:
<a href="contact_us.html">Contact Us</a>"

It is also possible to specify a relative path in your url:

= link "../Contact Us"
produces:
<a href="../contact_us.html">Contact Us</a>"

You can also specify a URL:

= link "StaticMatic", "http://staticmatic.rubyforge.org"

Images

= img "me.jpg"
produces:
<img src="/images/me.jpg"/>

It is also possible to specify a relative path in your url:

= img "../me.jpg"
produces:
<img src="../me.jpg"/>

Stylesheets

= stylesheets

This will automatically insert links to any Sass stylesheets in your site source. It will also link up any static stylesheets in your site/stylesheets/ directory

You can also specify the files and the order explicitly along with setting attributes:

= stylesheets :reset, :application, :media => :screen
produces
<link href="stylesheets/reset.css" media="screen" rel="stylesheet"/>
<link href="stylesheets/application.css" media="screen" rel="stylesheet"/>

Javascript

= javascripts('test', :other)
produces:
<script language="javascript" src="/javascripts/test.js" type="text/javascript"></script>
<script language="javascript" src="/javascripts/other.js" type="text/javascript"></script>

Current page

It can be very useful to know what page you're on in your layout and helpers (ie: setting selected style on a menu item).

For the page src/pages/index.html
= current_page # => "/index.html"

For the page src/pages/subdirectory/other.html
= current_page # => "/subdirectory/other.html"

urlify

Will convert a string to be usable in a url

= urlify("We love Haml") # => "we_love_haml"
= urlify("Elf & Ham") # => "elf_and_ham"
= urlify("Stephen's gem") # => "stephens_gem"
= urlify("Test/Link") # => "testlink"

text_area

Generates a text area field

= text_area 'myname', 'myvalue'
produces:
<textarea id="myname" name="myname">myvalue</textarea>

text_field

Generates a text input field

= text_field('first_name', 'bob')
produces:
<input name="first_name" type="text" value="bob"/>

Partials

As with web frameworks like Ruby on Rails, StaticMatic uses partials to keep things DRY.

= partial('mypartial')

This will first look in the current page/partial's directory for a file called _mypartial.haml. If not found there it will look for src/partials/mypartial.haml.

Specify the partial's local variables

= partial('mypartial', :locals => { :title => 'My Title' })

This will locate the partial file as in the previous example above but now passes in a local variable called title that can be used in the partial like so:

%h1 title

Specify the partial's directory

= partial('shared/mypartial')

This will look for the file src/pages/shared/_mypartial.haml first. If not found there it will look for src/partials/mypartial.haml.