loading...
Cover image for 4 Hugo Beginner Mistakes

4 Hugo Beginner Mistakes

brewinstallbuzzwords profile image Adam Davis Originally published at brewinstallbuzzwords.com ・3 min read

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.

Posted on by:

brewinstallbuzzwords profile

Adam Davis

@brewinstallbuzzwords

full-time software developer, part-time dumb-things-for-the-internet developer

Discussion

pic
Editor guide