search

tnguyen14 / wintersmith-handlebars

handlebars plugin for wintersmith
26 stars 11 forks source link

readme

Handlebars plugin for Wintersmith

This plugin provides support for using Handlebars for Wintersmith.

This plugin was inspired from wintersmith-hogan.

How to use

Either

  1. Download the repo and copy the wintersmith-handlebars.coffee file into your plugins directory of your wintersmith install.
  2. Add wintersmith-handlebars.coffee to your config.json file.
  3. Starting writing handlebars templates in your templates directory as .html, .hbs or .handlebars files

Or

  1. Install it as a node module via npm install wintersmith-handlebars
  2. Follow steps 2 and 3 above.

Layouts

You can use layouts in wintermsith-handlebars the same way you do in hbs.

Write your layouts as you would normal templates, but make sure they include the variable {{{body}}}. (triple-handlebars prevent the HTML from being treated as plain text)

layout.html

<!DOCTYPE html>
<html>
  <head>
    <title>My Static Site</title>
  </head>
  <body>
    {{{body}}}
  </body>
</html>

Then in your templates, add a {{!< layout.html }} reference at the top of the file:

index.html

{{!< layout.html }}
<p>The index page.</p>

And it will be rendered like so:

<!DOCTYPE html>
<html>
  <head>
    <title>My Static Site</title>
  </head>
  <body>
    <p>The index page.</p>
  </body>
</html>

Partials

This plugin provides support for partials in handlebars.

To start using it, just add a partials directory in your template folder and add partial template files in there.

You can also rename this file to any other fancy name you would like. For eg, if you want it to be bits, you can simply define that in your config.json as follows:

"handlebars": {
  "partialDir": "bits"
}

Helpers

You can add helpers for Handlebars by adding functions in the helper directory. By default, this direcotry is named helpers, and is placed under templates. You can specify custom name for this folder in config.json:

"handlebars": {
  "helperDir": "helpers"
}

Each helper is its own file. The filename will be registered as the helper name.

An example of a helper function:

module.exports = function(stuff) {
  console.log(stuff);
    return;
}

See examples folder for more information.

Note

To use the locals variables in the template, instead of writing {{locals.name}} like in the jade template, simply just write {{name}}. This applies for other variables as well.

See the wiki for a sample 'locals' context being passed to the compiled handlebars template to see what's available and how to call them.

Under development

This plugin is my first attempt at bringing support for handlebars to wintersmith. It is still very new, experimental and under development (read: there might be bugs).

If for some reason it doesn't work for me, please submit an issue and I will hopefully fix it.

Smith away!