Theme Standardization Through "Feature" Support

I’d like to propose a mechanism by which themes could become more standardized and interchangeable.


I recently started using Hugo. I was immediately impressed by the flexible and rich data-model it supports. On the face of it, the content is all Pages, and you can decide if you want to have specific Sections and related Archetypes. Plus, you have all the power of defining your own Taxonomies and even just straight-up raw Data if all of these other generic concepts cannot be used to provide what you need. Very cool! :smile:

But, now I’m looking at the theme gallery and even trying switching from one theme to another. Oh, no! This doesn’t work at all. One theme assumes that I have sections under “post” and “project?” Another theme assumes I have data about each author in a Data.authors listing. The theme is making all sorts of assumptions about my content and data, and requires a bunch of additional configuration specific to that theme to make it work. Now, if I want to switch to some other theme, I’ll have to start all over again! Waaaah! :frowning:

Themes Aren’t Standardized

So, the problems, as I see them, are that Theme authors are missing advice on how to design their themes to be swappable. Every theme author comes up with her or his own workarounds and hacks to accomplish the same goal, but in a different way. Usually, this involves a lot of Params in the Site config files and in the Archetypes for the various sorts of pages they support.

Introducing Features (or Theme Features)

Wouldn’t it be great if there were a list of features (conventions) that a theme author could promise that they support, and then, users could know that if they are switching from using one theme to another, they need to have overlapping feature sets, or things might break. Also, you could have really clear and standard error messages when you attempt to use a theme which doesn’t support a feature your content is obviously attempting to use. Basically, a Feature set of features would be defined in your config file.

Features = ['multi-author', 'gallery', 'hero-image']

Then, you, the user, would go about configuring your content according to the conventions that each of those features require. Oh, I see, using the ‘gallery’ feature means that I will have to specify a list of GallerySections in my config and then put all the images in those designated sections.

Theme authors would then be able to say that they support certain Features and (implicitly) that they don’t support others. It would also make it the Theme author’s responsibility to gracefully degrade when the content doesn’t use a Feature the theme supports. For example, I don’t have any plans to expose who the authors of my website are. So, even though you support the ‘multi-author’ Feature, you better remove that part of your layout and figure out how to make the theme look good anyway.

Theme authors would actually list the themes they support in their theme configuration file, and it would enable the Theme gallery to be filtered by themes which support the features the end-user is most excited about using.

I can see that some support is currently under consideration for adding standardized support for Authors. But, it makes me wonder if it shouldn’t be extracted into the first example of a Feature. If your site doesn’t use the feature, why should you have the cognitive overhead when reading the documentation of seeing a .Site.Authors variable. I really like the idea of standardizing on very commonly-used features of websites, but I think it would be a more generic enhancement if each of these features could be developed, and reasoned about separately.

Features offer a bridge between the generic nature of the core of Hugo and the specific nature of the Themes currently in existence.


I totally agree. I spent some grudging hours getting the theme site up and running with all the themes …

I’m not sure how this should be done though.

In its simplest example there is the classic blog layout:

The theme requires that you have

  • a section with the name “posts”
  • an section named “pages” with a single page “”.

The above is 3 variables that need to be set to “fulfill the feature of a blog”. Some of those could be optional, but today they are hardcoded, but should be provided by the site.

So given my site bepwasherecom:

In my config.toml:

I have a features section:

posts: someposts (my section for posts)
… and nothing more.

So a blog theme would look in the config and throw an error if it doesn’t meet the requirement, and it could notice that I haven’t configured the optional pages section etc. and do not render it.

/cc @spf13
/cc @digitalcraftsman

Actually, I wouldn’t expect “Blog” to be a Feature. I think it is too coarse-grained a concept. I would expect such a theme to advertise support for a set of features: ['about', 'pages', 'blog-posts'] Or something like that.

1 Like

To contribute my 2 cents two the discussion:

Standardization is great from the user’s perspective because it removes all the overhead of adjusting the config file while switching a theme.

For simple pages like blogs this might work if we agree on a coherent scheme for data that are common across all themes of this type. Having a standard like the Ghost blogging platform would make it easy to swap the theme because all variables are standardized.

On the other hand Ghost’s targeted audience are bloggers who mostly have the same requirements on a theme. But I consider Hugo much more flexible. Many of my theme ports have different features that I need to address somehow. Over the time I tried to be (more or less) consistent with the variable naming. But the manual changes are still necessary because most themes are just too different.

Furthermore, all theme maintainers would have to adapt the new standard (that are defined by whom?) and it would even take longer for theme users to switch. This would also create unnecessary overhead on the other end if they have to update their config file for the same end result.

In general, I consider this as a good idea for upcoming themes. But it’s hard to do with the 80+ existing themes.

Because I don’t want to reinvent the wheel it would be great if you could share your experience with other platforms like Wordpress, Drupal etc. Those are very flexible and a transition to another theme doesn’t seem to be that hard. I don’t have practical experience with them and admittedly Ghost might not be the best example.

But you should get the point.

If we cannot do something with the existing themes, then this is dead in the water. But I don’t agree with that. Work, yes. But doable. Having a standard that isn’t a standard isn’t really a standard.

“Hugo” (whoever that is) should define the standard and I see it as a two-way negotation:

  • Hugo asks the theme on behalf of the site what features it provides (error if none)
  • The theme asks the same and act in accordance

To add to that, @digitalcraftsman – I agree that a theme must have its total room for creativity, so there will always be special cases to handle (which can we made easier with params inheritance from theme), but a baseline (such as the blog-post feature example) would be nice.

WordPress has custom post types that are essentially the same thing, with the same concerns you’ve brought up. They default a few like post and page, but just about everything else is custom by theme or plugin. A great example is testimonial fragmentation. Tons of WordPress sites support some version it, but they use their own testimonial implementation or a common plugin.

WordPress has the same issue with author and social media support. Author metadata is limited, including mostly defunct options like Jabber, while not having common social media links. The same thing on the site level, almost every site has links out to their social profiles, but you end up defining them in 3-5 places depending on what themes and plugins you use.

It’s always going to be tough to decide what to support as “core” supported features, but the more standardization the better.

Apologies for the necro. I’ve been reading for something to kick my decision paralysis on how/where to define/structure some site/theme data and had a thought that connects a few different threads I’ve seen here and in github issues (re: standardizing themes, author metadata, testing themes, rating themes, providing a default theme…):

Instead of declaring and negotiating feature lists, it seems like Hugo could create the scaffolding for and accumulate feature/behavior tests that define, document, and check the configuration and behavior of sites and themes. Hugo’s theme site could present pass/warning/fail status for these tests, along with the status of more general theme tests discussed recently in

Running the same tests on your local site would output a machine-readable report that identifies when your site’s causing compatibility problems of its own. The theme site could have an in-browser compatibility checker where you paste this report to filter out incompatible themes.

It seems like this arrangement might better orient the various incentives and feedback loops at play:

  • Users get clear, consistent signals about theme features, behavior, and quality.
  • Users can identify local changes they need if they want to be able to readily switch themes.
  • Theme developers get a strong nudge towards developing better initial releases.
  • It gives users, developers, and the core Hugo community an active lever for continually proposing, discussing, and promoting better practices: develop/improve a test and send a pull request.