I just wanted to express my frustration with the hugo tutorial. 2 hours passed, and I’m still unable to produce anything near a working hello world site. The documentation makes it nearly impossible to understand the relation between content and template because either a template example is displayed without the matching content example or vice versa.
Why not provide a minimal example that renders a website with 3 pages in a minimal custom layout?
Not everyone wants to use a predefined template - in fact most will start out creating their own templates.
Been there. Hugo is a bit Drupalish (if you happen to know this CMS system) in that it actually all makes a lot of sense and is really cool when you get to know it, but initiallly that’s not evident and things seem confusing.
I think it is the trade off when you have very flexible systems that don’t follow all the rules (which is a good thing, otherwise why have something new?) and the new approach and terminology needed to learn it.
You are not the first to suggest better tutorials or ways of making an easier start. So ideas here could be very valuable.
My initial thoughts on the
are that it would not be enough to get uder the surface of Hugo, to show what makes Hugo different to other systems.
I completely agree about pre-defined templates, and this in my opinion something common with many systems (the assumption that people willl start with a predefined template). It sounds like a tutorial that specifically does not start with a template would be a good idea.
Thank you for your feedback. As hard as we try, it’s impossible for us to have your “blank slate” perspective again. We would love any details or contributions you can make to improve the tutorial for everyone else.
Even just a list of questions you have would be super valuable.
I understand @eaigner’s frustration. I’ve always developed websites the “good ol’ fashioned” way.
I would absolutely love to get into a static site generator and was told about how fast and lightweight Hugo was.
The issue I’m having is that as just a plain old web designer using HTML CSS & Jquery it’s hard to wrap my head around the flow and structure of Hugo.
As far as I know there isn’t a layman’s guide to Hugo. The documentation is catering to knowing things about the language and processes beforehand and there are no contextual examples.
I guess to give a quick scenario – Basic web designing, if someone asked how to turn all paragraph text blue. Most would simply tell them to write p { color:blue;} which is fine if that person knows what CSS is, how to link a spreadsheet to their html file, inline styles or even how to use tags. Without that other knowledge the answer p { color:blue;} doesn’t truly help. I feel like the documentation holds all the answers but I don’t know how to properly use the answers given.
Be it that I am ignorant in such things and I know it’s hard for you to have the “blank slate” perspective it may just be that I need to gain that knowledge elsewhere before tackling Hugo and if so please let me know because I would love to start learning.
Good point, and food for thought. I think this though is the crux of all technical documentation and manuals. Where to start? It can also be too early in the process / too simple to be helpful.
If in your eample the reader did not know what CSS was, then I would say it is the wrong documentation for them (rather than the documentation being wrong).
I don’t agree that non familiarity with command line or static site generators in general is the audience to focus on. I would have said both are prerequisites to being able to use it, not things to work around.
I hadn’t used command line before static site generators, but Hugo docs wasn’t the place to learn about that, nor about the reason / concepts for static site generators.
I think what people won’t know at the start is things like… why the folder stucture needs to be a certain way, what happends when an .md file is in the content folder (or sub folder) and the matching layout folder has an HTML file that references the content, and why list or single is chosen.
And to demonstrate that to new users, I’d say its like a good fiction writer’s approach … show, don’t tell.
The docs do cover a lot (plus what I mentioned) but it is a lot more telling than showing.
This topic seems also to be part of the discussion of how we should restructure the docs.
I would strongly advertise to newcomers a starting guide that describes in an understable way (for beginners) how to setup a website with Hugo (by revisiting the current one). In addition, I would create a list of small “recipes” á la “How to do xyz” to cover the most widely used features. And this preferably described in a nutshell but with all required information.
The second part would be the regular docs. But they are part of the linked thread above.
@eaigner are you still struggling with the docs? @stiobhart created a commentted sample site. Read this thread for more information.
It would be worth gold if you could explain which parts confused you and what you would exactly revisit? Your perspective may uncovers aspects that more experienced users maybe wouldn’t consider. Feedback is appreciated!
Just some feedback from someone who last week hadn’t heard of Hugo
I’m a part time web stuff person, my job is as a Technical Writer, so I know how difficult it can be to pitch things at the varying skill sets of users that may want to use Hugo.
I’m comfortable with HTML, CSS, JavaScript etc, as well as command line stuff (El Capitan threw some issues at me when installing Hugo via Brew).
The most useful thing I found was the Quickstart video. This was a lifesaver, and I was hoping to see other videos or tutorials that would build on that. However I then spent quite some time trying to work out how the hugo-uno theme worked.
There is a lot of functionality with Hugo and it would be great to do some of step by step build up of knowledge, with links to more in depth documentation elsewhere.
If you start from the assumption that not everyone is familiar with the technology, using this approach builds their confidence, and therefore expertise.
Hugo is a different beast to get_iplayer in many ways but in others they overlap and I believe the principles should work similarly.
I’m not sure what exact help I could give to restructuring the docs/site but if there’s a concrete end state I can see what I could offer in terms of working towards that.
The doc is OK, but not great. I’d love to see more examples. Most of the examples from the doc seem incomplete or are link to the GO website. For example, I’ve been having a hard time understanding the “index” function but examples in the doc are not clear enough.
for me, the hardest part of Hugo is how themes are “incompatible” with each other, or not documented, and how there is no way to discover it than to try them one by one.
By this I mean that, e.g.:
the same parameter, e.g. your twitter account, must be defined in different variables if you change theme, or formatted in different ways. EG in theme A you write "twitterid =“mf” in theme B it’s "twitter = “mf”, in theme C it’s “twitter” again but you must write the full URL, not just “mf”… Then there are things, IIRC like “site slogan” which in other themes is called “topline”, and so on
some themes automatically list in the home page what is in the post folder, others what is in the archives folder, others what is in the blog folder…
menus? Some themes don’t visualize them .Some visualize what you put in a data file.
how to put custom text in the sidebar is another thing that changes without evident rule from theme to theme. When a sidebar is supported, that is. But to know that you have to run the theme
some themes have no “img” shortcode. Others have “figure”. Some display as thumbnail in list mode what you define as “thumbnail” in the frontmatter, others do the same thing with what you define as “image” in the frontmatter
finding where to put a “translation” link is a totally different exercise from theme to theme
combine all the things above, and the net result is that what looks usable in one theme can become an absolute mess in another (assuming hugo doesn’t abort) and the only way to understand and fix what happened is to go head first in the template sources. And restart if you want to try another theme.
ALl in all, this is much more time consuming than it should be. I have no problem to study and hack source code, but having to do that because the same thing or basic function isn’t supported or has a different name… doesn’t feel good.
The only solution I can suggest is to at least NOT showcase at themes.gohugo.io any theme that doesn’t follow some UNIQUE, basic naming/files layout convention. For example, only themes that support menus defined in the config file should be there. In practice, which convention to use, is up to the real experts to decide.
FIY, these are some of the themes with which I experienced the problems above:
