Migrating from HTML to Handlebars

In a previous post, I described how I rebuilt my site to use Eleventy. This post picks up from there and describes what I did to convert my website from a set of static HTML pages to use Handlebars templates.

The Goal

To make my website easier to maintain, I want the ability to group common code into subtemplates so that I can reuse those subtemplates across multiple pages. This will also allow me to make changes in one file and have those changes reflect across multiple pages instead of having to update each individual file.

I could use one of many template engines to accomplish this but I chose Handlebars simply because I've used it in the past and it works well for what I need.

The Process

In order to accomplish the goal, I split the process up into two major steps:

1. Create a default page layout
2. Update files to use the default page layout

Create a Default Page Layout

The one of the first major benefits that I encountered in using Eleventy is that you don't need to configure Handlebars. If you save your HTML files as .hbs files, Eleventy detects that you want to use Handlebars to render that file.

I did add the following snippet of code to my .eleventy.js configuration file so that I could use Handlebars with .html files:

    return {
        htmlTemplateEngine: "hbs"
    }
            

Depending on the approach you use, it can be intimidating to set up Handlebars to take advantage of layouts and partials (subtemplates). Luckily, Eleventy makes it easy to hook things up.

For my blog pages, the content within the <main> tag represents the content of my pages. So I want that to differ from page to page while everything else around it stays the same.

Eleventy has some great documentation on how to create layouts. I used that as my guide as I created a new layout file called layout-default.hbs that contained the code that I wanted to include on every page. In the spot where I wanted the content from my individual blog files to be included, I used the {{{content}}} shortcode.

Since my content includes HTML markup that I want rendered, I needed to use triple curly braces ({{{content }}}), otherwise the template engine would render the HTML as text instead of the actual HTML that I want it to.

Using the Layout in My Blog Pages

Once I created my layout file, I updated my static HTML files to use the layout.

At the top of each file, I defined the layout:

    ---
    layout: layout-default.hbs
    ---
            

I saved the file and when Eleventy regenerated my pages, I could see the layout being applied because there was duplicate content on the page. I removed any code from each file that already existed in my layout so that they rendered as they did before... almost.

Updating the Titles for Each Page

In my layout, I included the HTML title for the page. However, this caused the same title to appear on every page. To solve this, I added some Front Matter Data with the page title to each blog post. For example:

    ---
    layout: layout-default.hbs
    title: Name of the Blog Post
    ---
            

Then in my layout, I updated the title tag so that it would render the title using the data from each blog post:

    <title>{{ title }}<title/>
            

With that, I had converted my site from static HTML files with lots of repeated code to a set of Handlebars templates where the common code could be updated by making changes to a single file.