MayADevBe Blog

A Blog about Computer Science

How to create a Hugo Theme

Published - 2021-02-18 | 5min

Today I want to talk about how I created the Hugo theme for this website. I will give you an overview of how I went about figuring out how to use Hugo and what sources I found and what features I implemented. I will not go into too much detail about the actual implementation. I explained my motivations for choosing a static site generator, specifically Hugo, in another article. But, before I start with the explanation of creating a theme, I want to give a short introduction to what Hugo is, for everyone, who doesn’t know.

What is Hugo?

Hugo is an open-source static site generator, that claims to be the fastest framework1. It is written in Go. For everyone, who doesn’t want to go too deep into learning Hugo and web development, the Hugo community offers a wide range of themes. Themes are style and website templates. However, it is still possible to override these styles and templates if you want to. Furthermore, it is possible to create your own themes. The content of the pages is written with Markdown files, however, for specific situations, HTML can be used.

Roadmap

First, I want to give you an overview of what I did.

  1. Get an idea of the basics
  2. Check out the available themes
  3. Create a base template (HTML)
  4. Create a base style (CSS)
  5. Add features
    • Pagination
    • Tags
    • Social Media Links
    • Time to read post
    • RSS feed
    • Twitter Card support
  6. Make specific Markdown style

Theme Creation

Now that you have an overview of what I did, I want to go a little more in detail. However, I will not be able to explain everything I did fully. I will give links to further resources, that I used.

0. Prerequirements

If you want to create your own theme, you do need an understanding of HTML and CSS. How deep this understanding is, depends on how advanced the theme/website should be.

1. Basics

The first thing everyone has to do when looking into a new tool is either read the documentation (which most people - me included - probably don’t want to) or find a tutorial. Now everyone has their preferences, I looked for a video tutorial series and found a short and precise YouTube playlist from Mike Dane. This step is just for getting an overall idea of how to set up Hugo, the file structure and generally the possibilities Hugo offers.

2. Existing Themes

When I got the overview of how to work with Hugo, I took a look at the available Hugo community themes. Now, I wanted to actually fully understand everything that was in my theme and also brush up on my HTML and CSS skills, which is why I decided to create my own theme. However, that doesn’t mean I had to start from scratch. I looked at the themes to see what features they implemented and how. Because all the themes are available publicly over GitHub, this step was pretty easy. I found one theme, whose look and implemented features I really liked, so I took it as an example. The theme is called ‘Ezhil’, you can check it out in GitHub2. As of writing this post, my theme is very close to this theme, however, I have some ideas that I might implement in the future, that will set my theme apart from ‘Ezhil’.

3. Basic HTML of the Theme

First thing when creating a Hugo theme or site, is having the correct file structure. This is a really important and Hugo offers a command for this. I used the command to create a website and build my theme with this.

1

hugo new folder_name

There s also a command, specifically for creating a theme:

1

hugo new theme exampleTheme

Hugo created the file structure including all the HTML files, that you have to work with.

  • head.html: Includes the <head> and everything that belongs in it (mainly Metadata)
  • header.html: Includes Website title and a menu
  • footer.html: Includes copyright notice and a menu for imprint and policy
  • index.html: Includes head.html/header.html/footer.html and a list of all the content files
  • list.html: Similar to index.html (except it does not include all the content files)
  • single.html: Includes head.html/header.html/footer.html and the content of the content files

The implementation of this is quite forward if you have seen the tutorial and have a basic understanding of HTML.

4. Basic CSS of the Theme

Creating the style of the pages is quite forward if you already know CSS. I oriented myself on the ‘Ezhil’ theme. However, I wanted to have a specific colour palette, that I use for basically all my tools that allow style customizations. That is the dark mode ‘Gruvbox’ palette 3.

5. Features

  • Pagination Hugo has built-in support for pagination. I again took the ‘Ezhil’ theme as an example. First, when paginating I had to make sure, that only posts, show up (meaning the about.md should not show up) and for the page menu I created a partial.
  • Tags Hugo also supports tags. However, by default, they are not enabled. When the tags are enabled another default layout gets important, which is the terms.html file. This file is similar to the list file, just that you use it to display taxonomies or more specifically in my case tags.
  • Social Media Links For social media links, I used the feather icons 4. the website offers a good explanation on how to include them in any HTML page.
  • Time to read post To show an estimated reading time of the posts, I found a good article on kodify.net. I also used the previously mentioned feather icon.
  • RSS feed Again, including an RSS feed is pretty straight forward, because Hugo includes an RSS template. The previously mentioned feather icon site also comes in handy here.
  • Twitter Card support Twitter card and Open Graph are also supported by Hugo and easy to implement when looking into the documentation.

6. Markdown specific Style

In regard to styling the content of the Markdown files, I found the documentation lacking. I did, however, find a blog post that closed that gap. I used a custom CSS file to also use my previously mentioned colour palette.

Next Steps

The next step for the blog after choosing Hugo and creating a theme is to actually deploy the site. I will have a post up on how to use GitHub Hosting with a Hugo website soon. I also have some other ideas to build upon the theme for the future, like integrating google analytic and comments.

Conclusion

I know the explanations are partly shallow, but I tried to give more of an overview of what I did, that includes the resources I used and how I used them. Most of what I have mentioned is explained very well in the documentation and the other sources I gave. Furthermore, if you want to check out the code, to make a picture for yourself, you can check out my Hugo Theme on GitHub. If you have any further questions, you can send me an email or contact me over Twitter. You can also use the Hugo community forum.

  1. Hugo Website: https://gohugo.io/ ↩︎

  2. Ezil Theme https://github.com/vividvilla/ezhil ↩︎

  3. Gruvbox Palette https://github.com/morhetz/gruvbox#palette ↩︎

  4. Feather Icons https://feathericons.com/ ↩︎


Share on:
Comments:
Related Content:
Integrate Comments in SSG Hugo

I integrated a comment feature into my Static Site Generator blog that was created with Hugo. I used the utterances app that is based on GitHub issues.

Integrate Social Media Share Buttons on your Website

A post about why you should integrate Social Media Buttons in your website and how to do it.