Theme consistency

It’s early days with hugo but already it’s very difficult to switch quickly between themes due to different settings and parameters. Some of this might be addressable with documentation, some with code changes, but I’d like to see how we can make this easier both for theme creators, and theme users, before leaping down the path of how to resolve it best.

Some things I’ve personally noted:

  • it’s very confusing for newcomers to toml / yaml format to work out the correct parameter names, and whether the capitalisation is important. It varies across theme implementations.
  • parameter names differ between themes, and in some cases do different things in different places. We could do with a list of things in the config file that MUST / SHOULD be handled in themes. i.e. break down what a theme user can rely on, vs what is optional for a theme to implement (but if present, it will be consistent), vs stuff a theme should document itself. This might be able to be generated programmatically even, but its a documentation thing at heart. Some examples are authorname, defaultdescription, sidebartitle, which are sadly missing, or different, in several themes.
  • list of things a theme author should ensure they’ve taken care of, maybe this can be coded up in future as a sort of test. For example using {{baseurl}} whenever possible instead of /.

As a newcomer and as having just built a theme, I definitely agree. I tried to create sane defaults so that when a variable wasn’t available the theme didn’t show what it couldn’t or showed something obvious, etc.

So if it was an obscure value, of course, it simply didn’t show some element on the page. I figured the users could go back and add those if they wanted to use the design elements. …But you’re right, what if another theme also then used that variable name? For something else?

I found .Site.BaseUrl unavailable in certain areas as mentioned before. Though I didn’t even think about it at first, it was quite obvious of course. Would it be possible for Hugo to catch all href="/ strings and change them to prepend the base URL automatically? I suppose someone could want to link back to the root domain in some cases, but if they put an absolute URL with http then that would solve that or perhaps even // which might be awkward but perhaps another option.

What about namespacing variables? I could prefix all variable names specific to my theme with some characters…Could we even use underscores? I suppose we could put them in a map too.

The only way that I’d know how to start this would be to borrow from WordPress or Drupal (e.g. My worry is that standardizing around blogging themes kind of casts everything in a blogging light. CMS’s are mature enough that there’s got to be a sort of taxonomy for content, articles, sidebar versus navbar, header, footer, post, blog.