I’m a Hugo newbie who is experiencing tutorial frustration. The current tutorial seems to be like “here’s how you can get this beautiful theme up and running in no time, and here’s how you can replace the title with your own title, now good luck!” instead of teaching the underlying principles of the system in a linear fashion.
Is there a good tutorial that would teach me how Hugo really works, so that I can eventually make it do what how I want? I have an ongoing gripe with open-source “tutorials” that just want to show off the most impressive thing the system can do in the least amount of command lines, without actually teaching anything about said system…
(PS: My frustration is echoed in this old thread by eaigner. Thought I would revive the topic in a new thread.)
I don’t speak for the project, but I don’t think there is. Hugo is a templating system, with a lot of flexibility, and it is difficult to fully understand. Fortunately, most don’t need to grok it to get started using it.
Please read every page of documentation. It lays out the web of information you’ll need to understand the nuances of templates and formats and all that. And then you’ll be able to let us know how to improve the docs!
That is not the case with our quickstart (it isn’t that impressive, feature-wise). It is, actually, closer to the thing that most people ask us for, including the thread you linked to. Most of the time folks are not asking for more detail, but instead would just like to paste a few lines and have a site up.
If you see that as a pattern in software projects, it isn’t an accident. It is the only marketing projects have.
Do you have experience with another static site generator? There is a common pattern of processing content files via templates, and if you know a different system, let us know, maybe someone can translate vocabulary between them.
But definitely read all the docs. I personally think the most important doc we have is the introduction to templating. I would refer to that page often, until I basically memorized it.
@maiki Thanks for the “intro to templating” tip. Right now I am working my way through the giraffe academy video tutorial. Have also downloaded the hugo skeleton site by madranet, which could help me.
I have some previous experience with Jekyll, but never moved much beyond using a predefined template there. Now the time has come where I have to move beyond a predefined template, and Hugo seems to be the way to go.
I’m all for marketing, by the way, since the more people use Hugo, the more support there will be for all users… I just wish that open-source offered something beyond the “see, it works!” type of example. And even open-source docs are good quality, they always tend to be nonlinear, with no obvious entry point.
(Btw, when I said that eaigner was echoing some of my own gripes I was referring to his quote “not everyone wants to use a predefined template - in fact most will start out creating their own templates”. This is precisely me!)
Anyway, Hugo looks like a lot of fun… my frustration is precisely caused by sensing that Hugo must be really fun if you grok it, but that there is no clear road to said grokking…
The thing is - devs are busy catching bugs, fulfilling feature requests, and adding new features that are requested by us, the user. Striking the balance between that (development) and writing detailed documentation/tutorials about everything in that particular piece of software is really hard. Thus most of the devs/projects you see will just showcase the most impressive thing in the system, as it is the thing that differentiate it from the others (Just like a new product, you don’t tell the customer everything what the product can do, you will only tell them what the product can do the best.)
As for Hugo, reading all the docs (which are really, really well-written) and sometimes going through the discussion on GitHub issue (or this forum) will definitely help a lot. Utilize the powerful search bar properly will also ease your journey. And the best way for learning anything, is as the old cliche that goes “learning by doing” - build your own site, poke around with the theme you downloaded, make mistakes, ask questions, or occasionally go through the go docs, and hopefully you will be able grasp the theory that you wanted.
PS: All of this are my own humble opinions, and do not anyhow speak for the project.
