Marrying Tailwind with Jekyll

Ruby has more than one beloved framework - there's also Jekyll.

Jekyll is a simplistic framework for static websites that originally sparked the static website and JAMstack movements. While there are many similar frameworks with more features, Jekyll remains one of the simplest on the market. It has been somewhat forgotten and hasn't evolved much lately, to the point where some people decided to take matters into their own hands and fork this framework into something called Bridgetown.

Surprisingly, in many projects, I don't really need more than what Jekyll can offer. So, I remain a loyal user. Until recently, I didn't have much to complain about, not until I decided to rebuild poshtui.com with Tailwind CSS. The only way to add Tailwind and Heroicons was through a JavaScript bundler, and I'm no longer used to that approach.

As it sometimes happens in the Open Source world - the stars aligned in the right way. I stumbled upon work by @crbelaus on jekyll-tailwind. He demonstrated that it's possible to integrate both, but his solution was lacking. I then found work by @flavorjones who extracted the tailwindcss-ruby gem from the Rails core gem.

To keep things short, over the next couple of weeks, I worked to improve the integration of Tailwind and Heroicons with Jekyll. An example of this work can be found in the jekyll-tailwind-cli-template. The current setup experience with jekyll-heroicons and jekyll-tailwind is not exactly a walk in the park, but it's much easier than working with JavaScript bundlers.

jekyll-tailwind

tailwindcss-ruby will be used in Rails, so this gem now depends on it as well.

This work brought everything you would expect from Tailwind:

• Minification
• PostCSS support
• All the tweaking of tailwind.config.js
• Ability to provide input/output files
• People can move to Tailwind v4 on their own accord

@flavorjones did a wonderful job here; it was a breeze to write the integration! @crbelaus was a great collaborator, and he offered me to step up as a maintainer.

jekyll-heroicons

Besides the obvious way to distribute SVGs without a JavaScript bundler, the gem offers small quality of life improvements. Any icon can be used just by typing a name:

{% heroicon bell %}

You can define a default variant in _config.yml, but you can also overwrite it on a per-icon basis.

heroicons:
  variant: 'solid'

It's possible to define default classes that will be applied to all icons:

heroicons:
  default_class: {
    solid: "size-6",
    outline: "size-6",
    mini: "size-5",
    micro: "size-4",
  }

But it's also possible to turn that off, provide your own classes, or any other tags for the SVG element:

# Disable default_classes
{% heroicon bell disable_default_class: true %}
# Provide additional classes
{% heroicon bell class: "text-red-500" %}
# Provide any other attribute for svg html element
{% heroicon bell class: "text-red-500" aria-hidden: true height:32 aria-label:hi %}

There's no need to copy SVGs one by one or reach out to a JavaScript bundler!

Ending notes

Jekyll might have a chance for a revival in light of recent trends in the Ruby ecosystem. Ruby developers are eagerly looking for ways to simplify and condense complexity. And now, there's a simpler way to use Tailwind CSS with this amazing framework. I hope you'll find it useful.