I’ve been working on rebuilding this site (again!) since the start of the year. I still use Hugo as the static site generator, albeit now I learned a little bit more about Go so I can make better, informed decisions on how to write the proper template for this site.

In this post, I’ll talk about a few things that I learn from simplifying the site from the first version that I built with Hugo. Just a disclaimer my requirement is pretty simple, so I do not use all functionalities that Hugo offers.

No themes, just default layout

I only need a simple design for this site (if you can call it that), so I decided to just set the default template directly in the layouts directory that comes with the default hugo new site command without using the themes folder. Hugo already supported this out of the box for their lookup order so I can completely remove the themes folder from my site structure.

Essentially, my layouts folder looks like this:

layouts/
├── _default/
│   ├── baseof.html
│   ├── list.html
│   └── single.html
├── 404.html
└── index.html

I think that’s the simplest it can get! Some explanation on the files:

  • index.html - contains the base markup for the homepage.
  • 404.html - 404-page markup (obviously!).
  • _default/baseof.htmll - the master layout, the other two templates, list.html, and single.html will extend from this.
  • _default/list.html - I mainly use this to display the blog archive, with one conditional to show a list of tags if you are on the main archive page.
  • _default/single.html - The single post view, also reusable for static pages.

Assets compilation

Since version 0.43, Hugo adds an awesome feature of pipelines that can automatically compile your SCSS files, Javascript, images and so much more for the production build. It’s a very much welcomed feature indeed as now I don’t need to set up a separate gulp task to do this. Processing your SCSS files automatically looks as simple as this now:

1
2

{{ $style := resources.Get "scss/app.scss" | toCSS (dict "targetPath" "css/app.css") | postCSS (dict "use" "autoprefixer") | minify | fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}" integrity="{{ $style.Data.Integrity }}">

This is what I use for this site. In just two lines, I now have

  1. SCSS compilation of my assets/scss directory
  2. Automatic browser auto prefixing with Autoprefixer
  3. Assets minification
  4. File fingerprinting that I can use with SRI

Pretty cool, huh?

Syntax highlighting

Some people prefer to do syntax highlighting on the client-side with the ever-popular library Prism. But given that Hugo already comes with its syntax highlighting library, Chroma, I might as well use that.

First, configure Hugo to output CSS classes for all code output, instead of the inline styles generated by Goldmark renderer. This can be achieved by adding pygmentsUseClasses=true to the site config. Once I did that, I can essentially pick any Chroma compatible CSS classes to be used, and not limiting myself to only what it offers out of the box. I’m a big fan of the base16 color scheme, so I use the one ported by Michael Morehouse. All I need to do is pick the one I like, then include it as a partial for SCSS.

Disable unused taxonomies

Hugo comes with multiple taxonomies to manage your content, but if you do not plan to use all of them, you can just define what you need inside your site config. As for me, I intended to only use tags, so I define it in the site config like this:

1
2

taxonomies:
  tag: tags

Hosting with Netlify

There isn’t much to talk about this one. If you’re using a static site generator and never heard of Netlify, you’re missing out. Their offerings are pretty awesome, CDN, continuous deployment, 1-click HTTPS, admin GUI and so much more. Hugo has extensive documentation on using Netlify so I’ll just link to that.

Sadly, I don’t find any working solution to make Netlify plays nice with Hugo assets pipelines yet, so I am still using the suggested workaround of running hugo command locally and committing the resources folder into Git.

So there you have it, a few tips of customization that I have done with Hugo. I’m pretty happy with the result so far but do let me know if you have any tips and tricks using Hugo.