Theme standards and general experience


@bep spoke of standardizing themes. I think this is a great idea and a must-have, but I have not seen a general discussion over that.

So what is to do?

  • Build a hugo get command to get a theme?
  • Wouldn’t it be nice to have a general hugo get command with the following sub-commands:
hugo get theme
hugo get widget
hugo get what else?

or even better:

hugo get theme the-theme's-unique-identifyier # (e.g. material-docs)
hugo get widget the-widget's-unique-identifyier
hugo get what else?

which would be so nice. We also would need hugo update to update themes and widgets in this case.

  • Would we need to centralize themes and widgets? How to do it? Looking at the hugoThemes repository, I think themes are already centralized and that it is ready to use with a hugo get theme command, which needs to be written.
  • Now, what would be the standards for a theme? I assume we don’t need more than the following files:
└── mytheme
    ├── config.toml
    └── index.html

And inside the config.toml (or config.yaml), the assertion to extend a theme would be:

extends: someother-theme
  • I often saw that I could not switch a theme without heavily modifying the main site’s config file. So, should we specify and recommend standard config vars (especially, params) to ensure that a same site would work with all themes that follow those guidelines (to draw the parallel, I would like to recommend some specific widget area names for the same reasons)?

Sum up

In my opinion, the general goal we have to aim is to enable non-developers (or not-so power users) to use Hugo and get personnalized, pretty websites. This goes by:

  1. Switching themes should not be painful (user has to experiment several themes if he/she cannot develop his/her own). This would be enabled by standard config recommendations for theme developers.
  2. Modifying a theme should be easy. One modification, in the case of theme inheritance, would need only to create one directory, one config file with one line (extends: …), and one file that replaces that of the parent theme (He/she copies the original file in the child theme and modifies it). This is easy enough for not-so power users (but not true beginners, but diving into themes cannot be that accessible in my opinion).
  3. Adding information aside of the main content should be easy. This is where widgets come into play. Widget area names should be normalized, such as that another theme would probably use that same name for the same position (e.g. sidebars, headers, footers).

And you? What do you think we need to help make the Hugo experience even happier?


I appreciate the direction this is headed. A few questions:

  1. On GH you mentioned WordPress child themes. My understanding is the primary benefit for Child themes in WordPress is to prevent individual theme customizations to the functions.php file from being wiped out during WP Core upgrades. Because Hugo does not use such a rig, I’m having trouble understanding the upside to the whole extends idea. Given Hugo supports the ability to perform layout inheritance within sites (which works especially well with block templates), what value would adding another N levels of inheritance buy us in your eyes?

  2. What exactly is a Widget and why would I want one? The terms widget, component, plugin, module, etc. are all traditionally loosely defined and, as a result, seem to complicate the CLI proposal using get which may never be used for more than themes (assuming widgets aren’t a thing, because they don’t exist yet) and building such a thing would be difficult given the ambiguous definition of “widget”, adding friction to advancement and justification of a get sub in the CLI.

  3. It seems the primary goal here is to ease the selection of themes for improved DX and Hugo end user experience. Is that correct? If so, given current themes and tooling do you feel the existing theme gallery could be improved? And, if so, what if any thoughts do you have to help improve the gallery without introducing a new CLI command?

And now some opinion. I’m packaging up my theme using NPM because some users might want to install it that way if it makes sense for them. That feels like a very user-specific and personal choice. And I don’t believe attempting to push standards unto themes is going to be effective unless done via standardization during introduction to the theme gallery.

Lastly, what about build pipelines? We have bash and NPM scripts, toolchains like Hugulp, boilerplates using pukes in mouth Webpack etc. How should users be using those in combination with the concepts being proposed here?

1 Like

In my understanding, the primary benefit for Child Themes in Wordpress is to prevent all individual theme customizations from being wiped out during theme upgrades.

I am so glad to learn about the block templates thing!! I did not know that we could already do template inheritance. This is great news for me, as I understand now that it is easy to extend a theme by externally modifying templates.

Here I described what I intended widgets for: Widget mechanism.

Totally correct from my views :slight_smile:

Actually, I find that switching themes is not so easy for the moment. As it is, the theme gallery is very nice and I like it very much. It is easy enough (at least for me) to install new themes, although I don’t know if it is easy to do it without git.

I experienced that switching themes:

  • often broke my site (the site did not build anymore or had empty pages)
  • often needed big modifications to my config file, because themes required arbitrary params. This is nice because the theme developer has freedom, but after only 3 theme tries this leads to config files that look like this:
baseurl: "http://www.blah/"
languageCode: "fr-fr"
title: "my title"
subtitle: "my subtitle"

theme: hemingway2
#theme: hugo-material-docs
#theme: hugo-me-theme
#theme: hugo-multi-bootswatch

metadataformat: "yaml"
canonifyurls: true
# Enable Google Analytics by entering your tracking id
googleAnalytics: ""

paginate: 5
paginatePath: "page"

    # FOR THEME hugo-material-docs

    author: Le Barde
    # General information
    description: ""
    copyright: "Licence CC-BY-NC."

    #version: "1.0.0"
    logo: "images/logo.png"
    favicon: ""

    # Custom assets
    custom_css: []
    custom_js: ["", "mathjax-support.js"]

    # Syntax highlighting theme
    highlight_css: ""

      primary: "deep-purple"
      accent: "red"
      text: "Ubuntu"
      code: "Ubuntu Mono"

    # FOR THEME hugo-theme-me
    colorscheme: red
      name: "Me"
      description: "A Simple Hugo Theme"
      #  label: "About"
      #  link: "/about"
      title: "Hello, It's Me!"
      intro: "Welcome to my page!"
      text: "I am a simple responsive theme for [Hugo]( based on [Read Only template]( by HTML5UP. To install Me just run inside your Hugo project:\n\n    $ mkdir themes\n    $ cd themes\n    $ git clone hugo-me-theme\n\n See [README](// for more information."
      label: "About"
      link: "/about"
      title: "Few Works Made by Me"
      intro: "Let Me present here its color schemes"
    email: ""
      copyright: "[My site]( Licence CC-BY-NC."

    # FOR THEME hugo-multi-bootswatch
      inverse: false
      name: cerulean
    # list of possible theme names that can be used
    # name: "cerulean"
    # name: "cosmo"
    # name: "cyborg"
    # name: "default"
    # name: "flatly"
    # name: "journal"
    # name: "lumen"
    # name: "paper"
    # name: "readable"
    # name: "sandstone"
    # name: "simplex"
    # name: "slate"
    # name: "spacelabs"
    # name: "superhero"
    # name: "united"
    # name: "yeti"

  #twitter: "lebarde"
  github: "lebarde"

    - name: "Accueil"
      url: "/"
      weight: 0
    - name: "Articles"
      url: "/articles"
      weight: 10

  smartypants: true
  fractions: true
  smartDashes: true
  plainIDAnchors: true

So, I think the community would appreciate standardization for params (e.g. “Author should be described with”). IMO this should not be a mandatory requirement, but only a recommendation for theme developers that want to share widely.

What I proposed was not to reinvent the wheel. Only to specify to Hugo what was the push command. This would have enabled to make a hugo full-upgrade command that updated everything, builded and pushed the site to the public server directory. But as I said here, we can already do that externally, so this is not useful.

1 Like

All good just dropping some comments for sake of discussion. I saw in the Widgets thread the captain suggested using hugo get to match Go dependency management conventions. Having a standard way to do things could certainly help build something like this longer-term:

You may also be interested in:

That indeed would be nice!

Blocks take care of inheritance (“extends”) at the templating level, but I think the above desire to keep compatibility with a theme’s upstream while adding personal modifications has always been achievable thanks to Hugo’s lookup order.

I think more drop-in-and-watch-the-magic goodness in themes is likely to be some more conventions, to be sure, but will mostly come at the template-function level, IMHO. I’m not saying this solves every problem, but it’s a heck of a smart idea and helps with a lot of current themes:

@lebarde I agree with @jhabdas about not fully understanding still the difference between a partial and a widget, but don’t let that deter you:

  1. I know you’ve done a lot of work on the PR and appreciate it
  2. To reveal my own biases , I have an equally emetic response to the “Wordpress” that @jhabdas has to “webpack,” which is by no means your fault :smile: (I’d like your thoughts on rollup, @jhabdas, but maybe in a DM sometime when you’re not too busy)

All around, I think we agree that the current ‘git clone’ method is far from ideal…

Thank you for your appreciation!

Actually, digestion mostly depends on our bacterial flora… Better vegetables and good cooking :slightly_smiling:

Could you tell me what may not be clear about partials vs widgets? Maybe I wasn’t clear enough. My first post in the Widget mechanism thread is dealing with the difference between partials and widgets. You can also see a partial as a craft piece of code, and a widget an all-in-one, polished block that you (and the community) can reuse across several Hugo websites and configure at everyone’s needs.

FYI / for others:
slight typo in your “lookup order” link - should be:
(not …/templating/…; now fixed - thanks!)

1 Like

Throwing this out there. Before we start getting things perhaps it would be apt to have a standard way to scaffold them first. Maybe something like this: I would see something of this nature saving mancenturies if created before the concept of widgets (plugins).

1 Like

I am not sure to understand: what about hugo new (theme, post, site)?

Given the context of the discussion I was thinking you might prefer hugo new widget. My point being perhaps getting something like that in and tightening up theme standards might make it easier for them to pass through the @digitalcraftsman gauntlet, and open the door to sub command extensions by freeing up core development time.

As a user I would prefer having the ability to easily use widgets or themes rather than developing them. I assume that developing themes and widgets is easy enough, but for newcomers I assume that the most important would still be a hugo get widget my-widget-name from a centralized repository. And then, a hugo update to update widgets, themes, and so on. What is your feeling about that?

Seems like pretty sane API to me. To preserve vestiges for those migrating from WordPress there may be some value to using the more common vernacular of plugin as opposed to widget and setting common environmental boundaries around what widgets can do to remove bikeshedding during the design process. Seems like the next step would be to create a POC by identifying the most common use case imaginable and using that as a first step towards a spike to build out the subcommand, which should be planned for and adhere to core standards.

That’s my two cents anyway.

Here’s an idea for the POC for Hugo widgets, probably one of the most common scenarios and a good test case due to environmental needs which could be abstracted away while adding very little overhead using a micro-container approach to plugin addition with the potential for “swarming” and automatic service discovery:

hugo get theme addon pygments

Hi, I’m wondering if there was any resolution here - ability to “inherit” or “extend from” an existing theme would be great from my perspective - what is the best practice here? Perhaps maybe a documentation FAQ item could be written on this?

That feature is being worked on.