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

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:

<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
  <input name="cmd" type="hidden" value="_s-xclick">
  <input name="hosted_button_id" type="hidden" value="VALUE">
  <button class="buy-button" name="submit">Buy Now</button>
  <img src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" alt="" width="1" height="1" border="0" style="display: none !important;">
</form>

The above example will generate a simple “Buy Now” button, allowing people to pay via PayPal. There’s just one problem: the code is static and can’t be customized.

The widget has two elements you will want to keep dynamic: the value of the hosted_button_id and the button label. Achieving this with inline variables is quickly done:

<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
  <input name="cmd" type="hidden" value="_s-xclick">
  <input name="hosted_button_id" type="hidden" value="{{ include.id }}">
  <button class="buy-button" name="submit">{{ include.button }}</button>
  <img src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" alt="" width="1" height="1" border="0" style="display: none !important;">
</form>

The variables you added are include.id and include.button. When you are ready to include the HTML widget inside, say, a Markdown post, you can simply do this:

{% include paypal-widget.html id="EXAMPLE-ID" button="Buy Now | $30" %}

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:

<div class="signup-cta">

  <h2>Sign up to the newsletter</h2>
  <p>Receive daily updates straight to your inbox—just fill out your name and email address and hit Submit!</p>

  <form method="POST">
    <input id="name" placeholder="First name">
    <input type="email" placeholder="Email address">
    <button type="submit">Submit</button>
  </form>

</div>

In this example, there are three elements you want to keep dynamic: the h2 text, the p element’s text below it, and the button text:

<div class="signup-cta">

  <h2>{{ page.cta.title }}</h2>
  <p>{{ page.cta.body }}</p>

  <form method="POST">
    <input id="name" placeholder="First name">
    <input type="email" placeholder="Email address">
    <button type="submit">{{ page.cta.button }}</button>
  </form>

</div>

Now when you include it in a Markdown post or page, define the following variables in the Front matter using Yaml:

---
cta:
    title: "Get the newsletter"
    body: "Like this blog post? Sign up to receive more content like this, delivered straight to your inbox every day."
    button: "Sign me up!"
---

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.

Frequently Asked Questions about Building Customizable HTML Widgets in Jekyll