gulp-rhb
v1.0.0
Published
A sane Handlebars Gulp plugin.
Downloads
18
Maintainers
Readme
gulp-hb
This is a fork of gulp-bh
simply to base it off of a remote fs (s3)
A sane static Handlebars Gulp plugin. Useful as a static site generator. Powered by handlebars-wax
. Think Assemble, but with a lot less Jekyll baggage.
For Grunt, see grunt-hb
. To precompile templates into JavaScript, see gulp-handlebars
.
Install
npm install --save-dev gulp-hb
Usage
var gulp = require('gulp');
var hb = require('gulp-hb');
// Basic
gulp.task('basic', function () {
return gulp
.src('./src/{,posts/}*.html')
.pipe(hb({
partials: './src/assets/partials/**/*.hbs',
helpers: './src/assets/helpers/*.js',
data: './src/assets/data/**/*.{js,json}'
}))
.pipe(gulp.dest('./web'));
});
// Advanced
gulp.task('advanced', function () {
var hbStream = hb()
// Partials
.partials('./partials/components/**/*.{hbs,js}')
.partials('./partials/layouts/**/*.{hbs,js}')
.partials({
boo: '{{#each boo}}{{greet}}{{/each}}',
far: '{{#each far}}{{length}}{{/each}}'
})
// Helpers
.helpers(require('handlebars-layouts'))
.helpers('./helpers/**/*.js')
.helpers({
foo: function () { ... },
bar: function () { ... }
})
// Decorators
.decorators('./decorators/**/*.js')
.decorators({
baz: function () { ... },
qux: function () { ... }
})
// Data
.data('./data/**/*.{js,json}')
.data({
lorem: 'dolor',
ipsum: 'sit amet'
});
return gulp
.src('./src/{,posts/}*.html')
.pipe(hbStream)
.pipe(gulp.dest('./web'));
});
Template Context
The template context is a merge of pre-registered data and file-specific data. Pre-registered data is available to all templates and is set using the .data()
method. File-specific data is available to the current template and is set via the file.data
property.
@
Data Variables
@root
The merged object of pre-registered data and file-specific data is available as the primary context of your templates. In cases where accessing this data would require the use of ../
, you may access the top-level context via @root
:
{{ foo }}
{{ @root.foo }}
{{#each bar}}
{{ ../foo }}
{{ @root.foo }}
{{/each}}
@global
In cases where file-specific data keys collide with pre-registered data keys, you may access the pre-registered data via @global
:
{{ @global.foo }}
@local
In cases where pre-registered data should be ignored, you may access the file-specific data via @local
.
{{ @local.foo }}
@file
In cases where information about the template file itself is needed, you may access the file object via @file
:
{{ @file.path }}
File-specific Data Sources
File-specific data is set via the file.data
property using other plugins such as gulp-data
, gulp-data-json
, or gulp-front-matter
.
var gulp = require('gulp');
var data = require('gulp-data');
var frontMatter = require('gulp-front-matter');
var hb = require('gulp-hb');
gulp.task('inject', function () {
return gulp
.src('./src/*.html')
// Load an associated JSON file per post.
.pipe(data(function(file) {
return require(file.path.replace('.html', '.json'));
}))
// Parse front matter from post file.
.pipe(frontMatter({
property: 'data.frontMatter'
}))
// Data for everyone.
.pipe(hb().data('./data/**/*.js'))
.pipe(gulp.dest('./web'));
Multiple Data Sources
Multiple data sources can be used to render the same set of templates to different directories using through2
.
var gulp = require('gulp');
var hb = require('gulp-hb');
var through = require('through2');
gulp.task('i18n', function () {
return gulp
.src('./i18n/*.json')
.pipe(through.obj(function (file, enc, cb) {
var locale = file.stem;
var data = {
locale: locale,
i18n: JSON.parse(file.contents.toString())
};
gulp
.src('./templates/**/*.html')
.pipe(hb().data(data))
.pipe(gulp.dest('./dist/' + locale))
.on('error', cb)
.on('end', cb);
}));
});
API
hb([options]): TransformStream
options
{Object}
(optional) Passed directly tohandlebars-wax
so check there for more options.bustCache
{Boolean}
(default:true
) Force reload data, partials, helpers, and decorators.cwd
{String}
(default:process.cwd()
) Current working directory.debug
{Boolean|Number}
(default:false
or0
) Whether to log registered functions and data (true
or1
) and glob parsing (2
).handlebars
{Handlebars}
(optional) A specific instance of Handlebars, if needed.compileOptions
{Object}
Options to use when compiling templates.templateOptions
{Object}
Options to use when rendering templates.partials
{String|Array.<String>|Object|Function(handlebars)}
parsePartialName
{Function(options, file): String}
helpers
{String|Array.<String>|Object|Function(handlebars)}
parseHelperName
{Function(options, file): String}
decorators
{String|Array.<String>|Object|Function(handlebars)}
parseDecoratorName
{Function(options, file): String}
data
{String|Array.<String>|Object}
parseDataName
{Function(options, file): String}
Returns a Gulp-compatible transform stream that compiles Handlebars templates to static output.
.partials(pattern [, options]): TransformStream
pattern
{String|Array<String>|Object|Function(handlebars)}
options
{Object}
Same options ashb()
.
Loads additional partials. See handlebars-wax
.
.helpers(pattern [, options]): TransformStream
pattern
{String|Array<String>|Object|Function(handlebars)}
options
{Object}
Same options ashb()
.
Loads additional helpers. See handlebars-wax
.
.decorators(pattern [, options]): TransformStream
pattern
{String|Array<String>|Object|Function(handlebars)}
options
{Object}
Same options ashb()
.
Loads additional decorators. See handlebars-wax
.
.data(pattern [, options]): TransformStream
pattern
{String|Array<String>|Object}
options
{Object}
Same options ashb()
.
Loads additional data. See handlebars-wax
.
Contribute
Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.
Test
$ npm test
© Shannon Moeller [email protected] (shannonmoeller.com)
Licensed under MIT