Building This Site With Hugo and Tailwind CSS

If you read the portfolio section on the home page, you would have learned that this site is built using Hugo and Tailwind CSS. Let me explain how this was done and why I chose to do it this way.

Background

I used to do web development a couple of years ago but haven’t really touched it since then. So coming back and seeing all the new frameworks people were using was a bit of a shock. It seems like the popular web frameworks change every few years. A a lot of effort is required to even keep up with the trends. Though my last web dev experience was with Flask and Bootstrap, I decided to go with something new this time.

Hugo

Hugo is what’s known as a Static Site Generator. This basically means that it takes files (in this case template files) and uses them to build static HTML pages. The files are served directly to the user as-is, with no client-side rendering required. In contrast, popular JavaScript frameworks such as React commonly generate some or all of their websites using client-side rendering, requiring the user to run JavaScript on their browsers.

Why a Static Site Generator?

I am heavily opposed to using JavaScript willy-nilly. Take Reddit for example. Go to reddit.com and open the developer console. See how many scripts it downloads and how freaking LONG the site takes to load. Now compare that to old.reddit.com. Isn’t it so much faster and lighter? All the Reddit site has to do is load a simple text-based forum with images and videos. It shouldn’t require so much crappy JavaScript to run.

Since my site only contains a simple portfolio and text-based blog, there is no reason to use JavaScript. In fact, this entire site runs without JavaScript. You heard that right. A site in 2020 that does not use JavaScript. Not having JavaScript also confers the added benefit of faster load times (the browser doesn’t need to download any scripts or run any code).

Tailwind CSS

For styling, I used a new framework called Tailwind CSS. Tailwind is an atomic CSS framework. This means that instead of doing this:

<div class="my-div">Hello, World</div>
<style>
.my-div {
    display: flex;
    color: #f56565;
    padding: 4rem; 
}
</style>

I can simply do this:

<div class="flex text-red-500 p-4">Hello, World</div>

Once you get past the added clutter in your HTML files, Tailwind CSS is just so much better than other CSS frameworks like Bootstrap. Having the styling together with the HTML makes designing sites so much easier. Honestly after my experiences with Tailwind I may never go back to a non-atomic CSS framework. It is simply that good.

Building the Site

Since I was new to these technologies, I needed some help getting off the ground. Luckily I found an excellent boilerplate project for Hugo and Tailwind CSS by Dirk Olbrich which I used to quickly get everything running.

Theming

Personally, I’m tired of seeing all the cluttered and overly-colorful sites on the internet. I wanted something clean and simple for my site. So I designed this site to be mostly a plain white color, like words printed on a physical sheet of paper. Colors are only used to make certain portions stand out or to indicate interactivity (e.g. links). Everything else is nice and clean and easy to read.

Templating

As someone who has only used Handlebars and Jinja2, the templating system in Hugo was a bit difficult to get used to at first. I was extremely confused by the large usage of the . prefix in Hugo templates, e.g. .Site.Params, .Date, or even just a single naked .

Only after I got used to scopes and variables in Hugo did I actually understand how to use the period to access stuff. Before I got the hang of it I was just throwing different variables at Hugo until I found the one that works.

Honestly I find Hugo’s templating system quite different from anything else I’ve looked at. It would definitely take some getting used to for most people.

Portfolio

This is supposed to be the main part of the site. It should appear directly on the homepage and act as a resume for me. Coming up with the actual design wasn’t easy though. I looked through countless other portfolio sites by different people before coming up with my own layout and design.

Blog

Building the blog was probably the easiest part. Hugo already has built-in support for blogs. All I had to do was customize the styling to suit the rest of the site.

Issues

I ran into a some issues over the course of developing this site (pretty much all being my fault). Here are some of the bigger ones:

Template Comments

After adding the AGPL license headers into every file, the site stopped rendering and only displayed a white page. It took me quite a while to figure out the issue, and it turned out to be a problem with comments in templates. I was using HTML comments to insert the license headers:

<!-- LICENSE header goes here -->

Turns out that was not how I was supposed to do it. Instead, I should’ve used Go template comments:

{{/* LICENSE header goes here */}}

Whoops!

SVGs

I like use SVGs as indicative icons on my site, especially in the skill tags shown on the homepage. In fact, all icons you see on my site are SVGs. However, I ran into a big issue when using SVGs with Hugo.

There are multiple methods of inserting SVGs into HTML, and I chose to insert them directly into the HTML as SVG tags:

<div>
    <svg>SVG goes here</svg>
</div>

To accomplish this, I used Hugo’s readFile function to read the contents of the SVG file and exported it directly into the HTML source by piping it through safeHTML:

{{ readFile (print "/assets/icons/" .svg ".svg") | safeHTML }}

However, it appears that the hot reload script in the Hugo dev server does not detect changes in the SVG files if I use this method. So whenever I changed an SVG file, the site would not update. I had to manually restart the Hugo dev server to get it to update, which proved to be a huge pain when I was actively modifying the SVGs.

As it turned out, the solution was to extract the SVG reading functionality into a separate Hugo shortcode. Doing that seemingly fixed the issue and hot reload started working for SVGs. The shortcode also made it more convenient to update the SVG paths while adhering to DRY.

Conclusion

Would I recommend Hugo and Tailwind CSS? Yes, absolutely. Other than some initial teething issues, they have been a joy to use and are very easy once you get the hang of it. Static sites are amazing and everybody should try building some too.