Enables the use of Handlebars Helpers in the template.

Gruntfile.js

@@ -40,6 +40,7 @@ module.exports = function(grunt) {
                         'test/example/assets/js/*.js',
                     ],
                     readme: 'test/example/assets/sass/readme.md',
+                    //handlebarsHelpers: ['test/helpers/**/*.js'],
                     //theme: 'test/theme.css',
                     //template: 'test/template.hbs'
                     //highlight: 'github'

README.md

@@ -74,6 +74,12 @@ Default: `null`
 
 *Optional*. A path to a Handlebars template file. Will use default Sassdown template if left blank.
 
+#### options.handlebarsHelpers
+Type: `Array`<br/>
+Default: `null`
+
+*Optional*. Array of file paths. The [Handlebars helpers](http://handlebarsjs.com/#helpers) will be available to use in the template. Supports [globbing](http://gruntjs.com/configuring-tasks#globbing-patterns). Supports relative and absolute file paths (eg. `http://`, `https://` or even `file://`).
+
 #### options.theme
 Type: `String`<br/>
 Default: `null`
@@ -234,6 +240,32 @@ Sassdown also provides a series of Handlebars **partials**, which can be used to
 
 * `{{> theme}}`<br>Outputs the theme stylesheet, minified, into a `<style>` tag.
 
+### Handlebars helpers
+
+You can add more features to Handlebar templates by using [Helpers](http://handlebarsjs.com/#helpers).
+
+For example you could add a helper that capitalizes all text:
+
+    <big>{{uppercase shoutThis}}</big>
+
+You load your helpers with the `handlebarsHelpers` option.
+
+    handlebarsHelpers: ['hb-helpers/**/*.js']
+
+The helper module must export a function that does the registration, or else it won't load.
+
+    module.exports = function(Handlebars) {
+        Handlebars.registerHelper('uppercase', function(input) {
+          return typeof input === 'string' ? input.toUpperCase() : input;
+        });
+    };
+
+    // This also works
+    module.exports = {
+      register: function(Handlebars) {
+        ...
+    }
+
 # Highlight.js
 
 Sassdown uses the popular and well-supported [Highlight.js](http://highlightjs.org/) for syntax highlighting. Markup is parsed by a Node module and highlighted before being output through the template. Various popular themes are supported via the task options.

tasks/libs/sassdown.js

@@ -50,6 +50,18 @@ module.exports.init = function (_grunt) {
     Sassdown = this;
 };
 
+module.exports.registerHandlebarsHelpers = function () {
+    var helpers = Sassdown.getFileList(Sassdown.config.option.handlebarsHelpers);
+    helpers.forEach(function (helper) {
+        helper = path.resolve(__dirname, path.relative(__dirname, process.cwd()), helper);
+        if (fs.existsSync(helper)) {
+            helper = require(helper);
+            if (typeof helper.register === 'function') { helper.register(Handlebars); }
+            else if (typeof helper === 'function') { helper(Handlebars); }
+        }
+    });
+};
+
 module.exports.template = function () {
     // Check for existence of user defined template
     Sassdown.checkfor('template', datapath('template.hbs'));
@@ -86,16 +98,12 @@ module.exports.checkfor = function (requirement, defaults) {
     }
 };
 
-module.exports.assets = function () {
-    // Check if we added includes option
-    if (!Sassdown.config.option.assets) {
-        warning('User assets not specified. Styleguide will be unstyled!');
-    } else {
-        // Create empty array
-        var fileList = [];
-        // Expand through matches in options and include both
-        // internal and external files into the array
-        Sassdown.config.option.assets.forEach( function (asset) {
+module.exports.getFileList = function (assets) {
+    var fileList = [];
+    // Expand through matches in options and include both
+    // internal and external files into the array
+    if (assets && typeof assets.forEach === 'function') {
+        assets.forEach( function (asset) {
             grunt.file.expand(asset).forEach( function (file) {
                 fileList.push(file);
                 grunt.verbose.write(file+'...').ok();
@@ -105,8 +113,16 @@ module.exports.assets = function () {
                 grunt.verbose.write(asset+'...').ok();
             }
         });
-        // Insert as list of files as new assets object
-        Sassdown.config.assets = fileList;
+    }
+    return fileList;
+};
+
+module.exports.assets = function () {
+    // Check if we added includes option
+    if (!Sassdown.config.option.assets) {
+        warning('User assets not specified. Styleguide will be unstyled!');
+    } else {
+        Sassdown.config.assets = Sassdown.getFileList(Sassdown.config.option.assets);
     }
 };
 

tasks/sassdown.js

@@ -23,6 +23,7 @@ module.exports = function (grunt) {
                 assets: null,
                 readme: null,
                 template: null,
+                handlebarsHelpers: null,
                 highlight: null,
                 excludeMissing: false,
                 dryRun: false,
@@ -40,6 +41,7 @@ module.exports = function (grunt) {
 
         // Subtask: Scaffold, Template, Theme
         grunt.verbose.subhead('Compile the Handlebars template, theme and syntax highlighter:');
+        Sassdown.registerHandlebarsHelpers();
         Sassdown.scaffold();
         Sassdown.template();
         Sassdown.theme();

test/helpers/handlebars.lowercase.js

@@ -0,0 +1,5 @@
+module.exports.register = function(Handlebars) {
+    Handlebars.registerHelper('lowercase', function(input) {
+        return typeof input === 'string' ? input.toLowerCase() : input;
+    });
+};

test/helpers/nested-helpers/handlebars.uppercase.js

@@ -0,0 +1,5 @@
+module.exports = function(Handlebars) {
+    Handlebars.registerHelper('uppercase', function(input) {
+        return typeof input === 'string' ? input.toUpperCase() : input;
+    });
+};