Debugging Your Hugo Web Site[1]

HIDDEN[1]

 

If there is a problem with a Hugo site that you are developing, here are some things you can try.

  • Use Ctrl-C to stop the Hugo server and then restart it.

  • In your web browser, do a “hard reload” or “hard refresh.” How to do this in many web browsers is in en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache.

  • Run hugo and hugo server with flags such as:

    • --debug

    • --disableFastRender

    • --gc  (“garbage collector”)

    • --ignoreCache

    • --path-warnings

    • --log

    • -v  (equivalent to --verbose)

    • --verboseLog

    For information about these and other flags, see Infinite Ink’s Hugo CLI page.

  • Check that the port number in your web browser (http://localhost:port) is correct. If you have multiple Hugo servers running, you may need to look at http://localhost:1314. This can happen when you are using multiple terminals.

  • View your site with a different web browser.

  • Explicitly specify a different port, e.g. hugo server -D -p 51000.[2]

  • Put debug code in layout files.

  • Delete the Hugo server cache. To find its location, run hugo config | more and look for the value of cachedir.

  • Delete the resources/ directory that hugo generates. An example resources/ directory is discussed in Step 5.3 in Infinite Ink’s TGIH: Themeless & Gitless Introduction to Hugo.

  • In your config file(s) and front matter, make sure that any value that you intend to be a string is not being interpreted as a number, and vice versa. You can force a number to be interpreted as a string by using quotes, for example dateFormat: "2006".

  • If you use TOML in configuration files, front matter, or data files, make sure all TOML tables are at the end. Information about this is in the Now we get crazy section of Nate Finch's Intro to TOML.

  • If you use Mmark[3] includes, changes in an included file are not noticed by LiveReload. Instead you need to stop and restart the hugo server to view Mmark-include-file changes.

  • If you have a problem viewing emoji, smart quotation marks (such as ), mathematical symbols (such as ℵ), or any non-ASCII character, make sure your web server’s HTTP configuration and your Hugo source and destination files are all using UTF-8 encoding. UTF-8 is the standard file encoding for the web nowadays.

 

See also

Infinite Ink’s #gohugo is a portal to the Hugo world.


1. An earlier version of this article was in Infinite Ink’s TGIH: Themeless & Gitless Introduction to Hugo in a section called “Debugging tips.”
2. Possible port numbers are discussed in en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers. In a nutshell: well-known or system ports range from 0 to 1023; registered ports range from 1024 to 49151; dyanamic, private, or ephemeral ports range from 49152 to 65535.
3. Mmark-flavored Markdown is one of the markup languages that Hugo supports. Details about it are at github.com/mmarkdown/mmark. The version of Mmark that Hugo uses is documented at miek.nl/2016/march/05/mmark-syntax-document/.

Discussion and suggestions💬

To post a comment on this page, you need a GitHub account and your browser needs to be able to run a script that is hosted on https://utteranc.es.