Request: hugo with a 'hello world' example?

feature
1

So looked at hugo several times.

It seems right on the verge of getting big adoption, but also seems like it could use:

  • better examples
  • better docs

This is in no way an insult to docs or examples.
Hugo has extensive docs and many themes.

Issues are:

  • docs need a unifying image that illustrates the theory or concept of hugo content assembly
    • have used many templating systems but hard to fully grok how hugo assembles content without reading hugo’s source.
      • if that is the point (which it seems like it could be idk), but if so, seems like a missed opportunity to grow users and contributors a lot
      • happy to create this image, if somebody wants to write a markdown (before writing this i googled a huge variations of hugo workflow, but only found out how people who switched from something else to hugo were using it… many of whom switched back! :slight_smile:
  • hugo either needs a hello-world theme (or it needs to rename the current getting started theem to ‘hello-world’)
    • a lot of hugo customization/implementation is currently done by themes
    • this is fine, but it’s passing the buck huge
    • also it doesn’t convey how extremely basic things like basic color scheme or background/logo images might be handled.
      • this is a huge part of every website.
        • if hugo is mostly about generating consulting for guidance on basic things, ok fine.
        • just seems weird that when it’s easier to write a new go program than to modify the color of the default hugo example, this is a huge area for improvement
  • will continue to look at it, if we make clear will try to post somewhere for others.
  • seems like it could overtake so many different options, just missing a few things (it’s hard to understand what of these things are desired vs not, from the theme… which is designed great for flexability but is not explained in terms of a hello-world)

anways, lot of efforts went into submitting this. appreciate anybody who appreciates what is being said here. will respond likewise. best and thanks to devs for efforts. have looked at it MANY times. need a bit more to advance i think imho.

best

List item

1 Like
2

I think part of the confusion stems from the fact Hugo is more like ‘make’ than Visual Studio (for example). By that I mean Hugo processes layouts, contents, and resources and copies static files to produce the output. It is not, and is not intended to be a standalone solution to creating websites (as I understand it).

I seem to recall some discussion of moving things like the internal templates (and default empty site generation?) out of the Hugo binary (call that “Hugo core”).

On top of Hugo core you have themes (or sites that implement layouts directly, without using themes).

I believe part of the difficulty folks have with the documentation is that there is a tendency to view Hugo as full package, rather than a (vital) component in a complete package.

That goes back to the “what is Hugo” point you mentioned, but I think documenting a particular theme as if that were Hugo would be a mistake.

One thing I am planning on working on is a ‘skinnable’ theme — that is a theme that support different frontends (not just colours, but the whole ‘look and feel’) but where the bulk of the work is the same in the ‘backend’. I have parts of that with the module stack I have been working on, but the theme itself I haven’t started.

I am, however, not a Hugo developer (or really a frontend developer for that matter; this is ‘hobby’ work for me), and not the most active member of this forum, so I’m not sure how much traction it will get.

1 Like
3

cshorednaiel thanks for your response, but it doesn’t seem you understood my post.

i’m gonna summarize my other thoughts here for anybody else who has come across same issue.

one such user pm-d me a link to a from-scratch hugo site guide, which is closer to idea of a hello-world-level example. ( i realized later that a hello-world for hugo probably shouldn’t be a theme, i changed subject line and category to reflect this).

here is the guide the user mentioned.

i also found this very simple hello world site request that is similiar and answered by same author of blog post above.

i actually think what would be more helpful is just a flow diagram showing how (eg in what order) hugo assembles content from directories to make a page. i can sort of understand this after a few hours reading the docs, but i’m certain i don’t totally get it. generally speaking if you have to read this much to understand it you’re losing a lot of potential users and devs who don’t want to invest the time.

in this thread, i see another user had the same issue and attempted to create something that is close (but not really specific, which would require understanding source to do):

not a flowchart, but attempts to show how parts make a whole

this image is much more specific (via this blog) but it only covers a portion of hugo building:
partial flowchart

If I find or create anything else will try to post here.

Ideally the developers would create this, because this could do it very quickly and it would be more accurate and again bounce off less new users for your project. (saying this as someone who helped outgrow two other vc-backed open source projects in a non-website space).

Anyways, definately seems pretty interesting just wish there was quicker way to get my intuition matching the developers, rather than trial and error and time as it seems. (and yes, there’s always a faster way to onboard new users).

will do my part if i can. thx again.

2 Likes
4

Huh, surprised to see that PlantUML generated diagram from my blog post here. :slight_smile:

2 Likes
5

yeah sorry i thought i linked to post also but appears i didn’t. fixed that thx for heads up.

6

I was addressing your second bullet point, rather than the first. The second seems to betray a bit of the misunderstanding I expressed:

To me, the first point is like saying ‘make’ is passing the buck because it doesn’t include the code for setting up UIs, and the second is like complaining that the documentation for a ‘C’ compiler like GCC doesn’t convey how to do a ‘real’ UI for prompting for user input.

Now, the first major bullet point and the diagrams you show are interesting, but the chances of keeping such diagrams fully specific and complete is about nil. Hugo is semver 0.xx.xx which means it is still in development and there are aspects of the Hugo’s processing that are still subject to change.

That isn’t to say a high-level approximate overview would not help a number of users, but it is important to remember that such a diagram would be informative not normative.

Now this type of diagram, and the kind of expanded ‘hello-world’ tutorial you mention (of which I think @zwbetz has done a good job of a basic version in the link you posted) would undoubtedly be beneficial new users of Hugo (with caveats I mention below), but it takes someone with time, energy,and interest to work on it. Hugo is not a commercial product and has no deep pocket funding for ‘productizing’ Hugo (which includes the kinds of documentation that seems to be looked for), so attempting to browbeat or complain documentation into existence won’t work (not suggesting that is what you are trying to do @bdpp, but others seem to be trying to take that approach), so making the ‘new user’ experience more comfortable has to be done by someone who likes doing that kind of thing, does a good job of it, and has the time and energy to do it (and put up with flack, because there will always be complainers no matter how much one does).

There are also a couple of caveats:

It is important to keep focus when creating such a guide. It should be focussed on those creating themes or who will creating their own layouts for one-off sites.

For those who want fully realized ‘modern/post-modern’ sites a separate effort to create a theme and a (sub-)community around a theme designed to do that would be more appropriate than trying to shoehorn that onto the Hugo documentation.

Back to your question about a ‘colour scheme or background/image or logo’: those are CSS / HTML design questions not Hugo questions. There might be specific considerations on how to make that happen using Hugo’s Go Templating and/or Hugo Pipes and/or support for PostCSS but those specific examles are very theme-specific and are not generic questions to include in general Hugo documention, at least in my opinion.

It’s important not confuse the ‘site assembly’ tool with a theme and documentation effort that would look more like a ‘website IDE’ (or the CLI equivalent, at this point). It still seems to me you are conflating a whole environment build around ‘make’ and a C compiler like Visual Studio with ‘make’ and GCC.

Would a more developed environment built around Hugo be useful to quite a number of users? Probably, but it would require that those interested in making that happen work on it, or pay to get it done, rather than expecting Hugo to become that.

Probably more than just 2¢ of my thoughts on this.

1 Like
7

cshoredaniel. i thank you for your help but this post is neither addressed to you and i have no follow up to your comments other than already expressed thx.

it seems like you have a lot your own thoughts on hugo. feel free to open up your own topic.

8

@bdpp — this is probably the closest thing to a “hello world” for hugo I’ve written.

Many folks on this forum have written similar pieces, or have playground git repos. (Like @kaushalmodi above).

You may not find the exact tutorial you’re looking for. But that’s okay. Once you find a theme you like, peek into their git repo and see how they did it.

As @jmooring had said before, experimenting is a good way to learn.

7 Likes
9

I am (one week) new to hugo and also I have my problems with the documentation and also with 3rd party blog posts and tutorials. Most of the latter just battling against each other about how to generate a website/blog with a minimal amount of code as possible. This helps no one. And other blogs/tutorials just show what can be done with hugo in the meaning of advertisment and feature firework. Also helps no one new.

What I really miss (even in the official docs) is the “big picture”.

A text (and maybe some explaining graphics) that explain the ideas, concepts and design descissions behind hugo. And that text also should explain the hugo terms (e.g. Kinds, page, posts, content, public, theme, layout, theme) and how they belong together. Explain does not mean to show up code. Nearly no code or shell content in such a document!
Explain the terms all together in one text and do not just link to the documentation. Do not make a list of all terms and explain each term with its list entry. Explain them together and how they are connected.

Think about to explain this to someone with the age of 6 years. :wink:

When a user understand the concepts and the terms it is easier for her/him to find the correct piece of information in the official documentation.

1 Like
10

uh ok. i respect you seem to contribute a lot so i appreciate that.

and yes ‘experienting’ is valuable as a general thing.

if you have nothing better to do with your time than learn hugo, then yes hugo is probably the right use of one’s time. :slight_smile:

i opened this thread to be about learning curve, not about left-most point on curve.

our existing content framework actually works and looks right, so it’s hard to invest time in hugo even though [theoretically] it should be easier. good reminder for any project tho.

there is definately a lot of room for improvement. whether it’s in hugo, a fork or just conversation. keep it short and simple. if this topic is not good, will start another.

hugo experiementers- please seek another thread! this is for people trying to accomplsih something in hugo in a reasonable (<4hr timeframe).

11

oh and i appreciate your latest link: Convert Your Plain Old HTML Site to Hugo | zwbetz

(different than other links mentioned)

12

So after reviewing this for more hours, here are updates:

  • like many other posters mention, hugo has pretty bad onboarding (probably a high churn/bounce rate)
  • the documentation- while extensive… is “off” (this from someone as professional developer, who knows go and has done html/css for 20 years)
    • not sure if this is because of a language barrier?
    • it’s very impractical, it reads more like a dictionary
    • although it has a lot of specificity in it’s organization, it’s impractical and not pragmatic
    • example, when looking at date formats… there is a lot of stuff written… but it’s not how to change a format or where, or what it would look like.
    • you’re basically constantly googling for plausible examples to try and hope they work for the correct version

We were able to take existing examples and modify them to start to import existing sites, but it was very trial-and-error. So many people have had this problem that there are tons of hugo posts explaining how to do certain things, but there is no carnoical example and they all use different versions.

Somewhat complicating things is that hugo itself doesn’t generate a complete skeleton. So the idea of a partial template (what other generators usually call compoents) is cool and seems well executed. But the hugo new site doesn’t create ‘partials’ by default!

So you’re constantly guessing and crossing your fingers. It’s super inefficient.

That said, this is the best resource I’ve seen and it should be included in the defacto hugo docs. It’s up-to-date with current version of hugo. It example of how to use hugo in a handful of commands and is both very simple and illustrative of important hugo concepts. (I do note that while it references the very thorough hugo docs, it doesn’t characterize their opaqueness and lack of practicality).

Put another way… if standard hugo getting started is the 1min guide, this resource is the 5min guide. I’m linking it again because it didn’t show up in google and I only found it because the other DM-ed it to me.

Actually wondering if it would make sense to fork hugo into another project that just wraps it with better example, a full project skeleton when doing ‘hugo new site’ and english-native documentation. (the first two are pretty easy, the last is big project but also why the developers probably don’t want to work on this)

13

TIME UPDATE:

  • so far have probably invested 6-7 hours figuring out hugo
  • during this time could’ve easily
    • built a complete website from scratch that looked the same and had same content in about half the time
    • posted probably a hundred updates to existing site using current framework
  • in general we don’t like to DIY unless we have real differentiated expertise. (knowing how to do advanced stuff is not same as having expertise)
  • hugo does seem powerful and seems like best option, but it’s weird that the documentation is so poor and the devs don’t seem to care or respond to basic questions like “what is a single image that describes how hugo works?”
  • also low hanging fruit would be having the full skeleton created by default, because that provides best feedback into the documentation

will continue to post updates based on this meager effort.

14

after building demo site with aforementioned resource was able to flip it to use current content wrappers from our current site framework.

using these as partials and modifying baseof caused local demo page to look perfectly correct to current site very quickly (5min).

however lots of small details to clear up before it could be deployed (links + normalizing relative urls, inlinng static resources, sections vs pages- hugo calls sections page-bundles- and other small things). attempted to resolve these things quickly using docs, but broke things so will come back.

hugo is one of those frameworks where it’s so close the borderline of whether it’s easier to learn or just build something, almost always this instinct is wrong but our application for hugo is very very simple, so it’s not great that it’s taken so long. [another ~20min here for superficial progress].

15

So at least content-wise this is close to create graphic such as mentioned:
layout lookup for regular pages

It’s a bit lacking as while it’s easier than reading source code, it’s not much.
Still could benefit from a single image that sort of shows how page is assembled, that new users could keep in their mind.

At present no plans to produce better docs since doesn’t seem to be a lot of interest in ease of use (or feedback of any kind other than laudatory). Will continue to post links in line with questions/suggestions and onboarding issues that are lacking.

At moment have been able to import most of a wordpress theme into hugo and much of content. Seems it will be possible to do everything, tho uncertain probably 75% of spent didn’t yield meaningful returns which again is surprisingly and not ideal.

Still uncertain overall if will actually flip sites over to hugo. It’s appealing to have an easier to install framework that is more in line with everyday tools (not to mention have it be markdown native). and at least in our case not having to give up anything other than a few guis and some plugins (which we mostly don’t need).

will keep posting relevant updates.

16

90% there.
then tried to do static content with hugo. (two column table w/image plus some bullets)

it will partially display in all number of ways.

if you follow the hugo docs, it will eiter say "html rendering not support " (the most natural way, the founder knows of these weaknesses and hedgtes with ‘there are going to be XXXX of web frameworks.’). genius- full donald trump on accountability.

in his defense, still trying to use this bc??

  • 95% ready to roll to qa… but can’t support a static page?
  • hugo doesn’t really have content, it has ‘text-slugs’
  • overall feeling like a chump for trying hugo
    • all but two of responders here are clueless
    • founder @bep accepts all issues and welcomes using different frameworks (originally thought this was just request to review other frameworks, not seems more like an invitation to create replacements)
  • templating in go isn’t that complex, there seems to be a lot of issues regarding sub-problems in goldmark and hugo assumptions at large.

regardless, hugo is open source and has a familiar cli user interface to build on. it has what seem like some good decisions but 1) not easy to access 2) even when you access, the decison have huge amounts of embedded assumptions that contradict even most basic use cases.

overall, seems to lack some love and meaningful feedback. originally learned about hugo from netlify, but now netlify is recommending next.js instead, but that’s err-ing towards the front end of [J]AM-stack, vs backend JA[M]-stack.

irrespective of approach, ideology or priority… continuallly surprised by how little progress you make w/hugo for time spent. you can change any specific code or content from scratch, but just when you feel like you get hugo… oh here’s another thing you can’t do that would make life easier.

perhaps a sunk cost faclacy, but since most of site is there will try again.

will continue to post updates with what discovered.

17

as few care about results of specifics besides us, going to become more fine-grained in criticism and share upfront rather than just at end of hugo session.

here’s a typical hugo 404 w/ html content:

404 page not found

hah- you thought i was kidding and I am, because it’s just a 404. this is all hugo produces (IN LOCAL DEV MODE). beatifully useless

here’s what the actual server reports to stderr:

WARN 2022/04/05 12:21:39 found no layout file for "HTML" for kind "page": You should create a template file which matches Hugo Layouts Lookup Rules for this combination

ok, so this is obviously far more useful than the dev-mode webserver response above.
however it’s still useless, it doesn’t tell me anything relative to content being used. for example, while this is front-matter there is no ‘kind’ attribute. ok so there is a default attribute… but it doesn’t reference what to look at.

found this page: Template lookup order | Hugo

this page provides examples of what a ‘kind’ is, but doesn’t define it or say how hugo renders kinds:

Kind - The page Kind (the home page is one). See the example tables below per kind. This also determines if it is a single page (i.e. a regular content page. We then look for a template in _default/single.html for HTML) or a list page (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in _default/list.html for HTML).

(as an aside, it says ‘see the examples tables below’, but there is no link and if you search on the term again ‘kind’ you get nothing other than this paragraph, so the documentation… respectually sucks. could we try to improve it, maybe but no point if the dev won’t produce a caronical diagram of how it’s supposed to work. )

going to the table doesn’t help resolve the error, because it doesn’t use the same terminology.

anyways… this is the start of session not the end, but it does illustrate the bad parts of hugo. namely:

  • it’s too complicated for what it’s actually doing
  • @bep doesn’t [seem to] take much less solicit feedback
  • the documentation is sort of self-serving and inconsitent and too verbose for what is happening
  • error messages don’t actually refer to words terms that are useful in resolving things

too much time spent documenting this for now, really didn’t even touch the surface.

as i’ve said, based upon all the information i’m getting… it seems not too hard to fix. but it would require some sort of semi-definitive graphic or diagram that intuites how @bep expects hugo to work. and if he doesn’t know, well then I almost feel bad for him. luckily it’s open source and I’m saving this post as i write it. that’s the savior for anybody who is experiencing the same (which most won’t post to this level).

will keep posting updates.

18

@bdpp Here are some facts:

  • Hugo has a steep learning cure
  • The discourse is incredibly good (jmooring is amazing)!
  • In Hugo functions are removed and added at will, as it is below version 1
  • Error handling is pretty bad
  • Hugo has no clear scope (support for AMP, but not for pages from data… really??)

However, Hugo is the most powerful site builder I have encountered. You will not regret learning it.

Just hang in there!

PS. You might like https://hugocodex.org/…

19

@jvanloofsvelt lol, your facts are mostly your subjective opinions ftw. tho while you are agreeing with some of our collected feedback [subjecitve], you’re mostly rationalizing [if you need to respond, please create a new thread- thx].

point here (this thread) is to articulate a simple website in a cli-based static framework, using hugo as basis. starting to generate some ideas as to next steps, but since this is a ‘gohugo’ forum, it maybe goes elsewhere.

if you want to vent about hugo, please start a new thread. feel free to link this one, will try to learn from past mistakes and only +1 it or not.

not much in love with hugo. it’s like the 'aughts mp3 players in our opinion (mine is less than humble, but again so it’s @bep so it’s great that is the web! for moment we use wordpress but really, really ready to be done with wordpress for many reasons. if have to write some code… well I’m loving this thread [archiving now])

20

@bdpp you tagged the wrong person I think