Learning how to switch themes


I have managed to get my first hugo test site working more or less as I wantedm, using a theme picked up more or less at random in the theme gallery.

Using that theme (academic), I set up custom home page, menus, permalinks and similar things. Once that worked, I said OK, let’s see how this looks with other themes. I got a mess. Lots of errors like:

ERROR: 2017/01/05 18:31:51 template.go:142: Unable to render [partials/navbar.html theme/partials/navbar.html]

and a site without a theme, and without the basic features, e.g. menus, even in themes that do support menus. I have tried 3/4 other themes, it’s always the same result.

Now I may look at all errors, add the required partials or other files one by one, etc… until I hopefully get everything working. Until I have to do the same thing to try another theme.

But I’d rather learn why this happens in the first place, and how, in general, to easily switch from theme to theme. In other words:

  • how much of this depends on hugo themes not being standardized, i.e. each theme developer giving different names to the same things/options/files, or similar? (not criticizing, just curious, really)
  • what is the most efficient way to handle this? Besides the obvious copy and paste of theme-specific options in config.toml, I mean? Is there an efficient method to follow, once you download a new theme, to make sure that it will work? Something like check if these files are present in this folder, if not copy them?



Yes, you’re on the right track in your thinking. A theme can be fairly generic in its design and support the standards Hugo has set-forth while also adding additional functionality. The Academic theme is a great example of this - it follows the Hugo standards (as much as I can tell after a quick look at the code) but adds the necessary configuration elements to make it look and perform in a manner suitable for an academic with a potentially large amount of information to publish.

This sort of thing is not specific to Hugo either - the same would happen in WordPress for example, albeit with different errors and different ways of fixing them.

The important thing is to make sure you are representing your content in the most Hugo-ish way possible. Of course, if you decide to use a theme that was built by somebody else and they use a custom parameter for the title of the page, well, you either need to change the theme code or change your content to work with the theme.

What I am getting to in my long-winded reply is that I think it’s more important to determine what your needs are first and foremost - what information do you want to convey to a visitor of your site? Then its a matter of organizing your content efficiently and writing or updating a theme to make use of that organization. Do it the other way around (layout first) and you are somewhat beholden to whatever the theme developer came up with.

This can be a really complicated topic that gets into the essence of design (and not just for aesthetics). Things become easier when you are just theming a standard blog with an agreed-upon set of functionality - much more difficult when the content is not just a list of articles with a title / author / description / date.

Hy @langhorst,

I am not sure that we are really talking of (all) the same things

First, I’m not going “layout first” at all. I am experimenting to migrate to hugo several existing sites, quite different from each other, each with a lot of content and its own requirements in terms to “what to convey to visitors”.

Second, I am talking of things being totally broken when you move from one theme to the other, not of some parameters not showing. If I thought Wordpress is better than Hugo for my needs I wouldn’t be here. But on wordpress, if I configure a blog to use a theme and tweak that theme, then switch to a different one, the site is still usable. Maybe ugly, but fully usable.

Whereas with Hugo, just to make two examples:

  1. if I start with one theme, copy its “single.html” template to layouts/default to tweak ONE parameter (in my case: add links to translations), then try to load another theme, then hugo throws a lots of errors, and doesn’t compile the site at all. Part of those errors are because partials that do the same thing (i.e. render the footer) have different names in the two themes.The only way I see to avoid this when testing a different theme, is to rename the layouts folder to something else, e.g. layouts.academic, then repopulate from scratch an empty layouts folder, one file at a time. Is this correct?

  2. if I find a theme that I think it’s perfect for me, except one non-trivial thing, it is far from obvious how to add that feature, even if it is something surely supported by Hugo.

Concrete examples of point 2:

a. where do you paste, and how do you modify, the code in https://gohugo.io/extras/menus#rendering-menus to make the aglaus theme display a menu with what you put in .Site.Menus.main. ??? Yesterday, at some point, I tried to copy that menu code referenced below in (IIRC) the single.html template of the aglaus theme: I got no errors and… totally blank pages, except the sidebar…

b. just for fun: if I wanted to add a sidebar to aglaus, where should I write the corresponding partial?

I’m not asking for a point and click platform, mind you! I’m saying that a less unpredictable behaviour (see the links to translations case), as well as concrete examples in the docs of how to do the things above, wouldn’t hurt at all.

One thing I really don’t understand, instead, is the fact that several themes seem only installable via git. This is not a problem for me at all, but not providing a single tar/zip file makes that theme unreachable for many potential hugo users. I know it’s up to the single theme developers, but I wouldn’t feature in the official theme gallery themes accessible only via git. Or at least I would flag them explicitly as “only usable with git” so users without git wouldn’t waste time looking at them

1 Like

Hmmm. Maybe I or someone else can better help with a specific example. What site are you attempting to migrate? Let’s focus on that first and attack one thing at a time. Could you set-up a repo on GitHub with an example of what you’re trying to do?


  1. This could make sense, though not the most user-friendly, I will agree. I don’t want to assume what’s going on without seeing the specifics for myself though. But, in general, yes, if you are overriding parts of a theme within your main layouts directory, you will more than likely need to restart from scratch with a new theme. I’m sure you’ve read this already: http://gohugo.io/themes/customizing/

2a/b. I don’t know anything about the Aglaus theme and unfortunately my knowledge of AMP is still minimal, but it appears that you would follow this document: https://www.ampproject.org/docs/reference/components/amp-sidebar. The additions required would be made in the “baseof.html” layout in the Aglaus theme. You could either add the menu functionality directly within “baseof.html” or write it in a partial file such as “sidebar.html” and include it in “baseof.html”.

Re: theme sources, maybe a suggestion worth throwing into an issue? Though if it’s on GitHub, it can be downloaded as a zip with that big green button.

about “What site are you attempting to migrate?”: unfortunately, I cannot share this online until it’s ready to go public again. Not my decision, sorry. BUT: please note that there is no need to look at that website or any other to answer. One can just start with an empty new site, a “lorem ipsum” page, and then try to add a sidebar and/or menu to it.

  1. I had read http://gohugo.io/themes/customizing/ But I really didn’t expect that there would be such a mess when changing theme. even on “standard” parts like footer or navbar partials. I suggest to add in very big font, at the beginning of that documentation, something like what I wrote, i.e.

“The only way I see to avoid this when testing a different theme, is to
rename the layouts folder to something else, e.g. layouts.academic, then repopulate from scratch an empty layouts folder, one file at a time”

because, as obvious as it may seem afterwards (even to me, now), for a hugo beginner is not so obvious at all…

2a/b: First, thanks for the pointers to the AMP page and aglaus files, that’s very helpful for me. Second, I discovered only in this second that the author of aglaus has made a theme with (it seems) the same basic structure BUT menu and sidebar. It’s called “beg” http://themes.gohugo.io/beg/ and it is probably the best place where to look at, and copy/port code to aglaus.

about the big green button of GitHub: I know about that. But I am talking of how themes are presented in the hugo gallery. A good example is just aglaus: you go to http://themes.gohugo.io/, see aglaus, click on it because you like it, and end up on a page: http://themes.gohugo.io/aglaus/

where the only installation instruction is, literally,

cd themes ; git clone https://github.com/dim0627/hugo_theme_aglaus.git

again: not a problem for me, personally. But if I had no idea of what git is, or no way to install it on the target machine, I’d be quite pissed off by the fact that the theme home page doesn’t tell me at first sight which themes (aglaus and many others) are not worth looking at, because they cannot be simply downloaded as one zip file.

Just noticed it: another theme that is nice, but even worst to install than those that expose only the “git” option: http://themes.gohugo.io/hugo-theme-foundation6-blog/

I didn’t read whole of this topic since it seems more opinion-discussion than a help question, but to respond to this: any theme that’s on Github can be downloaded as one zip file:

  1. Go to the theme’s page on the website (like http://themes.gohugo.io/aglaus/).
  2. Click on the link to the Github source (in the case of Aglaus, that’s the ‘Homepage’ button). Other themes mention this information in the text, so you’ll need to look/read for it.
  3. Then on Github, click on the ‘Clone or download’ button:

There’s no need to use Git to install or use themes. (I also never install a theme through Git.)

[quote=“Jura, post:7, topic:5025”]
it seems more opinion-discussion than a help question[/quote]

the part about how to present /inform about themes in the theme gallery, yes, that’s not help question, but opinion, or I’d rather say constructive critique, see below.

The rest is an help question. For example, learning how to handle customization of layouts, testing of several themes on the same site is a concrete help request I have, which was already partially answered here.

About this:

strictly speaking, you are right, of course. Still, if a few lines below those homepage buttons a newbie find something that a) is explicitly labeled as “installation instruction” or “to use this theme, start here” but b) that section ONLY says “cd themes; git something” the end result doesn’t change.

I did figure out how to proceed, because I am a novice only wrt Hugo, but a real newbie will just be frustrated as I said. Yes, it’s not an help question, just an opinion.

Hello all,

FIY, I just “resurrected” the general issue behind this topic in a post linked from here: Theme standardization and “compatible” comments