Using Tailwind CSS With Hugo

I moved this blog to Hugo a while ago, which is a static site generator built on golang. Recently, I had to update the server hosting my site, but it was too far behind on updates to run an upgrade to the latest version, so I backed up my site and powered it off and created a new server. Unfortunately, my backup only had the nginx config which pointed to a container running my blog. I did have a backup of the repository which had the site content and theme, but I struggled getting it to build, but resolved it. I modified the appearance “I was using bootstrap”, and got it running locally. But I decided to switch to Tailwind CSS as it seems to be the new cool thing in web development. This also simplified my build process, as I no longer had to install bootstrapcss and gulp in my theme and run the gulpfile during development and during a deploy, it was all handled now by hugo.

What is Tailwind CSS?

Tailwind CSS is a framework for developing modern responsive websites - check it out here, which uses a utility class approach to building interfaces. If you have used a framework like bootstrap before, you will know that it comes out of the box with many base styles which drive the look of the design. Tailwind CSS is completely bare to begin with - kind of like a blank canvas, and styiling is done using utility classes on page elements. Most web developers will have been taught that we should isolate styling from the HTML, but Tailwind CSS does the opposite. But luckily there is also an option to apply these utility classes in the CSS file, so global styles can be applied, which I did for some typography things for my blog, so I don’t have to write styles in my Hugo markdown files.

Setting up your Hugo project to use tailwind CSS

Install instructions for using Tailwind CSS with Hugo can be found at the official site: Hugo Docs

Setting up VSCode

There is an extension for VSCode made by the Tailwind CSS developer which does intellisense, and also syntax checking aswell as shows the applied CSS when you hover over an element. It can be installed here: Editor Setup.

There was some further configuration I had to add to VSCode to allow the extension to show that my CSS file was correct.

Add the below config to your settings.json:

1
2
3
4
5

"tailwindCSS.includeLanguages": {
  "html": "html",
  "javascript": "javascript",
  "css": "css"
}

Your css file should now no longer show errors when using tags such as @apply and @source.

Local development with Docker Compose

To make it easier for teams to develop the site, you can include a compose.yml file which pulls an image to do local development. A project called hugomods has created docker containers with various tags that allow the hugo server to be run in a container. The hugo server watches for changes to the files and automatically recompiles the site when a change is made. In my case, I use the hugomods/hugo:debian-node image. Below is my compose.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

name: johnflynn_me_dev

services:
  hugo:
    image: hugomods/hugo:debian-node
    command: server -D
    volumes:
      - ./site:/src
      - ~/hugo_cache:/tmp/hugo_cache
    ports:
      - 1313:1313

Run docker-compose run hugo npm i to install the Tailwind CSS dependencies with npm and then run docker-compose up to start the container. Now any changes will cause hugo to recompile your site, if changes are made to your CSS file, they will also be recompiled.
In my case the hugo site is in a directory called site, with the compose.yml being in the top directory, so you might have to adjust the volumes array to mount the correct data in the src directory of the container.
Anyway that is it for this post, I will be creating another post detailing how I used the hugomods image with Gitlab to create a CI/CD pipeline which automatically publishes the site when I merge to main in my repository.