Quick Tip: How to Build Customizable HTML Widgets in Jekyll

The static site generator Jekyll is known in web design circles for being light-weight and “hacky”. But that is only part of the truth. Jekyll is surprisingly powerful in terms of what you can do with it, and how user-friendly you can make it to non-technical users and clients.

In this quick tip, I will show how you can build HTML widgets that your clients or team members can easily customize and include anywhere in a Jekyll project—no Ruby plugins needed, just Liquid, the open source template language created by Shopify, and good old HTML.

Setting Variables

--ADVERTISEMENT--

There are several ways of setting variables for customization. In this article, I’ll introduce two of them: the inline and Front matter methods.

Inline Variables

Setting variables inline is the best option if there’s a good chance the widget will be included more than once, say, in a blog post. In this example I’ll use a PayPal button.

First, create a new file called paypal-widget.html in your _includes folder. Then, fill it with this code:

This will create a button labeled “Buy Now | $30”. You can include the same file several times in the same page, each with different include.id and include.button values, as they are set individually inline.

Front Matter Variables

For longer text strings and widgets that will only be included once in a blog post, you can set the values of the variables in the Front matter of your posts and pages. In this example you’ll create a newsletter signup box.

As before, start by creating a new file in the _includes folder of your Jekyll project, name it something meaningful like signup-widget.html. Then, fill it with this code:

And then you can include the widget anywhere in the text, much like you did with the other example:

{% include signup-widget.html %}

The result, after adding some CSS, looks like this:

You can, of course, include this more than once in a blog post—but both instances would retrieve the values for their variables from the same source, so they’d look exactly the same. If you want to make it possible to include a widget more than once in one page or blog post and customize each one individually, inline variables are the way to go.

Conclusion

Well, there you have it. Two quick and easy ways to create powerful modules for your Jekyll project. The possibilities with this technique are endless, and I’d love to hear how you end up using it in the comments below. I’m happy to answer any questions you might have.