Jekyll + Tailwind2 + Netlify

Here’s the new solution for your Ruby Flavored Jamstack. Yes, really!

Photo by Hannes Wolf on Unsplash

Adding Tailwind to a Jekyll website used to be a bit cumbersome. In this post, I’ll introduce you to the new jekyll-postcss v2 gem that ‘just works’. Yes, really!

Why Jekyll + Tailwind?

As a Ruby developer, you may need a website for your blogs or a pet project. Using a Ruby-based Static Pages generator makes double sense: 1) Because… duh… Ruby; 2) Chances are you will not be spending time on a stacic site daily, so not needing to switch to less familiar tools is a gain. With Jekyll we can add content from our editor, in markdown. Because who needs a CMS when we can use our editor?

Tailwind and especially the Tailwind typography plugin are such great solutions for backender-bloggers, for those projects where you don’t work with a designer or frontender. With just the plugin, you’ll import typography-design superpowers to achieve effortless style.

Jekyll was the first or at least a very early tool for what much later became known as the Jamstack. Jekyll’s been around forever, and its headstart became a bit of a disadvantage nowadays, as newer tools moved faster. As a result, adding Tailwind to a Jekyll site can be a challenge. That’s because we’d want to install Tailwind as a PostCSS plugin, and PostCSS is not built in in Jekyll — because PostCSS didn’t exist back then.

The good news: there is a straightforward solution available to make Jekyll and Tailwind play nicely together. I’ll show you what to do after I’ll explain what not to do.

The problem to solve: background

For a long time, the jekyll-postcss gem by Mitchell Hanberg has been the go-to solution for adding PostCSS plugins like Tailwind to Jekyll. However, if we’d want to use it with Tailwind 2 and the typography plugin, we’ll run in all kind of (Conversion) errors.

A few months ago, a newer gem became available, by a different author, Liam Bigelow, that works seamlessly with both Tailwind and its plugins. YAY!!!

The two gems take different approaches. The older gem is a Jekyll Converter plugin, which converts the output that is rendered by Jekyll. Instead, the newer gem is a Hook plugin: it extends, or hooks into, Jekyll’s build process. This hook approach avoids all the issues we’d had to solve with the converter gem.

Let’s do it

Example repo here https://github.com/emcoding/jekyll-tailwind-example/

Built with Ruby 2.7, Jekyll 2.4, Tailwind CSS v2.(15), jekyll-postcss-v2

1 Create a Jekyll site
First, create a Jekyll site. It doesn’t matter much if you create a site with the default Minima theme, or an empty site by adding the --blank flag to the new command. I used the latter for this post. If you use the theme, you’ll have to override some of the theme defaults. If you create the blank site, make sure to git init and bundle init yourself.

Add some markdown thingies like headers, a list, a link and `lorem` tekst to index.md, so we can measure success at the end. (Or copy it from my example.)
Start the server (% jekyll serve), and you'll see the Jekyll default text plus any markdown you added, with minimal styling applied.

Here's what's going to happen in the steps below. By adding Tailwindcss in the next step, the default styling gets a reset, so (almost) all the html generated from the markdown will be unstyled at first. Then, we'll load the typography plugin to come back with new and improved styling.

2 Add Tailwindcss

• Add packages

While Rails 6 (or rather Webpacker) is not compatible with PostCSS 8, there’s no such problem with Jekyll. So we can use the latest versions of the packages. We also add postcss-cli in this step, which we’ll need for the gem in the next step.

//first create a package.json
% yarn init -y 
//then add the packages
% yarn add -D tailwindcss@latest postcss@latest autoprefixer@latest postcss-cli

• Add the new gem postcss gem

Add the gem. (But do not add it as a plugin to_config.yml. This is new in Jekyll: either add a gem and add it as a plugin the _config.yml , or just add the gem to the :jekyll_plugins group.)

#in Gemfile
group :jekyll_plugins do
 gem 'jekyll-postcss-v2'
end

• Add the css

Replace the css in assets/css/main.scss with the Tailwind directives. Leave the Jekyll frontmatter in place.

Now that Jekyll can work with PostCSS, let’s configure PostCSS for Tailwind.

• Add config files

Create tailwind.config.js and postcss.config.js in one go:

% yarn tailwindcss init -p 

We’ll add config files and settings in the next steps.

3. Add the typography plugin

% yarn add -D @tailwindcss/typography

and add it to the plugins array in tailwind.config.js (note: require the plugin when using the array syntax, like so:)

module.exports = {
  ...
  plugins: [
    require('@tailwindcss/typography'),
  ],
}

Put the plugin to use by adding the prose class to the Liquid {{ content }} in your main layout file.

# in _/layouts/default.html
...
<div class="prose prose-yellow prose-sm">
  {{ content }}
</div>
...

4 Add the Inter font

The typography plugin, and especially the TailwindUI components are at their best with the Inter font.
We’ll add it as a yarn package via `@fontsource`…

% yarn add @fontsource/inter

… and add it to the Tailwind default theme like this:

// In tailwind.config.js
const defaultTheme = require('tailwindcss/defaultTheme')

module.exports = {
  //...
  theme: {
    extend: {
      fontFamily: {
        sans: ['Inter var', ...defaultTheme.fontFamily.sans],
      },
    },
  },
  // ...
}

In the default layout file, add the font-sans class in the html or body tag.

Now, if you restart the jekyll server you’ll see all the markdown elements nicely styled, in the Inter font.

5 Remove unused styles

We can use Tailwind’s purgecss to remove all unused styles.

# in tailwind.config.js
module.exports = {
  purge: [
    './**/*.html'
  ],
  //...
}

Check by setting the Node env to `production`:

% NODE_ENV=production jekyll build

The output file should be something around 20–30 kb.

6 Deploy to Netlify

Netlify will add a default build command to the deploy settings for Jekyll repo’s and run in development env. Purging, however, will only happen in with the Node environment set to production.
Change the default deploy settings on Netlify to: NODE_ENV=production bundle exec jekyll build. Or even better: add a script to package.json or a Netlify.toml config file.

And ready!

Now you’re ready to add some pages and blog your heart out.

Conclusion

The new jekyll-postscss-v2 gem makes it so much easier and neater to add Tailwind to Jekyll.

The Tailwind typography plugin is a perfect match with Jekyll, because when we add content in markdown format, we get “effortless style” where it matters most: the content.

View on Netlify: jekyll-tailwind-example.netlify.app

Or see my real life jekyll+tailwind site that inspired this blogpost: www.strippenkaart.nl (in Dutch).