If you're using a static site generator with a large selection of pre-made templates, it's probably because you want to build your site quickly. However, as with any technology, Hugo has its own set of quirks that can stop an all-too-eager creator in their tracks.
In this post, I'll be laying out some beginner mistakes to help you flatten that learning curve #flattenthecurve
Inside your Hugo project, your theme will generally be stored in the directory
themes/<theme_name>. As far as I'm aware, there's never a good reason to edit anything in that directory.
The idea is that the files specific to your site should be entirely separate from anything in the
themes directory. You should be able to list
themes in your
.gitignore and redownload the theme as needed. However, this doesn't mean you can't put your personal touch on things.
To override a file in your theme, all you need to do is include a file with the same path relative to the root of your project. For example, you would override a file at
themes/<theme_name>/images/image-1.png with the file
One of the nice things about Hugo is how simple it is to generate your site. Whenever you want to generate your content, you run
hugo in the terminal and your content will be generated in the
public directory. However, what you may not have noticed is that it this only generates new content and overwrites existing content.
This means if you delete some content that was included in a previous build or change a file back to a draft, it will not be automatically cleared from the
public directory. This could lead to publishing content that you did not intend to publish.
To prevent this from happening, you can either use the
--cleanDestinationDir to remove old files from the destination directory. Alternatively, you could delete the directory before building, but adding the build option is easier. For more info, see the Hugo basic usage page here.
When testing out your site locally with the
hugo server command, you may be tempted to mark the draft option to false on whatever post you're working on. However, like the previously listed misstep, this could lead to posting content accidentally.
Instead, add the
-D option. This will include drafts when building the site, allowing you to test out your drafts in context.
To add a new post to your site, there's no need to create a file manually. Instead, use the
hugo new <filename>.md command. This will create the a file in the
/content directory, automatically pre-polutating it with front matter (as defined by the
When learning a technology, you're bound to make some mistakes. If you're getting started with Hugo, the best I can hope for is that this post helps you make one fewer mistake than you would have otherwise.
If you enjoyed this post, consider subscribing to my monthly newsletter.
For more of my posts, check out my blog.