What's the difference between themes and layouts?


I’m doing my first steps with Hugo. So far it’s looking great, but I’m confused by the notions of “themes” and “layouts”. How are they different and when would I use one over the other? It seems I can use both for the same purposes, only that a layout file would override a theme file with the same name. Is there more to it?

Thanks for any pointers!

Both theme and your main site can have layouts – your site’s layout files will override theme layouts with the same name and relative location.

A theme can also have static content (style sheets, images etc.), data files and i18n language files, so there is more to it. The basic motivation behind themes is to be able to reuse other’s work:


If you go down the theme path, YMMV on a WIP:

I’m starting to think it makes the most sense to just keep your content files as your site and do all your development as a theme, regardless of your intended finished product. Just a thought.

Thanks for your replies! I’ve put most things into a theme now, and only some things specific to certain content types of my site into layouts.

I’m reviving this old discussion to ask what I see as the implicit question: using a theme to style a website is mandatory?

If I don’t want to share a theme or reuse other’s work but just use a style for a single website, then I don’t need to create a theme, right?
I can use toplevel archetypes/, data/, layouts/ and static/ directories. What about i18n/? Can I use it at toplevel as well (it’s not created by hugo new site)?

Well, maybe using a theme may be recommended anyway. If I want to totally change a website style one day, all I have to do is creating a new theme. This would not be possible if I put the style at toplevel (which overrides any used theme).

No. There are use cases when a theme is not needed.


Yes to all of the above. The directory structure you see under a theme can also exist at the top level.


@fedelibre Checkout the website source of letsencrypt, they use layouts but not a theme.

1 Like