stack
=====

Generates a static site from template files with YAML and Liquid. Stack supports template transformation through Markdown, Textile and Less CSS.

Within template files, stack allows you to use bi-directional YAML variables and include files.

Dependencies
------------

* [Liquid][] - Templating system 
* [RedCloth][] - Textile transformation
* [Maruku][] - Markdown transformation
* [Less][] - CSS transformation

Install
-------

Available through [Gemcutter][].

	gem install stack

Usage
-----

### Command Line


	cd /path/to/my/site
	stack [command] [options]
	
#### Commands

	generate
	
Generate runs through the source and transforms the templates, if no source is specified the current directory will be used.
	
	gen
	
Alias of `generate`.
	
	server
	
Runs a web server serving the output of the transformed source, by default when running stack in server mode your templates will be automatically transformed when changed (this can be disabled).
	
	watch
	
Watches a directory and re-builds whenever theres file changes.
	
#### Options

	--source [DIR]
	
Directory to use as the source for generating a site with stack, by default the current directory will be used.
	
	--target [DIR]
	
Directory to use as the target directory, if none is specified the target will be a folder called `_stack` in the source directory.
	
##### Server Options
	
	--port [PORT]
	
Specifies the port number the server should use when serving content through the `server` command.
	
	--disable-watch
	
Disables automatic transformation when serving content through the `server` command. 
	
### Ruby

	require 'stack'

	Stack::Generator.new("/path/to/source", "/path/to/target")

Templates and YAML
------------------

Template files can contain YAML block's that are processed by stack and can be used to define Liquid variables for use in your templates. A YAML block can be something like;

	---
	layout: application
	title: Page Title
	---
	
### Pre-defined variables

	layout

This specifies the layout file to use around the content, theres no need to specify the extension. The layout must be defined in a file inside a `_layout` folder that is within the current template scope, if you have templates defined in a sub-folder you can have a `_layout` folder that only templates in the sub-folder can access.

	generator
	
This variable holds the current hash used to transform the current template. You should not override this from the YAML block.

	generator.time
	
The current Time from when the stack processed and transformed the templates.

	generator.processed_at
	
The current Time the `generator` processed the templates.

	generator.transformed_at
	
The current Time the `generator` transformed the templates.

### Liquid Templates

Its out of the scope of this project's README file to describe how Liquid templating can be used, for more information see the [Liquid Wiki][].

#### Filters
	
	{{ generator.time | date_to_xmlschema }} #=> 2009-10-31T21:16:06+00:00
	
Transforms a Time into a XML schema format string.

	{{ generator.time | date_to_string }} #=> 31 Oct 2009
	
Transforms a Time into a formatted string.

	{{ title | xml_escape }} #=>
	
Escapes the specified string for use in XML.

Contribute
----------

* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a future version unintentionally.
* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

License
-------

Copyright (c) 2009 Adam Livesley (sixones). See LICENSE for details.

[Liquid]: http://liquidmarkup.org/ "Liquid"
[RedCloth]: http://redcloth.org/ "RedCloth"
[Maruku]: http://maruku.rubyforge.org/ "Maruku"
[Less]: http://lesscss.org/ "Less"
[Gemcutter]: http://gemcutter.org/gems/stack "Gemcutter"
[Liquid Wiki]: http://wiki.github.com/tobi/liquid/ "Liquid Wiki"