How to add Tailwind to Hugo

To add Tailwind CSS to a Hugo site you install it with npm inside your theme, let the Tailwind CLI generate a CSS file into the theme’s assets folder, and load that file from your layouts through Hugo’s asset pipeline. Hugo and Tailwind run as two separate processes, and this setup keeps them nicely decoupled.

Install Tailwind in the theme

We work inside the theme folder because that’s where the layouts live, and Tailwind needs to scan them.

Inside your theme folder run

npm init -y

Then install Tailwind CSS as a development dependency:

npm install -D tailwindcss

Initialize Tailwind using:

npx tailwindcss init

This creates the tailwind.config.js file. Open it in your editor, and fill the content property with your theme layout files in this way:

module.exports = {
  content: ['content/**/*.md', 'layouts/**/*.html'],
  theme: {
    extend: {},
  },
  plugins: [],
}

The content paths matter. Tailwind only generates the CSS for classes it actually finds in those files, so the output stays small. We list both the layouts and the markdown content, because you can use Tailwind classes in markdown too.

Create the input CSS file

Now create tailwind.css file in the theme’s folder and add this:

@tailwind base;
@tailwind components;
@tailwind utilities;

Those three directives are placeholders. When Tailwind builds, it replaces them with the reset styles, the component classes, and every utility class your templates use.

Add the build scripts

Now open package.json and in the scripts section add the build and watch commands:

{
  "name": "valley",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "npx tailwindcss -i ./tailwind.css -o ./assets/style.css",
    "watch": "npx tailwindcss -i ./tailwind.css -o ./assets/style.css --watch"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "tailwindcss": "^3.1.4"
  }
}

We output to assets/style.css because Hugo can process files in the assets folder with its resources functions, which we’ll use next.

Try running

npm run build

and you should see the style.css file!

| Tip: use npm run watch when working on the theme, so the changes are saved to the style.css file on every file save.

In practice this means two terminals while you develop: one running hugo server, one running npm run watch. Hugo picks up the regenerated CSS and reloads the browser.

Load the CSS in your layouts

Now we can include it in our layouts, for example I put it in layouts/partials/header.html

{{ $styles := resources.Get "style.css" }}
<link rel="stylesheet" href="{{ $styles.RelPermalink }}">

When a class doesn’t show up

One thing that will bite you: you add a class like mt-8 to a template, and nothing changes. Two usual causes.

Either the watch process isn’t running, so style.css is stale. Or the file you edited isn’t matched by the content globs in tailwind.config.js, so Tailwind never sees the class and never generates it. Add the path to content and run the build again.

Also, don’t build class names dynamically by concatenating strings in your templates. Tailwind scans files as plain text, so a class name that never appears in full won’t make it into the output. Always write the complete class name.