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:
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
- 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:
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:
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
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:
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: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.
Links
'link' can automatically set up hyperlinks for you:
It is also possible to specify a relative path in your url:
You can also specify a URL:
Images
It is also possible to specify a relative path in your url:
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:
<link href="stylesheets/application.css" media="screen" rel="stylesheet"/>
Javascript
<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.htmlFor the page src/pages/subdirectory/other.html
urlify
Will convert a string to be usable in a url
= urlify("Elf & Ham") # => "elf_and_ham"
= urlify("Stephen's gem") # => "stephens_gem"
= urlify("Test/Link") # => "testlink"
text_field
Generates a text input field
Partials
As with web frameworks like Ruby on Rails, StaticMatic uses partials to keep things DRY.
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
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:
Specify the partial's directory
This will look for the file src/pages/shared/_mypartial.haml first. If not found there it will look for src/partials/mypartial.haml.