Setup a multilingual blog or website with Middleman and Tailwind CSS (Part 1)

The first part will focus on the Middleman and Tailwind CSS setup. The other parts discuss multilingual support and the integration of a blog.

Introduction

When I first started setting up this website, I've decided to choose Jekyll. Jekyll is a great static website generator made in Ruby. After a while of coding, I did not "feel at home" and was looking for something even simpler. The main reasons where a complicated multilingual setup, using a complex Gulpfile for the Tailwind CSS integration and I did not like the Liquid template engine. I just wanted to use Ruby and ERB templates.

Switching to Middleman was just a proof-of-concept and soon was the right decision: Easy setup, plain Ruby, built-in i18n support.

First things first: The general setup is based on Donn Felker's great article about a Tailwind CSS and Middleman setup, which helped me a lot.

Setup Middleman

Prerequisites: Ruby, RubyGems and Bundler.

Install Middleman and initialize a new site:

gem install middleman
middleman init

With these commands you should now have a plain Middleman project, which can be executed by:

bundle exec middleman server

By visiting http://localhost:4567 you see the default middleman page. As of writing, there is an open issue in the middleman project which prevents the CSS from being generated. You might see the following error in the console:

DEPRECATION WARNING: autoprefixer-rails was deprecated. Migration guide:
https://github.com/ai/autoprefixer-rails/wiki/Deprecated (called from process at .../autoprefixer-rails-9.8.6.5/lib/autoprefixer-rails/processor.rb:36)
TypeError: Cannot read properties of undefined (reading 'version')

To fix the error, change the version of middleman-autoprefixer in your Gemfile:

Gemfile
gem 'middleman-autoprefixer', '~> 3.0'

and execute the bundler again:

bundle

You are now ready to build your static website with Middleman. Let's use Tailwind CSS for our layout.

Integrate Tailwind CSS into Middleman

Start by initialize a new project, installing and initialize Tailwind CSS:

# init a new project (creates package.json)
npm init
# install tailwindcss
npm install -D tailwindcss
# init tailwindcss
npx tailwindcss init

The configuration is based on the Getting Started Guide of Tailwind CSS. Now you have to tell Tailwind CSS where your source files are located. In Middleman the default directory is './source':

tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './source/**/*.{html,erb}'
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Middleman already created a CSS file, which we can use for our Tailwind directives. Rename the file and replace the content with the Tailwind directives:

mv source/stylesheets/site.css.scss source/stylesheets/site.css

source/stylesheets/site.css
@tailwind base;
@tailwind components;
@tailwind utilities;

If you'd execute Middleman's server the CSS file would not work, because the browser don't know how to handle Tailwind directives. This is where the External Pipeline of Middleman comes in. Add the following lines into your 'config.rb' file:

config.rb
activate :external_pipeline,
         name: :tailwind,
         command: 'npx tailwindcss -i ./source/stylesheets/site.css ' \
                  "-o ./dist/stylesheets/site.css #{'--watch' unless build?}",
         latency: 2,
         source: './dist'

With this configuration Middleman will include CSS produced by Tailwind.

Now you are ready to use Tailwind CSS utility classes in your ERB and HTML files. In the next parts, we will cover the i18n and blog integration. Thanks for reading and if you want to give me feedback, just drop me an email.

---

References

1. HowTo: Setup Tailwind CSS 3 with Middleman. Donn Felker. Retrieved October 2023.