DEV Community


Posted on

Build your own blog with Hugo and Netlify

This post was originally published on my blog, find original post here.

This post might feel a little redundant as it's being published on - already a blogging platform so you might ask yourselves: why bother with my own blog? I think there are some advantages to having your own personal blog alongside the one on - it helps your name recognition, it's easier for potential employers to find your articles and you have your posts backed up.

When I decided to start my own blog, I started looking at static site generators because I haven't done anything with them since I created a Jekyll site few years back. I found a few and after a played with them a little, I decided to go with Hugo.

Hugo is a fantastic static site generator and if you're looking to move away from Jekyll, Hugo is an excelent choice. I'd say that the initial setup is much easier than Jekyll's and I'm nicely surprised how quick I was able to put this site together plus Hugo's blazing fast thanks to the fact it's built in in Go.

I tried Gatsby as well and maybe I chose the wrong theme to start with but both Jekyll and Gatbsy came short when it came to Hugo. I was not fan of all dependencies I needed for Jekyll and the plugin system in Gatsby (not saying Gatsby's bad - I like it a lot and I like the fact it goes with React but for my purpose I liked Hugo better)

The theme on I chose is hugo-paper and I will show you how I set this up and host on Netlify.

Install hugo and create new project

Installing Hugo is as simple as this (for MacOS users, otherwise look up Hugo website for more instructions)

brew install hugo
Enter fullscreen mode Exit fullscreen mode

After installing Hugo, simply run an another command which creates a new folder and adds project biolerplate.

hugo new site <siteName>
Enter fullscreen mode Exit fullscreen mode

Install a theme

The next step is to initialize git and install the theme you want to use. There is an extensive list of themes for you to use. As mentioned above I am using hugo-paper (github repo) which you can install like this:

cd <siteName>
git init
cd themes
git submodule add 
Enter fullscreen mode Exit fullscreen mode

All that's left now is to add the theme name to config.toml file and create new content which you can do by adding .md files to content/posts folder and run hugo serve from root directory to serve it locally.

Deploy with netlify

I am a huge fan of Netlify so I will recommend you to deploy your newly made website there. They offer continuous delivery with Github so every time you push your changes to Github, the website is rebuild and deployed and you don't need to do anything.

Easiest way to set up the commands is with netlify.toml file, simply create the file at the root.

publish = "public"
command = "hugo --minify"

HUGO_ENV = "production"

command = "hugo --enableGitInfo"

HUGO_ENV = "production"

command = "hugo --buildFuture -b $DEPLOY_PRIME_URL"


command = "hugo -b $DEPLOY_PRIME_URL"


Enter fullscreen mode Exit fullscreen mode

On Netlify website, choose option to create New site from Git , choose your project and deploy. In theory, it should be as easy as that ๐Ÿ™Œ

Possible roadblocks

Submodules error during the build

Ehm, if you didn't followed this tutorial or tutorial on offical Hugo website and you used git clone for your theme instead of git submodule add you might encounter a failed deploy. This is an easy fix, add your theme to your project with submodules, not cloning (check the process above).

Editing theme

I have seen few articles about Hugo saying you can't edit the theme you added. It's because of the way submodules work, you reference the original theme from the original repo. I've seen suggestions that you fork the theme, edit it and then reference it, however, there are some disadvantages to this approach. I would say the biggest one is that you won't get a newer versions of the theme, which, in theory is not that big of a deal but still. There might be some useful updates that you will miss out if you fork the repo.

There is a neater way, I believe, as Hugo can support several themes at once. You can edit them in config.toml file,

theme = ["hugo-paper-edited", "hugo-paper"]
Enter fullscreen mode Exit fullscreen mode

There is a theme inheritance algorithm that looks at the array above and create a new theme with theme on the left being loaded first and being the most important and merging the themes on the right into it. Hence, I copied the files I wanted to amend into a new folder called hugo-paper-amended and made all the changes to the theme there. The rest of the theme is then loaded from hugo-paper theme.

Styles didn't load

You might get an error in the console saying that website wasn't served though secure https. That might be to a possible wrong baseURL value set in config.toml. If deployed already, Netlify supports https, so add your URL to the config and that will solve the problem!

further reading

Discussion (10)

effingkay profile image
Klaudia Author

To be honest, I don't know if Hugo really is better than Jekyll, it's just my personal preference. Plus, this post was not about Hugo vs Jekyll, I wanted to write down tutorial how to set up Hugo ;)

And by initial setup, I meant that to install Jekyll, you need to install Ruby, bundler, jekyll, last time I tried it my laptop just refused to cooperate and it was such a pain to get to the point where I could even create a jekyll project locally. That may have affected my opinion a little ;) Whereas with Hugo, I ran one command and I was ready.

By no means I think Jekyll's bad. I used it for a long time and never had any issues, I just wanted to try something new and I really enjoyed Hugo, that's all :)

bgadrian profile image
Adrian B.G.

Github pages is agnostic, but their UI can setup a default Jekyll for you that is true, making it easier than the Hugo setup. But if you need extra customization you probably have to do the Jekyll setup local too, which is a bit more complicated than Hugos I think.

notriddle profile image
Michael "notriddle" Howell

Hey, if you add a canonical_url: to your front matter, it'll make sure search engines return your own post instead of the mirror, and put a nice originally-at thing higher up in the UI than where you put it.

teej profile image
TJ Fogarty

Great post. I just moved from Craft to Hugo over the weekend and I absolutely lav it. I agree with you about Jekyll, I used to hit errors every so often and it put me off maintaining my site. Could just be me, I'm prone to errors.

effingkay profile image
Klaudia Author

I agree with you - I think it's just matter of preference. There's so many good static site generators now thanks to the raising popularity of JAM stack that it all comes down to what you like and prefer.

aborruso profile image
Andrea Borruso

I have added my theme as submodule but I have:

"Error checking out submodules: Submodule 'themes/albopop' ( registered for path 'themes/albopop'
Cloning into '/opt/build/repo/themes/albopop'...
Host key verification failed.

fatal: Could not read from remote repository."

netlify has full permission in my organization

I have no idea on how to solve it. Some tips??
The source repo is

Thank you

aksh1618 profile image
Aakarshit Uppal

You need to have https link in .gitmodules instead of ssh link

qasim_57 profile image

I wonder if it's easy (or trivial) to migrate from HugoJS to GatsbyJS.

Would I be able to reuse the same yaml frontmatter to generate content?