In a previous post, I talked about choosing to use Hugo and Netlify.
In this one, I will talk more about how I created a new Hugo blog, pushed the source code to GitHub, and built and deployed on Netlify. I’ll walk through the steps I took to actually set it up a new—in particular, linking to the guides I followed. There were, unfortunately, a few gotchas that tripped me up. Hopefully this post will help someone else get through this more easily.
Setting up a Hugo site
Follow this, but beware the gotcha below: Hugo – Quick Start Guide
Gotcha: Configuring the theme
Not too far into the guide, I got to the part of setting Ananke as the theme and figured I would just immediately use a different theme. After all, it involves cloning submodules, and I didn’t really want to clone something I wasn’t intending to use. Themes should be modular and easy to swap in, right?
That doesn’t look nearly as good as the showcased example. Well, it turns out the instructions are a bit misleading: cloning the submodule and adding
theme = "hyde-hyde" is not all you need to do. In order to get the extra stuff, you need to configure it on your
config.toml. Take a look at the theme’s
exampleSite/config.toml for what to copy in. (Here’s
hyde-hyde/exampleSite/config.toml.) This seems to be an omission in many themes’ documentation, but the
exampleSite also seems to be a standard thing to have.
Note that static files like images go into the
static/ directory, but they are served from the root path, so an image at
/static/img/photo.jpg should be specified as
Setting up on Netlify
First, make a repository on GitHub and set it as the remote for your new site. If you’re not familiar with how to do that, here is GitHub’s documentation.
Then, follow this guide: Hugo – Hosting on Netlify
Once you have it set up, pushing commits to GitHub should trigger Netlify to build your site.
Debugging broken builds
If your new site isn’t working, you might have a failed build. In case you get lost on the Netlify control panel like I did, you can see build statuses and logs by going to “Deploys” in the top navbar. This will show you a list of builds, and you can click on one to see the log.
In particular, I was getting broken builds with the following error:
9:01:44 PM: Error: failed to prune cache "assets": remove 9:06:44 AM: Error: failed to prune cache "assets": remove /opt/build/repo/resources/_gen/assets/scss/scss/hyde-hyde.scss_4fddb88d50abca04f2e7ef77f0bb1c3b.content: no such file or directory
It turns out that something about my theme (hyde-hyde) and the
--gc cleanup after building wasn’t working. I had tried copying the
netlify.toml this blog post and it ended up building successfully.