What are the benefits of using a theme in Hugo?

support
1

I hope this question is not too broad for this category. I am curious what the benefits of building and using a theme over building bespoke sites with Hugo without a theme.

I can see why you would choose a theme if you intend to sell it as a product. I can also see the benefit if the theme provides only atomic components and some basic setup. That way, you can reuse the same base theme for all the projects, and once you update the base theme, all projects using the theme will get the update.

The latter can also be a double-edged sword if changes to the base theme could break some projects or cause noticeable (but unintended) changes in a project’s UI.

Is there an option to opt out of updates for a theme?

I ask this specifically when the theme is added as a git submodule. ?If it is a Git submodule, does Hugo pull the latest from GitHub during a build, or is there a version string that needs to be bumped manually?

Some of the details on the theme components page sound interesting:

But I also noticed that there is a notice that the docs here may be outdated and is being rewritten.

I have a repository published to NPM and use via npx when starting a new Hugo project. I kinda like this because I still do hugo new site . using the latest Hugo version and then run npx @project-calavera/hugo-skeleton --output=. to get all my latest scaffolding. I do wonder if I am missing out on something though. :slight_smile:

You could also have a bespoke Hugo set up as a template repository on GitHub. Whenever you start a new Hugo project, you create your new repository using the template repository.

The downside is, updates to the template repository do not carry over to older projects created from the template.

So perhaps the ideal is a base template that offers only atomic components, style, and JavaScript, and then the rest is built in a bespoke fashion. But now I wonder whether you can have a theme and add templates, partials, shortcodes, data files, etc., outside the theme.

Anyway, I am rambling a bit now. I guess in the end, there is no ONE way to build with Hugo. :person_shrugging: I would love to hear people’s thoughts on this. Thanks!

2

The main benefit of a theme is, as you mention, reusability. I have built 30+ sites on top of my own base theme. It has saved me many hours!

I think the best way of adding a theme to a site is via Hugo Modules.

You can deploy specific versions of a theme with git submodules but I find it far more convenient with Hugo Modules.

2 Likes
3

Thank you so much for your input, @frjo.

So you would import a theme using modules as mentioned in the docuapi repo (GitHub - bep/docuapi: Beautiful multilingual API documentation theme for Hugo):

[[module.imports]]
path = "github.com/bep/docuapi/v2"

This makes it easy to add a specific version and not always what is in main. I guess the example above uses a tagged release.

So, if you import a theme like this (or by some other means), could the theme only provide core, base components in the form of either partials or shortcodes (along with the needed CSS and JS), but the templates, additional components, CSS, JS, and, say, data files are all added specifically to the current project?

Is there a way to override the styles defined in the theme (other than !import :grin:) in your own CSS files?

So, inside assets, data, layouts, and static at the root of the new project. I am also thinking about things like integrating a headless CMS like TinaCMS. Could the theme provide that configuration? It does not sound like something you would expect from a theme. When I think about a theme, I 100% think of the look and feel and some basic UI interactions through components like a responsive menu, tabbed-ui, and an accordion for something like an FAQ.

From the Hugo docs (Hugo Modules | Hugo), it sounds like modules are pretty new in Hugo. Is this the future vision for building with Hugo? If you had to teach someone to use Hugo and you chose to go the theme-less route, would that be a terrible idea? Thanks again!

4

I had not realized that since I modified my theme so extensively, it had nothing in common with the original one beside the few js scripts, so it didn’t make sense anymore to keep it under themes/. Hell, I had not thought I could do otherwise. Thanks for the tip

5

How you decide to load the theme, or not using a theme at all, is completely up to you. Use whatever you find most convenient. All the templates, partials, shortcodes, assets etc. works the same regardless of how you load them.

Personally I think Hugo modules is one of the most powerful Hugo features. With Hugo modules you can load more or less anything, not only themes. Here is a nice example of a image gallery feature: GitHub - bep/gallerydeluxe: Fast Hugo gallery theme/module suitable for lots of images.

You can also load in content, assets, date directories etc.

In whatever way you load e.g. a theme, Hugo always allow you to override files.

Theme files:

  1. mysite/themes/zen/assets/sass/styles.scss
  2. mysite/themes/zen/layouts/_default/single.html
  3. mysite/themes/zen/layouts/shortcodes/contact.html

Will be overriden by:

  1. mysite/assets/sass/styles.scss
  2. mysite/layouts/_default/single.html
  3. mysite/layouts/shortcodes/contact.html

If you load the theme as a module it will not actually show up in working dir themes/ but overriding it still works the same way.

You can even add multiple themes to a site and the order will decide what files are actually used.

6

That is exactly what my next question was going to be! :smile: You can almost use it like loading NPM modules in the Nodejs and JavaScript world. So you can load only those components needed for the current project and nothing more. As it ties into Go modules, I guess all of this applies: Using Go Modules - The Go Programming Language

Out of curiosity (and I can try this myself, so consider this a lazy web request :smile:), I guess a module could then be written in Vuejs, React, Svelte, or native web components, and it does not matter.

You can even add multiple themes to a site and the order will decide what files are actually used.

This sounds amazing! I guess one can substitute themes for components here, right?

Thank you for all of this great input, @frjo :raised_hands: This is one of the big reasons I still love and use Hugo when given the choice. :+1: The Hugo community is amazing.