Deris

A documentation templating engine based on HAML

Installation

Whenever significant functionality is added to deris a new gem will be added to rubygems so installation is easy:

gem install deris

Getting started

Deris takes and transforms the contents of one directory and transforms and writes it out to another directory. Your source directory should be laid out something like this:

myproject/
  _src/
    layout.haml

_src/layout.haml is the only file deris expects to exist.

Any files and directories within myproject that aren't within _src will be copied over to the output directory. This lets you have static content such as CSS files and images.

To get deris to generate HTML from this directory you'll want to call it like this:

require 'rubygems'
require 'deris'

Deris::Project.new('myproject/').write('myoutput/')

Which will result in an output like this:

myoutput/
  index.html

This is because the contents of the _src directory are used to create the index.html for your site.

If you want to take advantage of the templating capabilities you will want to create a layout.haml something like this:

-# myproject/_src/layout.haml
!!! 5
%html

  %head
    %title 
      Deris example
    
  %body
  
    %h1 Deris example
    
    #content_wrapper
                  
      #content
        =partial :content

You will now want to create a content.haml to provide the markup for the :content partial:

-# myproject/_src/content.haml
%h3 Home page

%p
  As this is in the _src directory it will be used to create index.html

If you want to add another generated page to the site you need to create a new directory under the _src:

myproject/
  _src/
    morrisons/
      content.haml
    content.haml
    layout.haml

When the page is generated it will take the name of the directory, in this case that means the file will be called morrisons.html. Each directory can override the partials from its parent. This means that morrisons.html will be created by the combination of _src/layout.haml and _src/morrisons/content.haml.

You can nest directories within other directories as well:

myproject/
  _src/
    morrisons/
      bread/
        content.haml
      content.haml
    content.haml
    layout.haml

Which will result in an output like this:

myoutput/
  morrisons/
    bread.html   # _src/layout.haml + _src/morrisons/bread/content.haml
  index.html     # _src/layout.haml + _src/content.haml
  morrisons.html # _src/layout.haml + _src/morrisons/content.haml

If you prefer you can specify the :content partial in a file with the same name as the directory. This stops you ending up with multiple files called content.haml which can make the project a bit easier to traverse. If there is a file with the same name as the directory and a content.haml then the :content partial will refer to content.haml, not the file with the same name as the directory.

You can create URLs relative to the root of your generated content by using the url helper in your HAML files:

%a{:href => url('morrisons/bread.html')} Bread

This will look at the current "depth" of the file within your project and prepend the correct quantity of ../ to your URL.

Getting help

You can get hold of me on twitter, through a message on github or even via ye olde email at garry@robustsoftware.co.uk