Why HUGO?

A few months back now, I started a blog - Dipped my toe into the water so to speak - To experiment with what was out there. As an avid reader of a few technology blogs, I feel like I have a few things to share myself so kicked off something with Wordpress.

It was everything I had hoped running a blog wouldn’t be.

Sure, with time, I could have perfected the process, but not having oodles of time nor even the certainty anyone would ever read anything I wrote, it felt like a huge time sink. Many of the things that can make your life easier are locked behind paid plugins.

And then there are the updates…

I will, at somepoint, write a post on why I have tentatively chosen HUGO (if it works out of course!) but here we are, I’m writing my own theme and I want tailwind.

What is Tailwind

If you somehow stumbled across this, I am hazarding a guess you already know what tailwind is, but a small precursor for the uninitiated, its a “utility first framework” which allows you to write CSS faster.

CSS isn’t all that hard, but unless you’re a designer, it’s also not the easiest thing to maintain a sound design language across a site which can contain thousands of elements.

As an example, if you wanted to write give a div some padding, you may write something like this in CSS:

1
2
3

.my-div {
    margin: 8px;
}

In tailwind, you could keep it all inline:

1

<div id="my-div" class="p-8">My div</div>

Downloading Tailwind

Fortunately, in the not so distant past, Tailwind came out with a standalone executable version to avoid needing to install via NPM.

So let us first grab the executable, by running the following from the root of your project:

1
2
3
4

# Note this example assumes OSX, you can find a version for your OS here:
curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-macos-arm64
chmod +x tailwindcss-macos-arm64
mv tailwindcss-macos-arm64 tailwindcss

This should give you an executable within your project folder named tailwindcss. You can now run this using:

./tailwindcss

But this won’t do a whole lot yet!

There are two ways we can use this, element specific, for example in a post or on a page, or in a theme.

Running Tailwind

We’re almost there, but the way tailwind works, it takes two paramters to run:

• An input file
• An output file

To get tailwind working, we first need an input file.

Go to the static directory in your HUGO project and add a new folder within there called styles.

Within this new folder you shold then place two files; input.css and output.css.

input.css should contain the following:

@import "tailwindcss"

output.css should be left empty.

You can now run the tailwind executable we downloaded with the following command:

1
2

# Update input and output directories/files as necessary
./tailwindcss -i ./static/styles/input.css -o ./static/styles/output.css --watch

What does this actually do though?

./tailwindcss tells the computer to run the tailwindcss executable

-i is the flag to specify the input file

-o is the flag to specify the output file

–watch tells the executable to remain open (you’ll need to keep a terminal window active) and watching for changes

As you modify files in your project, tailwind will update the output.css file to reflect the latest changes and import only the necessary classes needed.

Don’t forget to import the output.css file into the header file of any pages you need it on, likely you can just do this in the baseof.html file.

Get Tailwind themed elements displaying your site

Modifying a plain HTML page

HTML pages are the easiest to get started with. You can use the tailwind guide as a reference, but let us assume for a second you wish center the content in the center of the screen in a column like view.

In baseof.html replace

1
2

{{ block "main" . }}
{{ end }}

with

1
2
3
4

<div class="container mx-auto p-4 max-w-xl">
    {{ block "main" . }}
    {{ end }}
</div>

You should now see your content has centered into a column into the middle of the page.

Modifying a markdown file - Not working

I have spent hours - multiple hours - trying to add classes to markdown. It would appear that at somepoint HUGO switched to Goldmark as a markdown processor and with that I think inline CSS classes went.

If anyone is able to advise to the contrary, I’d love to know, but despite a plethora of posts for 2019 claiming is is possible, I cannot for the life of me get it to work.

The idea, for clarity, would be take a paragraph in markdown, have the ability to append class names to that paragraph to style it like so:

1Hello world{.text-bold}

Render Hooks

Render hooks do work, and they seem to be the best way to take a lot of control when it comes to customising your site.

Since I’m just getting started with HUGO, and am in no position to articulate how all this fits together. I’m going to go ahead and shoutout this tutorial by bit-101 which helped me get setup with a theme.

When you write your pages in markdown, HUGO passes your markdown through a parser which is then translated into HTML.

Lets take the Block Quote render hook. By default when rendering a block quote, HUGO will output something like this:

1
2
3

<blockquote>
  Your quote goes here!
</blockquote>

Which, with tailwind installed will just render as plain text.

Lets say we want to customise that a little.

Assuming you have followed the linked tutorial above, in your themes/themename/layouts directory, create a folder called _default and then within that, a folder named _markup.

Your directory should now look something like this:

themes
|- themename
|   |- layouts
|   |   |- _default
|   |   |   |- _markup

Within the _markup folder, create a file called render-blockquote.html

What ever you paste in here will be rendered by default whenever HUGO converts a blockquote from markdown to HTML.

Lets add some Tailwind magic:

1
2
3

<div class="text-2xl font-extralight border-l-8 pl-4 border-gray-200 italic">
    {{ .Text }}
</div>

Your block quotes will now stand out in a much nicer format. Feel free to play around with Tailwind to get a look and feel that works for your site.

Conclusion

I have been thoroughly enjoying building this little site out. As I come to learn more I’ll revisit this page and add some extras, but for the most part, it has been very straight forwards!

If you’re thinking of starting a blog with a dead easy file based CMS, but want a little extra control on the output, I can highly recommend this setup.