How to add Tailwind CSS 3 to a Hugo website in 2022?

I use Hugo for my personal website - https://www.unsungnovelty.org. At present I use Bulma CSS for it. But I am working on a redesign with Tailwind CSS. During my search, I found articles on how to add Tailwind CSS to Hugo confusing. And at times bloated. So here is an attempt to tell you how to add Tailwind CSS to Hugo in the most minimal way. The goal is a simple and straight forward setup for Tailwind CSS in your Hugo website.

Also, this blog post is possible thanks to Integrating TailwindCSS with Hugo by oomusou. It uses prettier and a couple of other things. I have already included that post in the references / link section. But it was the only article I could find on adding Tailwind CSS 3 to Hugo. So thanks oomusou. My post sticks to being a lil detailed and uses just the tailwindcss package from NPM. If you rather use that article. Please do. :)

If you already have a Hugo website and just want to add Tailwind CSS to it’s theme, jump directly to follow How to add Tailwind CSS to a Hugo theme? Else, follow along!

How to create a minimal Hugo website & add Tailwind CSS to it’s Hugo theme?

• Install the Hugo package on your operating system. Follow the Install section from getting started from gohugo.io. If you are on Windows, the below commands might not work in full. Use a unix shell like bash to make them work.

• Create a new Hugo website using the command hugo new site <site name> in your terminal. Eg; hugo new site thisSiteIsNew. This will create a new hugo site with a startup template inside the directory called thisSiteIsNew.

• Go inside your new site’s directory. Eg; cd thisSiteIsNew.

• Create a new theme using the hugo new theme <theme name>. Eg; hugo new theme thisThemeIsNew. This will create a new directory with the <theme name> and necessary files needed to get started. In my case, it will be inside thisSiteIsNew/themes/thisThemeIsNew.

• Link the Hugo theme to your Hugo website in your config file. Linking this way tells Hugo to look for the so called theme inside /themes/ directory. Website won’t show up if you don’t link it like this. An example config file will look like the below. This uses .toml format with the file name being config.toml. If you want to use .json or .yaml for your Hugo config file, you can. Just format it accordingly.

baseURL = ''
languageCode = 'en-us'
title = 'thisSiteIsNew'
theme = 'thisThemeIsNew'

How to add Tailwind CSS to a Hugo theme?

• Go inside the themes directory. It is in hugo-website-directory/themes/theme-name/. This assumes you have a hugo website with layouts, config file etc setup. Other prerequisites are npm and node installed in your computer.

• Reminder - Link the Hugo theme to your Hugo website in your config file. Linking this way tells Hugo to look for the so called theme inside /themes/ directory. Website won’t show up if you don’t link it like this. An example config file will look like the below. This uses .toml format with the file name being config.toml. If you want to use .json or .yaml for your Hugo config file, you can. Just format it accordingly.

baseURL = ''
languageCode = 'en-us'
title = 'thisSiteIsNew'
theme = 'thisThemeIsNew'

• Initialise package.json using npm init -y. This will create a package.json file inside your theme directory.
• Install Tailwind CSS using npm install --save-dev tailwindcss. This installs Tailwind CSS as a development dependency.
• Initialise tailwind.config.js by running the command npx tailwindcss init. This will create a tailwind.config.js file.
• Inside tailwind.config.js file, add the below code:

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

• Create a file called main.css in /assets directory. You can use any other name instead of main.css. Also, If this is a new theme, /assets directory won’t be present and you should create it. mkdir assets command in Linux will create a new directory from your terminal.
• Add the below code to main.css file.

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

• Create a style.css inside the /assets folder. We will use the Tailwind CSS CLI to transpile the stuff needed from main.css to style.css. style.css will be our final css file used to style our website.
• Add some Tailwind CSS utilities to your html files. I have the below index.html which is the home page of a hugo website.

{{ define "main" }}

    <h1 class="text-3xl text-blue-700 font-bold underline">thisSiteIsNew</h1>
    <p class="bg-sky-600 text-slate-100">The thisSiteIsNew uses a theme called thisThemeIsNew</p>
    
{{ end }}

• Link your style.css to your website by linking the stylesheet in the /layouts/partials/head.html. An example head.html looks like the below:

<head>
    
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Hello Hugo</title>
    <!-- resources.Get "style.css" will fetch the style.css file. 
    It will not work if you mention the exact location like "./assets/style.css".-->
    {{ $style := resources.Get "style.css" }}    
    <link rel="stylesheet" href="{{ $style.Permalink }}"> 

</head>

• Add the below script/command to package.json file. This is needed to build the style.css from your main.css based on the utility classes you added in the previous step.

"scripts": {
  "build-tw": "npx tailwindcss -i ./assets/main.css -o ./assets/style.css",
  "watch-tw": "npx tailwindcss -i ./assets/main.css -o ./assets/style.css -w --minify"
},

You can use any name instead of build-tw and watch-tw here. I just use build-tw and watch-tw because it easily translates to build tailwind or watch tailwind.

• Everytime you make changes to your styling using tailwind utilities, you can run npm run build-tw. This will create a new style.css file.

• Or instead of npm run build-tw, you can use npm run watch-tw which is hot reloads any changes and builds CSS. Very useful when you are making constant changes.

• Now go back to the Hugo site’s directory from /themes/thisThemeIsNew.

• And from inside /thisSiteIsNew run hugo server --disableFastRender in your terminal. It will start a live server in http://localhost:1313/ by default. Otherwise you will have the address in the terminal. That is it. If you have followed all the steps, you should have a Hugo website with the below output.

Final output if you have followed the article step by step.

References / links

• https://functional.style/hugo/general/tailwind/

Found an error? Know a better way to do this? Have feedback on my writing? DM me on Twitter @unsungNovelty or drop a mail to unsungnovelty at protonmail dot com.