grunt-stencil

grunt-stencil

Stencil is a Grunt plugin for templating that generates static HTML files from given components. Stencil provides the following:

• A way to modularise your HTML source files: each file can include an arbitrary number of partial files, or be wrapped with a template file.
• Built in support for the doT.js templating language, which allows passing of arbitrary variables to your HTML files.
• Built in support for markdown
• Meta data headers in the beginning of each file to specify variables that should be used in the file (that are accessible from partials included in the file, and templates the file is injected into).

Documentation

See the Wiki pages for full documentation.

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-stencil --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-stencil');

The "stencil" task

Options

A more detailed explanation of all options can be found in the Wiki.

Each of the following is optional.

options.dot_template_settings

Type: Object Default value: {}

An object that specifies the template settings that are passed to the doT compiler (see doT.js).

options.env

Type: Object Default value: {}

Initial environment seen by all compiler, doT.js sees it as it. This environment is for each file with their header fields.

options.templates

Type: String Default value: "."

A String value specifying the location of all templates. When specified, this will allow to call templates in pages' meta data without the full path to it (the specified templates will be prepended).

options.partials

Type: String Default value: "."

A String value specifying the location of all partials. When specified, this will allow to call partial include functions without the full path (the specified partials will be prepended).

options.meta_data_separator

Type: String | RexExp Default value: /\r?\n\r?\n/

A String value specifying the characters to search for when separating meta data from the content of a file. By default, the JSON header of a file is considered to end after the first blank line in the file.

Usage Examples

An elaborate list of examples can be found in the Wiki.

In your project's Gruntfile, add a section named stencil to the data object passed into grunt.initConfig().

grunt.initConfig({
  stencil: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      // Target-specific file lists and/or options go here.
    },
  },
})

Grunt's rules for defining target and destination files apply, but care needs to be taken to make sure each input page maps to a single output file.

Custom Options

In this example, doT's it object is used to specify the location of script files and the main title of all pages; and the location of partials and templates is given. All pages in pages/ will be compiled to .html files in tmp.

grunt.initConfig({
  stencil: {
    main: {
      options: {
        env: {
          title: "Stencil",
        },
        partials: "content",
        templates: "templates"
      },
      files: [
        {
          expand: true,
          cwd: "src/pages/",
          src: "**/*.dot.html",
          dest: "tmp",
          ext: ".html",
          flatten: true
        }
      ]
    },
  }
})

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code using Grunt. Please ignore W092 errors (wrapping regexps). The warning will show up until there's an option to disable it in jshint.

You can run the test suite with grunt test or grunt testv for more verbose output.

Each new feature ough to have full test coverage. We usually start by writing a fixture which is a pair of two file: the one to process (the fixture) and it's expected output. Fixture are html or md files in spec/fixtures. Any partials and templates required by this fixture should be stored in spec/partials and spec/templates, respectively. The expected output of a fixture should be put in spec/expected.

Once we run tests and the fixture is failing, we can implement any necessary feature by starting with writing specs (unit tests) in the spec directory, (like spec/my_new_feature_spec.js) and then implementing it in lib directory (lib/my_new_feature.js).

Once all the unit tests pass, we can integrate new code back to the task with making the fixture test pass in mind :) .

If you take a look at any file in lib/ you can notice that there's no dependencies between modules. All dependencies are injected in the task file tasks/stencil.js. That's the place where the integration happens.

Release History

• version 1.1.0 (1st June, 2014) - apply doT to all HTML files
• version 1.0.2 (10th December, 2013) - Windows compatibility
• version 1.0.1 (24th November, 2013) - fix for new markdown version
• version 1.0.0 (7th October, 2013) - first stable release
• version 0.1.0 (4th October, 2013) - big refactor and change of specification
• version 0.0.3 (19th September, 2013) - fix dependencies in package.json
• version 0.0.2
• version 0.0.1 (16th September, 2013)