# Plate

[![Build Status](https://secure.travis-ci.org/jdtornow/plate.png)](http://travis-ci.org/jdtornow/plate) [![Dependency Status](https://gemnasium.com/jdtornow/plate.png?travis)](https://gemnasium.com/jdtornow/plate)

Plate is a super simple static site generator and blog engine. At its core, it takes a folder full of Markdown files and turns it into a static HTML site that you can host anywhere.

In addition to basic formatting with Markdown, Plate also supports generating more dynamic files with ERB or HAML, and compiling asset files with CoffeeScript, Sass and others.

Plate is a command line utility installed as a Ruby Gem. Installation requires Ruby 1.8.7, 1.9.2 or 1.9.3. For additional processing, install CoffeeScript, Sass, Haml and other formatters.

## Installation

    gem install plate

Or, create a `Gemfile` and add:

    gem 'plate'

## Command line

Plate is designed to be a command-line utility. Here is a rundown of some of the basic commands:

### Creating a new site

To generate a new site with plate, run the following command:

    platify .

Or, with the normal `plate` command:

    plate new .

### Building a site

To build your site, run:

    plate build

Or, just run `plate` without any options to build the site.

    plate

To show details about the site build, enable verbose mode:

    plate --verbose

### Creating a new post

To create a new blog post with the default options, run:

    plate post "New Post Name"

You can also put default post options (such as a category or layout) into the command line:

    plate post "New Post Name" --category Articles --layout post

Or, if you always use the same default category and/or layout, you can put those options into your config file instead like so:

    # In config/plate.yml
    ...
    post_defaults:
      category: Articles
      layout: post
    ...

## Directory Structure

Plate observes the following folder structure in your site:

* config/ - Put your global configuration settings here.
* content/ - All custom content for the site, besides blog posts. Everything in this folder will be copied over to the published site.
* helpers/ - Helpers are loaded into views automatically and can be used within dynamically rendered pages using a template language. (Such as Erb or Haml)
* layouts/ - Global layouts available for use on all content pages and posts.
* lib/ - Extend the basic functionality of Plate with plugins in this directory. All `.rb` files run against the Plate DSL.
* posts/ - All blog post content for the site. Posts can be organized into sub-directories if you like.
* public/ - This will be generated if it does not exist, contains the produced site. Set this as the web server root to your site for development mode.

## Extending Plate

Plate is meant to be extended easily. You might want to extend the basic functionality of Plate to add additional functionality for your site. To get started, create a directory named `lib` in the root of your site. Any Ruby files (ending in `.rb`) will be automatically loaded into the stack when Plate is run.

### Callbacks

Callbacks are used to call certain blocks of code when an event happens in the lifecycle of building a site.

The callbacks currently available are:

* Site - `before_render`, `after_render`
* Page/Post - `before_render`, `after_render`, `before_write`, `after_write`
* Asset - `before_render`, `after_render`, `before_write`, `after_write`

Example of a callback to be run when a site completes the build:

    register_callback :site, :after_render do |site|
       puts "the site finished rendering!"
    end

Put the above snippet in any file in the lib folder, and it will be registered when your site is compiled.

### Helpers

Helpers are modules that are automatically loaded into views. Any methods in the module will be available when you render a page.

An example of a helper file located in `helpers/sample_helper.rb`

    module SampleHelper
      def sample_helper_method
        "yes"
      end
    end

Then, in your `.erb` view you can call `sample_helper_method`.

All files in the `helpers/` directory are assumed to be helper modules and will be loaded automatically at runtime.

## Full Documentation

View the [full documentation on rdoc.info](http://rdoc.info/gems/plate/frames)

## Issues

If you have any issues or find bugs running Plate, please [report them on Github](https://github.com/jdtornow/plate/issues). While most functions should be stable, Plate is still in its infancy and certain issues may be present.

## Testing

Plate is fully tested using Test Unit, Shoulda and Mocha. To run the test suite, `bundle install` then run:

    rake test

## License

Plate is released under the [MIT license](http://www.opensource.org/licenses/MIT)

Contributions and pull-requests are more than welcome.