Build a professional tech blog with Hugo

You can build a professional blog quickly with Hugo. Just install Hugo on your machine, create a new site and pick a theme. With Netlify, hosting your Hugo site is easy too. This is because Netlify has native support for Hugo built in.

I’ve built around 5 Hugo sites for clients who were all happy with the results. In this tutorial, I’ll give you a nudge in the right direction. We will install the PaperMod theme and quickly go over some of the things you can do.

If I pick a theme won’t my site be generic? #

Not really. If you know a bit of HTML and CSS you can really customise your site any way you like. The purpose of a theme is to provide good, robust templates for your content.

Step 1: Install Hugo #

To install for your OS check out the installation guide on the official Hugo docs. Go is the language Hugo is built with - you will need to install it from here.

Step 2: Choose a theme #

The great thing about Hugo is that there are tons of open source themes. You have to dig deep a bit but you can find some really nice ones here. When finding a theme you like, make sure it has a high number of GitHub stars (around 200+ is good). This gives an indication that the theme won’t be buggy or that the developers respond well to issues.

I also like to make sure that the theme has good documentation. An example site that uses the theme is also super useful.

Configuration, installation and adding content for each theme is different. I’ll be using PaperMod as it comes with a ton of features out the box and looks really nice. Take a gander at the example site.

You can try to follow the rest of the tutorial with your own theme but keep in mind that some things will be slightly different.

Step 3: Create your website #

Create a hugo site #

Create your hugo site with the following commands:

hugo new site quickstart
cd quickstart
git init

This creates a new folder called quickstart with a bunch of Hugo configs in there.

You’ll notice that I created a git repo. This is important for two reasons:

• We will install our themes using git submodules. This makes the whole process much easier as you don’t have to manually download your themes.

• I use Netlify to host all my websites. Netlify has really good integration with GitHub and Hugo. Whenever you merge to your main branch Netlify can rebuild the site.

🎉 We now have a web site! Too bad it’s just a blank page.

Step 4: Install your theme and content #

Add the PaperMod theme #

Add the theme using git submodules:

git submodule add --depth=1 <https://github.com/adityatelange/hugo-PaperMod.git> themes/PaperMod

Remember to change this line if you aren’t using PaperMod.

In the root of your website is a file called hugo.toml. Delete it and create a new file called config.yml. Then paste in the code from this sample configuration.

Step 5: Get to grips with the config.yml #

Start your website #

With your terminal pointed at your websites root directory run:

hugo server

Your website will now be running locally. Go onto your website and explore. Mess around with the parameters in your config.yml to see which parameters do what. They are pretty self explanatory for the most part.

Config files #

All Hugo themes make use of a config file (either called hugo.toml or config.yml). Adjusting the parameters in these files adjusts how your website is rendered. Config files are used for a number of things such as:

• Setting up menus
• Changing the title of your homepage
• Setting your websites default theme (e.g. dark or light)
• Setting up Google Analytics
• Parameters for technical SEO

To be honest, what config files can do is up to the author of the theme you are using.While different themes have different parameters, a well built theme will have parameters that are easy to read and interpret.

Example: Changing your sites title #

Replace the following lines in config.yml:

params:
  env: production # to enable google analytics, opengraph, twitter-cards and schema.
  title: ExampleSite
  description: "ExampleSite description"

with

params:
  env: production # to enable google analytics, opengraph, twitter-cards and schema.
  title: My Tech Blog
  description: "It's my tech blog!"

Take a nice hard look at how the content of your homepage has been altered! Well built themes like PaperMod have configuration files that let you easily edit and customise your content.

Step 6: Adding and configuring posts #

Content such as posts are generally .md (markdown) files that live in your websites content folder. If you look at the example site for Paper Mod, you will see they have the following structure:

content / posts / post.md

Okay, your content folder should be empty. Add a new folder in there called posts. Then create a new file called sample.md in posts. Paste the following content in sample.md:

---
title: "My 1st post"
date: 2020-09-15T11:30:03+00:00
---

This is my first post

Take a look at your websites homepage. You should see that there’s a new post there.

Everything in between the --- are parameters for your post. Change the title to "My first post" by writing title: "My first post". Take a look at your homepage - the title of your first blog post has changed. Different themes have different parameters you can set for each post.

Underneath the parameters (so underneath the 2nd line of ---) is the content for your post. This is where you write all your prose. Click on your first blog post and see how your post just says This is my first post.

Use markdown to format your post #

The powerful thing about Hugo is that you can use markdown to efficiently format your posts. For example, change sample.md to include the following content:

---
title: "My 1st post"
date: 2020-09-15T11:30:03+00:00
---

This is my first post

## This is a H2 tag

Wow that's amazing. I can also make a list:
- wow
- this
- is
- cool!

Markdown is great. What else can I do? `I can make a code snippet!`.

Take a look at your first post now. Cool right?

Learn from the example site #

A good Hugo theme always ships with an example site. The example site acts as a piece of documentation. It showcases every feature of the theme you are using and in order to learn how to implement those features you just need to dig through the code and file structure. For example, I learned how to add posts to Paper Mod by copying their file structure for content.

This is just the beginning #

All Hugo themes are similar in their set up and execution. Once you learn how to install one you will be comfortable installing others. It’s a case of installing the theme, changing a few lines in the config and creating markdown files in the content folder. There are so many great themes out there for Hugo that you can literally create a great looking site within minutes!