grunt-generator
Static site generator for Grunt supporting Handlebars, DustJS and custom template engines and authoring pages using HTML, markdown (showdown library), etc.
Getting Started
Install this grunt plugin next to your project's grunt.js gruntfile with: npm install grunt-generator
Then add this line to your project's Gruntfile.js
gruntfile:
grunt;
Documentation
Assuming the following your Gruntfile.js
:
var helpers = ; grunt
and the following in helpers.js
:
moduleexports = { return "test " + s; };
grunt-generator will build HTML and markdown pages in the pages/
directory. Outputting generated pages to build/
. Each 'page' is run through handlebars.js and has access to the helpers specified above (in the example: helpers.js). Each page also has access to the optional metadata that can be specified at the top of every page as a JSON fragment:
"title" : "Test Title"--- <div class="content">...
A pages own metadata is available as the page
variable. In addition all other pages can be accessed using the pages
collection available to all pages. Using the above example: if the page is located at dir1/test1.html
then it's title can be accessed using a handlebars helper like so:
... // example: {{ pageTitle 'dir1/test1' }} { return thispagespageName ? thispagespageNametitle : "";} ...
Since all metadata is available to all pages (and their templates) at build time complex processing can be done using handlebars helpers such as navigation hierarchies, tagging/categories, etc.
The templates in templates/
will be used to render the final output and are also passed through handlebars.js. The templates are given a special variable body
which is the rendered output of the current 'page' (Note: Make sure you use the "triple-stash" expression for body
, so Handlebars doesn't escape the HTML: {{{ body }}}
). To specify a non-default template for a page use the template
metadata. The following will render using alternate.html as the template instead of the default (ie. index.html):
"title": "Test title" "template" : "alternate"--- <div class...
Handlebars partials can be specified using the partialsGlob
option. These will be available to all pages using their filename minus extension. Partials can be placed in the same directory as pages and will not be processed as unique pages.
See the spec/pages
and spec/templates
directory for a complete example.
DustJS and Custom Template Engine Support
As of version 0.3.0
the template engine used can be changed to DustJS or overridden with your own custom template function:
Dust Templates
DustJS templates have a number of advantages such as supporting async helpers and better access to the context in helper functions. Remember to turn off escaping of the body content in your templates: {body|s}
.
generator: dev: files: cwd: 'pages' src: '**/*' dest: 'build' ext: '.html' options: templateEngine: 'dust' templates: 'templates' helpers: helpers environment: 'dev' ...
Note: Dust templates support the dust partials syntax but it is not recommended to mix HTML/Markdown partials. Since the markdown compilation for pages occurs after the partials are processed HTML partials mixed into Markdown pages may produce undesired results.
Custom
Custom template functions must return the rendered template as a string or a promise-like object that resolves to the rendered template (or rejects). You may also throw an exception on error. Return a promise object if you need to perform asynchronous tasks. Note that the template function will be called twice for each page: once for the page itself and again when it is rendered into the template. grunt-generator uses the Q library for it's promises
generator: dev: files: cwd: 'pages' src: '**/*' dest: 'build' ext: '.html' options: templates: 'templates' helpers: helpers environment: 'dev' { // custom template engines must return the output as a string // a promise, or throw an exception on error return "Hello, " + contextname + "\n" + content; } ...
Custom Frontmatter
The frontmatter can be changed to use custom delimiters and also to use YAML syntax instead of JSON:
generator: dev: files: cwd: 'pages' src: '**/*' dest: 'build' ext: '.html' options: templates: 'templates' helpers: helpers environment: 'dev' frontmatterDelimiter: '###' frontmatterType: 'yaml' ...
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt.
Release History
See CHANGELOG.md
License
Copyright (c) 2012 Charles Lavery
Licensed under the MIT license.