Difficult to say. There are many things I need to find out myself and so far I think I’m getting the picture. One question however I have asked myself and did not find any answers that made it clear to me is how to build hiearchical static pages with appropriate navigation. E.g. with the hamburg theme you have blogs and then you have menus for static pages. Now I wanted to make some of the menus to point to another list of pages from which you can individually select pages, if possible with even more hierarchical levels like files and folders, and at the top a navigation bar should appear to make it possible to go back within the tree you have gone down. Like the “Home” button that apears when you have selected one level. I was reading about page bundels and thought that was giving the necessary grid, but up to now all variants I have tried (using _index.md at various levels with folders etc.) did not really match what I had in mind.
Another “mystery” that I have not yet fully discovered is where does Hugo start (file wise) and how the various directories and files are used. There is some info in the doc but I have not found an overview. Something I could print out and then navigate through while editing and adding files, as a newby you often loose track of what was clear only a few hours ago and having some sort of “bullet points” would speed the process, else I have always to go back and read again. Perhaps this is specific to my way of approaching new topics.
I think the first learning curve is around language / nomenclature.
Hugo is fantastic for using accurate terms such as archetype and taxonomy - while laudable, they’re unusual for anyone coming to this with a background in front-end code (frameworks aside - HTML, CSS and Javascript don’t use these concepts).
I reckon the second is the “lookup order”. This is hard for first-time users as we’re encouraged to start with a theme, my first question was “why does the theme have the same structure as the root folder?” - personally I would have found it easier for themes to reveal themselves after playing with a themeless site. I don’t use themes in any of my sites.
Indeed. Perhaps a quick start guide without a theme would be more appropriate as it would reveal more of how Hugo works internally.
I think by “comprehensive” it means starting from scratch. I myself as a beginner of Hugo find it frustrating to read the official hugo documentation, too. They’re just pieces of information all over the place. The dots are not linked to see the whole picture. Same goes to when you want to twerk config.toml the way you want so you want to develop your own theme because the themes provided in the gallery are not perfect to your taste.(kudos to all the theme developers out there) Then you realize there’s too little resources to guide you through the process and you are kind of lost. That, is the biggest frustration.
I think that we have to remember a few things, which might suggest possible areas of action:
-
There is a difference between technical documentation (which is helpful once a dev knows a few things) and tutorials (a pedagogical tool learn) and guides (which might showcase special use cases, design patterns, etc.)
-
Hugo is young enough that it hasn’t fully settled (we are in V<1.0) so there is some terminology confusion/shift and functional shift (ex. do we use
.Scratchanymore? in what cases? is there a (needed) fundamental difference betweentemplates,blocks,partials… etc.?) -
Hugo is young enough that the community has not developed a Hugonic way to do things (i.e. like “Pythonic”). This makes it hard to make tutorials/guides that are long-lived or to have those moments where one says: “Just do it this way, for now… you can do it other ways, but this is better… learn more when you can…”.
One last thing: I think that some visual guides might help and might lay down the foundation for the core metaphors for how we all think about what Hugo does.
Yes. These are different things.
@zwbetz Totally! 
My question was a little more philosophical: if doing things again, would we build Hugo with those same elements with the same about of (or lack of) difference between them? Or would a fewer number of core components suffice (maybe with some additional functionality) (My opinion is that they are a little too similar, but maybe I’m missing some deeper functionality or scoping stuff. I guess I’m looking for the clarity that the “branch” vs. “leaf” metaphor provides when thinking about content.)
I guess here is an open question to the group:
What are your fav. examples of Documentation? Guides/Examples? Tutorials/Comprehensive Courses?
for me:
Documentation:
MDN (of course)
Tutorials/Comprehensive Courses:
Rhino Python Primer (good introduction to Python and CAD scripting)
Nature of Code
Guides/Examples:
P5.js Examples
I think my biggest issue with the documentation is that it appears to be written in a bottom-up direction. There’s massive amounts of detail at all points, with no good overview (and the “Overview” pages are tables of contents, not overviews).
What I’d like, and what’s missing here as in so many developer-written documentation, is a stupidly basic summary of the terms that you need to get going, followed by a more detailed one with the same structure, showing all of the extra pieces and how they fit together.
At the moment, you have to read at least the first few paragraphs of every page with a concept defined in it, and then try to assemble those concepts together into something useful. Most of the time, you can’t even work out what the concepts are, because they depend on other ones. It’s overwhelming, because I don’t know which concepts do the things I want to do. I have no mental model of how the various concepts relate to each other, which ones are important, which ones are advanced usage. This is because the authors of the documentation haven’t delivered their mental model in the documentation.
A lot of the pages I’m reading in the docs are fragmentary and don’t flow at all well. For example, the “Content Organiszation” page: this is the first page in the content section after the TOC. It’s clearly important. However, literally the first thing on that page after the intro is a digression describing a new WIP feature in some specific version of Hugo, including a pointer to two other pages, one about page metadata and one about image processing. After a brief example showing filesystem-to-URI mapping, it then mentions “front matter” (not just undefined up to this point, but not actually mentioned in the preceding documentation), and various kinds of templates (ditto). Then there’s some examples of paths, using terms like “slug” which aren’t defined, even vaguely, until the next section of the page…
Basically, it’s got most of the information it should have, but it’s really hard to see how to assemble that into a coherent whole.
I guess what I’m looking for at the very top level of the documentation is something like this (and forgive me if I get everything wrong here – I don’t have a good mental model because the docs are confusing me…)
Hugo generates a website by taking articles in a directory structure (one per file), and transforming them into web pages. The resulting website has URLs reflecting the original directory structure. An article contains a body, written in HTML or MarkDown, and may contain some metadata (the front matter), such as the page’s title, its type, and whether it is a draft or not. As it is transformed into a page, the article may have a template applied to it, where the template provides a consistent page structure and content around the page content (e.g. formatting the title correctly, or putting the article date at the bottom). Templates may be selected on the basis of the page type, or where the page is in the site hierarchy, or the page’s language tag (e.g. “French”), or what language was used for the page body (e.g. “MarkDown”).
Images may be treated as article content, and generated one to a page. They may also be run through an image pipeline, for example to generate a gallery of small resized images linking to their respective larger ones.
While the URL structure of the site matches (more or less) the original directory structure of the source articles, additional directory structures can be created with taxonomies, allowing for pages to be structured in multiple different ways, each page appearing in several different places in the URL structure.
Then you can go into more detail on each of the italicised concepts, for instance explaining that templates have their own coding language (with link to the detailed docs on that). Also, showing some more about the ways of grouping pages (sections, collections, bundles?). Maybe something about the way that taxonomies interact with other ways of grouping pages (taxonomy templates? I’m lost at this point…)
Then show some examples of common patterns (blog, image gallery, corporate website) which show which pieces of the above you need to concentrate on in each case – no worked examples at this stage, but an explanation of how you would use the pieces to achieve the goal. For instance:
For a one-person blog, there would be a single top-level section to hold all of the articles. Then you would need a list template for the front page, to show the top-level description of the blog, and list the articles available, and a content template for the individual posts.
For tagging articles, the tags would be placed into the front matter of each article, as taxonomy terms. Links to collections of articles all having the same tag could then be generated by adding a “tags” section to the list template.
<link to worked example of this>
Nicely written, especially when you compare it to the current documentation where the overview is a list of links and the introduction doesn’t even say what a template is.
https://gohugo.io/templates/introduction/
You should keep writing and I am sure the forum will help. You have a wonderful ability to write at precisely the level and style needed. 
@darkling really great thoughts! I, too, think the idea of mental models are really important.
Another open question to the group (and @bep @zwbetz @RickCogley) : is this the right forum for this conversation, or is there a better place to have these discussions which might spur some work/projects?
Here is fine in my opinion. This discussion is not about developing hugo proper, nor is it bugs, so this seems like the right place to me.
To go from zero to functional would be helpful… 
The Quick Start guide should give a quick and dirty way to achieve this, however having gone through the QS walkthrough, I’m left with a blank after Hugo serve -D
To go from zero to functional would be helpful… 
The Quick Start guide should give a quick and dirty way to achieve this, however having gone through the QS walkthrough, I’m left with a blank after Hugo serve -D
Link to 2019 version.
@Jura I created an account just to thank you for sharing your articles. They’re really excellent.
Please spread the word. It is so good that you should be sued by not making people aware of it.
Regards.
Thanks @plicatibu, that’s very very kind to say. I’m glad you like the articles.
I hope not! 
I haven’t been that active with Hugo content lately. I still like the topic very much, but it so far it hasn’t lived up to my expectations to put it mildly.
Welcome to the Hugo community by the way! 
Hi I’ve just spent about 4 hours trying to get a basic setup working without success. I am experienced in HTML, CSS, JS, C, C++, R, VB etc - I was looking for a more robust way of putting together a static educational website, but after this I think I’ll go back to writing it all in HTML myself. Sorry but I just can’t get it to work.
Sorry but I feel just lost.
Thanks
Hi there,
It’s difficult to help you if we don’t know what question you are asking. “Something isn’t working” isn’t very descriptive. Have a read about Requesting Help to see how to ask for help.
I am also closing this thread now. Please open new topics for any new questions.