Hugo Themes Dont's

tips & tricks
6

Suppose you need to quickly test a theme under various devices using a custom local IP in the console with the --bind flag.

Assets that are linked in the form of {{ .Site.baseURL }}/something will throw a 404 since they inherit the value from the project config. One will either need to go in the templates or set the baseURL in the console every time.

Also whenever a URL is hardcoded from the config with a parameter i.e. https://some-external-URL.com or with the printf function combined with the readDir or readFile functions again this results in a hardcoded string that causes problems with the architecture of the theme site, because assets that are linked as such again can throw 404 errors.

My point in the thread you linked to is that theme authors need to stop treating themes as if these are their personal projects and need to make them more flexible. They need to take into account that these themes may be used in various situations and architectures that are not the typical way.

The Hugo Themes website itself is not a typical Hugo project at all since it is created and published with a pretty complex Build Script

It is always preferable to use the absURL, relURL, absLangURL, relLangURL functions for outputting URLs from a string i.e. {{ "hello" | relURL }} and the template variables .Permalink, RelPermalink for Pages and Resources.

.Page.URL is marked to be deprecated and then removed, so I do not recommend its use, but note that in the context of Hugo Menus .URL is the only variable that outputs a menu item’s permalink.

Furthermore in the Common Permalinks Issues section of the README in the Hugo Themes repository we mention the following:

  • If using inline styles, these need to use absolute URLs, for the linked assets to be served properly, e.g. <div style="background: url('{{ "images/background.jpg" | absURL }}')">

  • Make sure not to use a forward slash / in the beginning of a URL , because it will point to the host root and Hugo will not generate the correct URL for the demo’s assets.

  • If using external CSS and JS from a CDN, make sure to load these assets over https . Please do not use relative protocol URLs in your theme’s templates.

Missing assets are still the #1 problem we encounter when testing theme submissions with the Themes Site Build Script, hence my post here, also I might submit some of these points for inclusion in the Themes’ repository README.

6 Likes