Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    grunt-generatorpublic

    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.loadNpmTasks('grunt-generator');

    Documentation

    Assuming the following your Gruntfile.js:

     
    var helpers = require('helpers');
     
    grunt.initconfig({
      generator: {
        dev: {
          files: [
            { cwd: 'pages', src: ['**/*'], dest: 'build', ext: '.html' }
          ],
          options: {
            partialsglob: 'pages/partials/*.html',
            templates: 'templates',
            handlebarshelpers: helpers,
            environment: 'dev'
          }
        }
      }
    ...
     

    and the following in helpers.js:

    module.exports = {
      'test': function(s) {
        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' }} 
    'pageTitle': function(pageName) {
        return (this.pages[pageName] ? this.pages[pageName].title : "");
    }
     
    ...

    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',
            templateEngine: function(content, context) {
              // custom template engines must return the output as a string 
              // a promise, or throw an exception on error 
              return "Hello, " + context.name + "\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.

    install

    npm i grunt-generator

    Downloadslast 7 days

    15

    version

    0.4.1

    license

    none

    repository

    github.com

    last publish

    collaborators

    • avatar