Documentation on proper theme installation and use

feature
1

I hope this points out to the powers-that-be how lacking the documentation is and how the tone of exuberance around “it’s so easy” is misplaced. I didn’t have the difficulties in this post as a git and GitHub user. But, I started with Ghost-II theme and there were a few things missing, which I resolved by studying an example site.

The documentation on proper theme installation is severely lacking. A lot of excuses are given about how themes have independent authors who “can do anything.” Sure, they can–but you don’t have to include their themes in the promoted, default theme repository. Wordpress is notorious for broken themes and plug-ins. But, if you download a theme from their official repository, it is very likely to work–no warranty of course, but someone has tried it and clicked through the basics.

You could start by documenting the steps to install and use a well-behaved theme, which are pretty easy once understood. As for poorly behaved themes–don’t bother. You already have enough well-behaved and good looking themes. If it becomes a condition of being included in the official repository of themes, then more will become well-behaved.

All in all, this is a good product. You just have some work to be more realistic about the noob experience. It should be as easy or MUCH MORE SO than Wordpress, especially as Hugo is inherently much simpler than WordPress. And don’t get me started about Ghost: also nice, but a bear to maintain if self-hosting.

Take all this with a grain of salt: you might not WANT just about any blogger to be able to use it. You could legitimately decide it’s for developers only. Entirely legitimate–but you should say so if that’s what you intend. If not, then do a quick push of 4-6 weeks to really streamline the noob experience. It’s a simple product so you’d make a ton of progress in one push. (Simple doesn’t mean limited or incapable: it’s a simple pretty clear model–simple by design–a good thing.)

2

I split the initial thread into a few topics. I put yours on it’s own, and in feature, since it is a request of the “powers-that-be”.

We are as ashamed as we are gonna be. We can’t feel your frustration any more. Please make the documentation better, for all of us! :slight_smile: We also have a plan:

Let’s do it! I’m personally really busy, so I’ll copy edit. Please use support to describe any walls you run into, and then we will knock out each one as they come up. Fully documented. Yes! :fire: :fire: :fire:

2 Likes
3

Which ones are the poorly behaved themes in the theme repository and why?

It would be best if you opened an issue at: Issues · gohugoio/hugoThemes · GitHub

So that I can take a closer look to the themes you mention.

2 Likes
4

Hugo is not for Noobs. And especially not for anyone comparing it to WordPress. Start lower. Like Ghost or Jekyll. Then after a while have a look back at Hugo.

1 Like
5

@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.

6

@alexandros,
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.

7

@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.

8

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.

9

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).

10

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.

11

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

12

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-.

13

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

14

The referenced doc will certainly not work in many cases:

15

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
16

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
17

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!

18

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.

2 Likes
19

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.

20

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