- Stable
2.0.1
Toggle Menu
1.93s70.65sHandlebars
Contents
| Eleventy Short Name | File Extension | npm Package |
|---|---|---|
hbs |
.hbs |
handlebars.js |
You can override a .hbs file’s template engine. Read more at Changing a Template’s Rendering Engine.
Installation
The haml templating language was moved out of Eleventy core in v3 and now requires a plugin installation.
npm install @11ty/eleventy-plugin-handlebarsAdd to your configuration file (ESM version shown):
import handlebarsPlugin from "@11ty/eleventy-plugin-handlebars";
export default function (eleventyConfig) {
eleventyConfig.addPlugin(handlebarsPlugin);
}const handlebarsPlugin = require("@11ty/eleventy-plugin-handlebars");
module.exports = function (eleventyConfig) {
eleventyConfig.addPlugin(handlebarsPlugin);
}Use more options:
import handlebars from "handlebars";
import handlebarsPlugin from "@11ty/eleventy-plugin-handlebars";
export default function (eleventyConfig) {
eleventyConfig.addPlugin(handlebarsPlugin, {
// Override the `ejs` library instance
eleventyLibraryOverride: handlebars,
});
}const handlebars = require("handlebars");
const handlebarsPlugin = require("@11ty/eleventy-plugin-handlebars");
module.exports = function (eleventyConfig) {
eleventyConfig.addPlugin(handlebarsPlugin, {
// Override the `ejs` library instance
eleventyLibraryOverride: handlebars,
});
}Supported Features
| Feature | Syntax |
|---|---|
| ✅ Partials | {{> user}} looks for _includes/user.hbs. Does not process front matter in the include file. |
| 🚫 Partials (Relative Path) | Not yet supported: {{> ./user}} looks for user.hbs in the template’s current directory. |
| ✅ Helpers (Custom Tags) | {{ helperName myObject }} Handlebars calls them Helpers, but Eleventy calls them Shortcodes. Read more about Shortcodes or Custom Tags. |
| ✅ Filters | {{ filterName myObject }} Read more about Filters. |
| ✅ Shortcodes | {{{ uppercase name }}} Read more about Shortcodes. |
Helpers
Helpers are used to transform or modify content.
Both Eleventy Universal Filters and Universal shortcodes are exposed as Helpers in Handlebars templates.
Read more about Handlebars Helpers syntax
Filters
A note about Universal Filters
Universal filters have always been funneled into Handlebars helpers. However, shortcodes (Paired/Single) match better with the semantic footprint of Handlebars Helpers.
Moving forward for Handlebars content, using Universal Shortcodes are preferred to Universal Filters. We will continue to support funneling Universal filters to Handlebars helpers. This will not affect your template content as the syntax for Handlebars filters/helpers/shortcodes will continue to be the same. They’re all just helpers.
Shortcodes
Shortcodes are basically reusable bits of content. Handlebars makes use of existing synchronous Universal shortcodes.
export default function(eleventyConfig) {
eleventyConfig.addShortcode("user", function(name, twitterUsername) {
return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
</div>`;
});
};module.exports = function(eleventyConfig) {
eleventyConfig.addShortcode("user", function(name, twitterUsername) {
return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
</div>`;
});
};Usage
{{{ user "Zach Leatherman" "zachleat" }}}Outputs
<div class="user">
<div class="user_name">Zach Leatherman</div>
<div class="user_twitter">@zachleat</div>
</div>Paired Shortcode
export default function(eleventyConfig) {
eleventyConfig.addPairedShortcode("user", function(bioContent, name, twitterUsername) {
return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
<div class="user_bio">${bioContent}</div>
</div>`;
});
};module.exports = function(eleventyConfig) {
eleventyConfig.addPairedShortcode("user", function(bioContent, name, twitterUsername) {
return `<div class="user">
<div class="user_name">${name}</div>
<div class="user_twitter">@${twitterUsername}</div>
<div class="user_bio">${bioContent}</div>
</div>`;
});
};Usage
Note that you can put any Handlebars tags or content inside the {{ user }} shortcode! Yes, even other shortcodes!
{{# user "Zach Leatherman" "zachleat" }}Zach likes to take long walks on Nebraska beaches.{{/ user }}Outputs
<div class="user">
<div class="user_name">Zach Leatherman</div>
<div class="user_twitter">@zachleat</div>
<div class="user_bio">Zach likes to take long walks on Nebraska beaches.</div>
</div>