Adding Tailwind to a Jekyll site on Windows
Tags: webdev, jamstack, tailwindcss, jekyll
Published: 2021-09-08 21:38:48

---
title: Adding Tailwind to a Jekyll site on Windows
published: true
date: 2021-07-06 15:00:00 UTC
tags: webdev,jamstack,tailwind,jekyll
canonical_url: https://katiekodes.com/jekyll-tailwind/
---

I've been wanting to migrate one of my web sites from the Github Pages Jekyll to 11ty for a while so that I could use Tailwind CSS and facitate a redesign of the look and feel.

In the end, I realized that migrating old `.md` files w/o [breaking anchor links to subsections](https://kittygiraudel.com/2020/11/30/from-jekyll-to-11ty/#heading-anchors) was going to be a regex nightmare, and I'd be better off figuring out how to add Tailwind to Jekyll.

<!--more-->

## Minimum viable build

I put up [my working code at Github](https://github.com/kkgthb/web-site-jekyll-02-tailwind-tiny), and here's a [live demo](https://jekylltailwind.netlify.app/).

This is the first codebase I got working while implementing [Steven Westmoreland's](https://stevenwestmoreland.com/2021/01/using-tailwind-css-with-jekyll.html) and [Marcin Doliwa's](https://mdoliwa.com/articles/how-to-setup-jekyll-with-tailwind-css) directions to add Tailwind to [this tiny Jekyll site](https://github.com/kkgthb/web-site-jekyll-01-tiny).

I failed trying a million and a half more complex starters involving webpack, gulp, etc.  I'm glad the solution turned out simple in the end _(Ruby's `jekyll-postcss` plugin)_.

Clone it, run it, and play with the Tailwind classes in `pages/index.md` yourself.

## Issues

### JIT

`jekyll-postcss` works just fine, as long as you don't expect Tailwind to work in JIT mode _([bug report 1](https://github.com/mhanberg/jekyll-postcss/issues/22), [bug report 2](https://github.com/tailwindlabs/tailwindcss-jit/issues/41))_.

### SCSS

I also haven't gotten this architecture properly handling an `assets/css/main.scss` _(note **S**css)_ file; just plain CSS.

### Windows

If your localhost environment is on Windows, `jekyll-postcss` will fail with an `ENOEXEC` `Exec format error` something like this:

```sh
...
Conversion error: Jekyll::Converters::PostCss encountered an error while converting 'assets/css/main.css':
                    Exec format error - C:/Ruby27-x64/lib/ruby/gems/2.7.0/gems/jekyll-postcss-0.4.1/bin/postcss '{"raw_content":"@import \"tailwindcss/base\";\n@import \"tailwindcss/components\";\n@import \"tailwindcss/utilities\";"}'
...
C:/Ruby27-x64/lib/ruby/gems/2.7.0/gems/jekyll-postcss-0.4.1/lib/jekyll-postcss/socket.rb:20:in ``': Exec format error - C:/Ruby27-x64/lib/ruby/gems/2.7.0/gems/jekyll-postcss-0.4.1/bin/postcss '{"raw_content":"@import \\"tailwindcss/base\\";\\n@import \\"tailwindcss/components\\";\\n@import \\"tailwindcss/utilities\\";"}' (Errno::ENOEXEC)
...
```

You have to install the Windows Subsystem for Linux _(WSL)_ as in [Scott Hanselman's instructions](https://www.hanselman.com/blog/ruby-on-rails-on-windows-is-not-just-possible-its-fabulous-using-wsl2-and-vs-code) and run Jekyll from a **WSL** command line.

_(Be sure to remember to run `bundle install` and `npm i` in WSL first to install the Ruby and Node.js codebases.)_

Thanks to [Veselin Romic](https://veselin.dev/) and [Brittney Postma](https://brittneypostma.com/) for debugging [my stacktrace](https://github.com/mhanberg/jekyll-postcss/issues/27#issuecomment-874362958).

### Github Pages

Adding Tailwind to Jekyll requires moving the site off of GitHub Pages as a build engine, because GitHub Pages doesn't let you use more than a few preapproved Jekyll plugins, and `jekyll-postcss` isn't one of them.

This migration will involve writing a `Gemfile` and letting a less restrictive build engine + CDN, like Netlify, build and host the site instead.

_(I mean, you could use a build engine and have it write output to GitHub and use GitHub Pages to host that output, but ... **why**, now that services like Netlify exist?)_

GitHub provides a `github-pages` plugin that can be added to a `Gemfile` to facilitate building sites written for their environment to a different build engine _(it also helps w/ `localhost` development, as )_.  It looks like `github-pages-unscramble` might be handy, too, when the time comes.

## Other notes

For convenience, my sample web site includes some `package.json` commands that let you type less text to kick off Jekyll.

* Instead of running `NODE_ENV=production JEKYLL_ENV=production bundle exec jekyll build` 
* Instead of running `NODE_ENV=development JEKYLL_ENV=development bundle exec jekyll serve` you can run `npm run develop` or `npm run dev`.

## Background (why Tailwind)

When I first encountered utility CSS class libraries like Tailwind, I _hated_ them.  Who on _earth_ would want to take easy-to-read HTML and turn it into such a nightmare?

However, once I got used to it _(so that I could start playing with copy-paste pre-styled page section component libraries like Tailwind UI)_, and once I got used to [sectioning static site generator templates appropriately for page section components](https://www.stackbit.com/docs/knowledge-base/building-with-components), suddenly the idea of styling components anywhere _but_ within the file that the HTML lived in seemed disorganized & annoying.

As verbose as utility classes could be, at least they lived & died with their HTML, and that was comforting somehow.

I could add or remove page elements at will and not worry about breaking things or leaving behind confusing artifacts.

I've recently worked out how to add Algolia search to a Jekyll site, but the navigation bar on that site was a "don't touch code you don't understand" hot mess.  I've worked out a navbar I trust over the last few months in Tailwind, and into which I've successfully put a search widget.  I decided I'd be best off just rearchitecting the whole site's theme to be componentized & to use Tailwind CSS, so that it'd be easy not only to add search, but anything else that might come up in the future.