Most common Hugo pitfalls and their solutions

#1 Line endings CRLF vs. LF

Theres a difference in how line endings are encoded. If you use VS Code and git, take care that line endings are handled the right way.

In order to get it right in order work with hugo, I needed to do two things:

Change VS Code setting in the lower right corner from CRLF to LF
Check git handling. If you’re on Windows, there might appear the issue of git converting your “correct” LF line endings to CRLF which can cause problems with hugo. The whole issue is discussed on stack overflow. Simply check

git config core.autocrlf

If it is not set to false, simply override git’s setting.

git config --global core.autocrlf input

This will push the exact same line endings to your repo as used in your editor.

#2 Do not edit theme files!

When you customize your theme always work in your hugo repo folder. The logic is quite simple. If you want to overwrite something of your theme, create a copy of the file with the same directory path. It’s best explained in the Hugo theme customization guide. Let’s say I wanted to change the footer file of this theme and remove some parts. The original footer partial is stored in

georocks/themes/even/layouts/partials/footer.html

In order to make some changes one would just copy the file to

georocks/layouts/partials/footer.html

and change everything in here. Hugo automatically detects the changes and forgets about the theme’s original partial. If nonetheless you edit the theme files and think it’s working, yes it does. Only it will cause problems when uploading to github and deploying with netlify.

A well meant advice also to myself: if something doesn’t work, read the docs first. 👓