The best plugin for metalsmith + Handlebars. Global/local partials, in-place & layout compilation, and maximum customizability.
Combines all of metalsmith-handlebars, metalsmith-handlebars-contents, metalsmith-handlebars-layouts, metalsmith-discover-helpers, metalsmith-discover-partials, @goodthnx/metalsmith-handlebars, metalsmith-nested, metalsmith-register-helpers, metalsmith-register-partials and adds more. Written out of frustration with incomplete and/or complex existing options.
- filter files by
pattern
- auto-load global and local partials found in directory specified by option
partials
- compile contents (like metalsmith-in-place) and layout (like metalsmith-layouts)
- includes useful basic
set
andcall
helpers - allows custom Handlebars, partials, helpers
- also works with metalsmith-layouts, handlebars-layouts
NPM:
npm i -D metalsmith-handlebars-x
Yarn:
yarn add metalsmith-handlebars-x
var xhandlebars = require('metalsmith-handlebars-x');
// use defaults
metalsmith.use(xhandlebars());
// use defaults (explicit)
metalsmith.use(xhandlebars({
instance: require('handlebars'),
pattern: '**/*.{hbs,handlebars}',
layout: true,
partials: 'partials',
helpers: {},
context: (filemeta, globalmeta) => Object.assign({}, globalmeta, filemeta),
renameExtension: null
});
Set env var DEBUG
to metalsmith-handlebars-x
.
Linux / OSX
DEBUG=metalsmith-handlebars-x
Windows
set DEBUG=metalsmith-handlebars-x
Partials will be looked for in the directory specified in the partials
option.
Partials are automatically removed from the build output unless layout: false
.
A partial at partials/blockquote.hbs
will be usable in templates as blockquote
.
A partial at partials/layout/default.hbs
will be usable in templates as layout/default
.
Global partials (available to all templates) can be registered either by specifying a directory in the Metalsmith.source
directory:
metalsmith.use(handlebars({ partials: 'partials' }));
or by passing the Handlebars instance to the plugin:
var Handlebars = require('handlebars');
Handlebars.registerPartial('blockquote', '<blockquote cite="{{url}}">{{ quote }}</blockquote>');
metalsmith.use(handlebars({ instance: Handlebars }));
Both can be used together!
Local partials will be available to all templates that reside in the same directory.
In the directory structure below both .md
files have access to partial layout/default
.
├── partials
| └── layout
| └── default.hbs
└── posts
├── partials
| └── local.hbs
├── subfolder
| └── post-without-local-partials.md
└── post-with-local-partials.md
metalsmith-handlebars-x provides 2 useful helpers by default:
call
:{{ call func arg1 arg2 arg3 }}
allows calling functions available in template contextset
:{{ set varname value }}
allows storing temporary variables for re-use in the template
Register extra helpers through the helpers
option as {[helperName]: helperFunc}
, or similar to global partials,
register them directly on a Handlebars instance passed to the instance
option.
Specify a custom context
option to map file & global metadata in your templates, e.g:
context: function(filemeta, globalmeta) {
return {
page: filemeta,
site: globalmeta
};
}
In your templates:
{{ site.sitename }} {{ page.stats.birthTime }}
With the renameExtension
option you can choose what to do with a file's extension:
null
orundefined
does nothing (default)""
(empty string) removes the last extension (soindex.hbs
would becomeindex
, whilestyle.css.hbs
would becomestyle.css
)".<ext>"
renames the last extension to<ext>
, for exampleindex.hbs
would becomeindex.html
ifrenameExtension: '.html'
.
Relatively straight-forward:
const Handlebars = require('handlebars');
const hbsLayouts = require('handlebars-layouts')(Handlebars);
const xhandlebars = require('metalsmith-handlebars-x');
Handlebars.registerHelper(hbsLayouts);
metalsmith.use(xhandlebars({ instance: Handlebars }));
You can use this plugin together with @metalsmith/layouts & metalsmith-discover-partials but you should specify layout: false
in order to avoid conflicts. metalsmith-handlebars-x will then only compile file contents
. See test.js for an example.