Documentation on proper theme installation and use

@davidsneighbour, I didn’t say Hugo was for noobs or should be. I posed the question, if it is a goal there is a little bit of work to do. If it is overtly NOT a goal–say so.

I have used 2 themes. The default theme (name?) just to start up and see how things worked and Casper Two. Generally, changing to a new theme entails creating the theme folder in the right place with the right name, referencing that theme by the correct name in config.toml. Also, in the case of Casper Two, the config.toml needed to be replaced to incorporate many theme specific settings (or the settings copied/entered under the right headings). Also, layouts, static, and resources need to be copied | updated into the right places. These steps are simple and obvious when you examine the sample site, but these steps are not automated.
Installed correctly, Casper Two is well-behaved but there really is no documentation for complete installation of a theme. It is sort of figure out as you go–or copy the sample site (assuming one is provided) and hacking away to get it to be one’s own site. It all works well in the end.
My question is whether you want to improve this process or not. Do you? You can leave as is and people will get it to work–hundreds, thousands? already have. Or you can decide it is worth improving the process and/or documentation. (Documentation is a fine start)
I make reference to poorly behaved themes as a concession to the maintainers. I searched this forum for help on installing new themes and found a long thread, the gist of which was you could not be responsible for themes. You can probably find that thread. I think that is an unsatisfactory answer.
I think you could define a standard for themes to meet and ensure for users that compliant themes (by definition, “well behaved”) will install and work according to the (new) documentation or by some sort of install script (very much optional and fraught with potential problems–see Ghost). And you could make clear which themes were compliant and quickly (probably ALREADY) there would be many such themes available to use.
By definition, misbehaved themes are not compliant and don’t immediately work by following the (new) documentation. They might be fine themes with nice appearance and behavior, but they require some additional work off the prescribed path. The theme author might document what additionally needs to be one or not–their choice. And Hugo maintainers do waive any responsibility to “make it easy” for such themes.
Lots of choices and variety is already available and possible. It seems nice and desirable to more thoroughly document theme install (especially switching for an existing “site”) and have a reasonable repertoire (YMMV) of themes that work as documented. The fact is Hugo is already close, but the original poster’s comments suggest that some more training wheels would be useful.
It’s up to you guys. The current situation is certainly sustainable for a certain, non-small set of users. Of you might decide that the payback on a small amount of effort is considerable and Hugo becomes that much better. I do think a noob path is well-worth offering, even if more restricted than Hugo’s full capabilities, but that is just me and beyond the discussion of theme install/config.
Hope this is accepted in the spirit it is intended–improving an already fine piece of work and extending the audience for that work.
I put together a fine process in which a single site-content folder is synced from Dropbox to a directory under snap, symlinked to var/www, and updated with Hugo. To be sure ONLY this one folder is synced by dropbox to my server. And, I have the Hugo site “integrated” (visually) with a ghost site–it is all one URL. Many viewers would not notice that 2 technologies deliver parts of the site. I am super happy. I think for blogs the headaches of ghost and Wordpress–as manageable as they might be with some extra goodies if one cares–are not worth it to me. The speed, simplicity, and security of Hugo are great. Hardly anything to ever upgrade. Much less config. Granted some additional experimentation was required to make it work, but I am super happy with the results.

@lewisl There’s a lot here, so I’ll tease out what I think is worth talking about.

First, here are the current instructions on how to format a theme’s README (which I think are good).

I don’t think it makes sense to set a standard which makes all themes follow a given layout. Because some themes are for blogs, some for portfolios, some for changelogs, you get the idea.

But, I do think having the following required sections in a theme’s README would be useful. These are “loose” enough to where they apply to all themes, yet can be implemented theme-specific:

  • Installation steps
  • Updating steps
  • Expected site layout, if the exampleSite layout is not sufficient
  • Configuration steps, if the exampleSite config file is not sufficient

Thoughts from others appreciated and welcomed.

Actually whenever you see a Demo button for a Theme listed on the Hugo website then this is a theme that works with the latest release of Hugo.

Hugo projects can have vastly different architectures. There can be no standard. The Ananke Theme in the Quick Start Guide is a typical blogging theme and that’s why it’s there in the first place.

Hugo is constantly improved by individual contributions to the project. The Hugo Docs in particular have lots of contributors and have expanded vastly during the past year with lots of working code examples, that weren’t there just a year ago

We recently had a Spring Cleaning of the Hugo Themes website and several themes that no longer had a working demo generated with the latest Hugo were either removed or upgraded.

I understand that you may be frustrated when first starting out with Hugo, but you also need to give it time. Read the Docs and try out things and if you come across road blocks then just ask right here in the forum about specific problems with a link to your Hugo project.

The above would make for an interesting Tutorial in the Tips & Tricks forum category. So if you feel like writing one in detail then please do.

My stuff works fine, as noted.

Seems like you are still sort of avoiding the topic with excuses. I hadn’t realized that “demo” pretty much proves for a given theme that it works—sort of obvious that this would have to be true. But, it doesn’t account for the steps
that got the theme installed so that it does work. The cleanup work sounds awesome (and a lot of work).

Themes are different and sites want different behaviours. But, Hugo generates static content and works with themes. So, it must be possible to describe how a theme is to be installed. A prior post makes this clear and had some great
suggestions for a bit of improvement.

There are a few posts about startup challenges. Decide if it is worth it to smooth the process—or even possible. You might even have a subset of themes that are recommended for starting out in a few obvious site-type categories (blog,
documents, picture galleries—no more than this).

Improvement is always a goal; perfection is unattainable and its pursuit sometimes harmful. I hope you realize I agree that there is no HUGE problem here. There is a modest problem with getting started; that is all.

I’ll try to document my dropbox thing. It’s really no big deal but it turns out to be simpler that using a full-fledged CMS intermediary site for my purposes with 2 authors and 1 site manager (dare I dignify my limited competence as such).

There are themes like the Hugo Academic Theme that are so vast that they have an entire website full of documentation.

There are other middle sized themes like Aether and Hello Friend that are already documenting most of the steps you mention.

I don’t think that we should make these sections required because this depends on the complexity of a theme.

Also I suppose that there is relevant guidance on the Hugo Docs. If anyone feels that they can be improved then Pull Requests are always welcome.

This is the mail I meant. Seems great—just a few little improvements…

Have you read the following Doc?

If you feel that this is can be improved then feel free to send a Pull Request here for review:

I think that the points raised by @zwbetz belong in the Hugo Docs -if not already present-.

@alexandros Good points. Yeah the academic theme is definitely an outlier in terms of documentation.

The referenced doc will certainly not work in many cases:

Please enumerate the cases where it does not work, and we will fix the docs. Also, this document will never cover all theme installation use cases. Our software is just too powerful.

We have no reason to make excuses, please stop framing the conversation like this. We are trying to move to solutions, and you want us to make an official statement on how user friendly installing themes is. It’s as easy as putting a folder in /themes and naming it in the config, but that simplicity allows for a lot of complex configurations, and we document them as we can.

The feedback of “someone should do something” isn’t helpful here. This is it, we are in flux, 100% all the time. Our docs live in version control, everyone can be bold, we can fix errors as we find them, and everything here is done by volunteers, of which you are a member! Congratulations! As a volunteer, don’t get too flustered by accusations of making excuses, we’ll get through this together, if we focus on solving problems and updating the docs. :slight_smile:

1 Like

This is unhelpful.

I listed the reasons the simple command line install could not work.

For a theme to be correctly installed, the config.toml must be updated and the correct layouts must be present. You can call this configuration of a theme. But, it is essential for a theme to actually work.

I find most members of this community to be arrogant beyond belief. Keep this tool esoteric and restricted to a secret cognoscenti if that makes you feel better about yourselves.

Alexandros and Zak were reasonable. The rest of you were haughty.

Waste of time to pitch in.

1 Like

I don’t know what you are reading around here, but from your two posts, I’m the person that interacts with you the most, so let’s clarify it in less hurtful terms than including the entire community.

And yeah, I sound arrogant when I get like this, and your post certainly got me like this (but I am fully accountable for everything I’m saying, of course! :sunglasses:). Because I’m not taking what you are saying serious. If I take what you are saying serious, then I have to do this huge amount of work to get to the crux of what you are saying, or I can try to show you the landscape, and hope you land where you need to be.

Aside: I take you serious. Just not this particular topic.

If folks approached this by saying, “hey, I had trouble installing a theme, can we troubleshoot this, and I will contribute it to the docs”, you’d have a dozen people at your beck and call, typing out answers from their phones on their breaks and every available moment. It isn’t a secret cabal, I don’t even know these people, and based on how this conversation is going, I doubt they’ll double-down on any close association! :wink:

In the original topic, one user expressed frustration at poor documentation. Believe it or not, we hear that a lot. My technical writer peeps tell me they all hear that, too, but they could be bad writers, so… and on the good days, a volunteer helper here blows past the rote criticisms and armchair editing suggestions, and helps the person get their answer. On that particular day, someone dog piled on the “poor docs”, and completely hijacked the thread to get their own answer. And then your post, after the we solved the hijacked question!

It wasn’t great timing. It made me want to give undue attention to it, in hopes you’d find the crux of your issues with the more mature members of our haughty(nope, still just me!) community, like @alexandros and @zwbetz! :slight_smile: But then you kept saying things, like we were making “excuses”.

Excuse me an American moment while I take off my earrings and say, “dude, back off, huh?” Like, there are responsive souls trying to help you. Please stop criticizing them, everyone, anyone except me. We got beef, okay, that’s too bad (and I sincerely mean that, this was supposed to be fun, I’ll linger on lessons from this and become a better person, for sure!), and I’m gonna get out of here. But please be mindful of what you are bringing to the discussion.

:rainbow: :rainbow: Remember that video, that person was so happy to see those double rainbows!

Hugo is not for newbs as mentioned above, or people who don’t read thoroughly. Those who do, always tend to figure it out. Also, the docs are not prescriptive, so you’re not going to find exact instructions for every platform, obviously.

It should go without saying that this is open source, so if it needs improved, jump in and write (and maintain) any tutorial you see fit.


Know when to stop. I didn’t even have a problem. I had empathy for another poster.

I pointed out that Alexandros and Zach were very helpful.

Suggestion: Instead of your obvious snarkiness, say: Thanks for your input. We can’t get to this for a while. We’ve cleaned up the repository of themes, standardized theme readme’s, and we periodically look at how to make things easier.
We’ll consider this when we prioritize other work.

You could also point out that the forum is meant for very specific “how do I…?” questions and not general suggestions. You might have a place for more general suggestions; you might not.

The suggestion closes the discussion and isn’t impolite.

Several people were very emphatic that Hugo was NOT for noobs. OK. It’s fine to be explicit that way. C coding is not either. Generally when you have a tool as good and useful as Hugo you might gradually undertake to enhance its popularity.
But, you don’t have to.

At this point you’ve made pretty clear that suggestions aren’t welcome. I got the message.

I’ve built the same theme for 3 different platforms. Hugo, Jekyll & Gatsby.

I can say that Hugos theme contribution process is the most rigorous because they actually build theme locally and if it’s not done to certain standards it will fail and the PR will get rejected.

Jekyll and Gatsby theme directories just allow you to update a .json file with a link to your theme. They don’t test if it builds or anything.

So I think that’s a big positive for Hugo Themes.

That said, even Hugo themes that pass and make it into the directory will have often need changes to the config file to run, so yeah if you just clone a random theme and try and make it work with the quickstart tutorial you might hit a roadblock. But would this be different to using a random Jekyll or Gatsby theme?

1 Like

Given some of the tone of the discussion, I’m not sure if my response is actually useful here - or if it would be better in a separate thread. I’ll try here.

When I was looking for themes, too many just had the install instructions (git submodule/git clone …) and a comment about copying the theme.toml from the theme. I’d like to see more focus on what the theme is for and what the parameters are for configuring the theme.

Also I’d like to see more complex example sites for the demos. Too many themes I looked at, looked good with a few pages, but clearly didn’t organize to handle a 100 pages the way I thought they should, never mind my goal of 10,000+ (generated) pages. Having a more complex demo would have allowed me to see that before trying them. I know there are plenty of themes that are designed to handle a small sites and I am not saying that is wrong - just a different use case than what I need.

Hi @Warren

Perhaps you meant config.toml?
Also, what themes in particular do you feel need doc improvements?

The nice things about Hugo’s lookup order is that a given theme template can be easily overridden to meet your needs.

I do very much agree with this remark, that the documentation is lacking, not only for this theme but for the complete hugo ecosystem. I assume hugo is shared in the hope it will help a lot of people and thus become a success. For success you need excellent documentation, especially for entry level experience and knowledge. Otherwise your adoption will be too low and your wonderful tool will be slowly sinking to the bottom of our admiration. Big waste for all who put in lots of effort and time.
I have some 12 years of part time experience in web building and maintenance with Drupal, HTML/CSS/JS/PHP and Joomla and now Hugo, for over two years now. And the thing is, as much as I wanted it, I don’t have a site up in Hugo yet, just too difficult to grasp where and how to do what with the tool, especially the templating side of things.

Please guys, document!