Simple TailwindCSS PostCSS Setup for Hugo site

View complete source code on github

Before adding tailwindcss I would recommend to develop hugo website inside development docker container.

So we no longer have the issue of "this works on my computer". And it will not mess with your existing workflow.

So checkout my blog post for detailed video explanation.

This project is inspired from hugo-tailwind-basic template created by Bjørn Erik Pedersen who is creator and maintainer of hugo.

So lets get started with brand new hugo project.

hugo new site hugo-tailwindcss

First thing I like to add .gitignore file because we will be adding npm packages and I like to ignore node_modules folder along with other generated files.

You can generate gitignore file with gitignore.io based on your operating system and other packages in your project.

The initialize git repo with git init

Change config.toml to config.yml. I prefer yaml over toml. But you can keep default toml if you want.

Then add following config.

1
2
3
4
5
6
7

  <!-- prettier-ignore -->
  baseURL: "http://example.org/"
  languageCode: "en-us"
  title: "My New Hugo Site"
  build:
    writeStats: true
  

I have just replaced = with : to convert toml to yaml format.

And set write stat to true. This will generate hugo_stats.json file. Make sure you have this in your gitignore.

Now create package.json file by running command npm init -y

Then install following packages.

npm i -D @tailwindcss/typography autoprefixer postcss postcss-cli postcss-purgecss tailwindcss

Tailwindcss is postcss plugin so we need to install both. And we are using typography plugin for tailwind.

Autoprefixer will add browser specific prefixes. Purge css will remove all unused css.

Make sure to add all of them as dev dependencies. We don't need to add any of these packages injected in final production code.

Now create all config files withnpx tailwindcss init -p

This will create tailwind.config.js and postcss.config.js

Postcss config is all set but we need to modify the tailwind config as follows

We are basically purging unused css using hugo_stats.json. Purgecss options are natively integrated inside tailwindcss config.

If you are manipulating tailwind css classes using javascript then you may want to add path to where you have stored javascript files e.g."./assets/**/*.js"

For more information about all available purgecss options checkout official purgecss documentation. For example I am removing unused keyframes from the final version.

And adding typography plugin for tailwind config.

Now we are going add tailwind css in global css file. So create css file as follows

mkdir -p assets/css
touch assets/css/styles.css

Then add following 3 lines in styles.css

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

In styles.css file you can also add your custom css that you want.

Then create base html files with following command

mkdir layouts/_default
touch layouts/_default/baseof.html layouts/index.html content/_index.html

Add following code in baseof.html

This is very standard html file. The important portion is inside style tags.

I take the styles.css file from assets folder. Pass it through postcss and minify the output and add inside head of html file.

You could optionally create output css file and add path to output file.

Then setup homepage with index.html as follows

Here I have added the typography plugin classes.

Now this is enough for most people. But if you are like me. Then you want to add more custom classes for every page.

So for homepage content I have created _index.html instead of commonly used _index.md

Basically all of my articles I actually prefer to write in HTML over Markdown.

Markdown has started supporting classes for heading and list type. But its very new and limited to couple components.

So I wouldn't write the content in markdown. And here is my content for homepage.

The typography plugin prose class has lots of good defaults for most html tags. You cannot override them by adding class to code above.

You will have to modify the tailwind.config.js to override typography defaults. After that you feel free to add any tailwind class you want.

You have now successfully added tailwindcss to hugo. Just run hugo server from root of your project and open localhost:1313 to see the page.

The tutorial is not over yet. I have 3 bonuses for you.

Bonus 1: Tailwind CSS IntelliSense

If you are using VS Code as your editor then you can use the tailwindcss vscode plugin to autocomplete writing of classes.

At the time of writing this article the plugin is in preview mode. But in my experience it does works well out of the box.

But just installing plugin won't start autocomplete feature. You need to create folder at root of your project with name .vscode if it doesn't exist already.

Then add settings.json inside the folder again if the file doesn't exist already.

Then add following code in that file

{
"editor.quickSuggestions": { "strings": true },
"tailwindCSS.emmetCompletions": true
}

Now close and open vscode project. And autocomplete should start working.

If it doesn't work right away then just start coding. And within few minutes it will start working.

Bonus 2: Sorting Tailwindcss classes with Headwind

Depending on component you may have to add lots of tailwind classes to a html tag.

When its time to update the design then you will spend lot of time finding particular class from long list of classes.

The solution is always write classes in specific order so you can find them easy next time.

Headwind plugin allows you to sort classes automatically. They have their own logic for sorting classes.

If you want to add your own logic for sorting classes then you can customize sorting with regular expression.

If you are new to regular expression then I have crash course on regular expression that will get you started.

Bonus 3: Code formatting with prettier

Again the long list of tailwind classes makes it painful to break line into multiple lines every time.

Only reason I started using prettier because it automatically breaks lines after certain character count.

Let me be clear I do not like most of the opinionated rules set by prettier but I tolerate them because it automatically breaks the lines.

So first you need to install prettier packages as follows

npm i -D prettier prettier-plugin-go-template

Again you are not injecting any of these packages in production version so add them as dev dependencies.

Just like prettier the go template plugin is godsend and a curse.

It really helps to override prettier highly opinionated code formatter from leaving hugo double brackets {{ }} alone.

And it doest help with syntax highlighter. So every code will have prettier ignore comment like in this blog post.

I have made issue with go template plugin. Let's hope they solve it soon.

In the mean time you can always host your code on github gist that will continue to host your code even when the blog post is deleted.

Then create .prettierrc.json file at root of your project to configure prettier. And add following code.

I have bigger 4K monitor so I break lines after 120 characters. But if you have small screen then default value 80 is sufficient for you. You don't need to override it.

Then you need to add go template so it will leave hugo code alone.

You can see all available prettier options to modify for your needs.

Then you also need to add .prettierignore file at root of your project. And copy everything from .gitignore into this file so it will not format files that are not committed in git repo.

Then you need to let your editor know about prettier. So for vscode add the following inside settings.json

{
"editor.defaultFormatter": "esbenp.prettier-vscode",
"[javascript, html, json]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"editor.formatOnSave": true
}

And reopen VSCode and your code will be formatter when you save the files.

View complete source code on github

Conclusion

If you are sold on tailwind then its easy to add on hugo project. You should definitely start using it.

And make use of other vscode plugins to make workflow much easier.