Hugo Themes Dont's

Are you thinking about submitting a theme to the Hugo Themes website?

If yes, here is what you shouldn’t do:

  • Never leave pages without layouts. Instead use disableKinds. A theme with no layouts for various kinds pollutes the Hugo Themes deploy logs to the point that these are almost unusable
  • Never ever hardcode PATHs. Stop constructing URLs in the form of:
    {{ .Site.baseURL }}/something right now.
  • Also never use .Page.URL instead use .Permalink, .RelPermalink etc
  • Again do not hardcode PATHs in your theme’s Example Site configuration.
  • readDir or readFile are not really meant for themes that are supposed to be usable under various hosts and various situations.
  • Keep your Git Repo’s history down. No huge binaries.
  • Never use photos that are copyrighted. Make sure that your theme’s resources can be used in an Open Source theme.
  • Maintain your theme. If you’re thinking about submitting a theme and then forget about it, think again.

I am actively looking at existing themes.

If a theme demo fails to render with the latest Hugo I typically contact a theme’s author.

If I do not get a reply your theme will be removed.


What best practice do you recommend to construct URLs instead?

@martignoni see this post over here with what I reccomend:

P.S. @maiki maybe that thread needs to be merged here. It’s always best to keep things in one place rather than having them spread out in several threads

1 Like

Use relURL or absURL, e.g. {{ $url := $mypath | absURL }}.

That said, I see many people manually constructing URLs when using the Hugo provided Permalink/RelPermalink would be better, i.e. I would much prefer

{{ with .Site.GetPage "mypage" }}
<a href="{{ .Permalink }}>FOO</a>
{{ end }}

Compared to:

<a href="/mypage/index.html">AAA</a>

The above example may not be that good, but I see lots of similar constructs that would have been more portable and robust doing it the “first way”.

I know there are some situations with taxonomies that still need some “manual URL” handling, but that situation will be drasticly improved in the next Hugo, see:


Continuing the discussion from Hugo Themes Dont's:

I actually don’t know the best way, but…

I think we’d get more traction if we documented the best ways and why. @alexandros would you mind expanding on the quoted points? Once we have something, I’ll post it to #tips-tricks. :slight_smile:

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. 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.


Incidentally here is a console message from the latest Hugo v0.55.0-DEV that I compiled just now

WARN 2019/03/24 04:45:30 Page’s .URL is deprecated and will be removed in a future release. Use .Permalink or .RelPermalink. If what you want is the front matter URL value, use .Params.url.

It seems that it just got deprecated after all.

Also note that I got this warning for an older project of mine. I’m also guilty myself of using .Page.URL in templates :upside_down_face:

Given the bit in bold, what’s the proper replacement for .URL when building a menu?

AFAIK the .URL in menus is not deprecated … only the .Page.URL is deprecated, which can be replaced with .Page.RelPermalink or .Page.Permalink.