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
1. Editing the theme
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 images/image-1.png.
2. Accidentally publishing deleted files
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.
3. Not using the drafts option
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.
4. Manually creating new content files
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 /archetypes/default.md file).
Conclusion
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.
Further Reading
If you enjoyed this post, consider subscribing to my monthly newsletter.
For more of my posts, check out my blog.
Top comments (0)