Hugo 101: Slowstart for beginners

I noticed that on my last drive-by :slight_smile:

After it gets looked over by the forum, do you want me to do a PR to add it to the docs?

6 Likes

Nice tutorial @michael_henderson. Looks good overall, just have a few small tweaks for best practices.

Instead of doing {{ .Permalink | relURL }} you can use {{ .RelPermalink }}

And instead of {{ .Site.BaseURL }}/posts (and related occurrences) you can use {{ "posts/" | absURL }}

This will handle when someone does and does not have a trailing slash after their base URL

5 Likes

@michael_henderson. This is great! I’ve always thought you and I had similar sensibilities about what a good docs site can provide for all manner of end users. Hugo should be positioned as a powerful tool for beginners and professionals alike, and I think the “slow start” does well to inspire the former. @budparr had mentioned the idea of a robust “guides” section some time ago; I’d be interested if he would agree to this being a prime candidate for such a section:

Good suggestion. I made the updates to the post. (I’ll update my repo and confirm that I didn’t introduce typos :).)

Edit: repo updated. Thanks again for the suggestions.

1 Like

Absolutely!

Would this be suitable for the reading reference after it is included in the docs?

1 Like

@michael_henderson A few ideas, let me know your thoughts:

  • Putting the final project files in Git, that way someone can grab a link and clone/run the finished project (this would also allow a live demo via Netlify)
  • Changing up the CSS (but still keeping it hyper minimal) to something like that of http://bettermotherfuckingwebsite.com/
1 Like

Yes. If I space out doing it, since it is a wiki I think it can be done by most if not all members, so, you can ping me to do it, or, just do it. :smile:

It is in a repo (the link is hidden in the foot.html template - https://github.com/mdhender/canvas).

I’ll look at the CSS.

1 Like

Added the CSS and fixed a couple of typos. Started on adding Windows commands, but I don’t really have access to a Windows 10 computer at the moment and don’t trust my memory, so I’ll update them this weekend.

2 Likes

Thank you, very useful.

Does this need to be updated to reflect the changes to how .Pages works on the homepage in version 0.58 (and later)?

https://gohugo.io/news/0.58.0-relnotes/

2 Likes

Thank you for the walk-through @michael_henderson!

There’s still some typos in this version of the tutorial compared to what is on your github repository (e.g. the unclosed list items in layouts/article/single.html and layouts/post/single.html files).

Could you please update this version as well :blush:

1 Like

The where clause in the index file is very misleading:

This actually looks like an iteration over posts. Instead this seems to be an iteration over all sections called posts. Which doesn’t make much sense, there is ever only one. Is there a clearer way to express this?

1 Like

Actually it is an iteration over the pages of a section called posts.

It may seem misleading to you but it is not really. Also note that the guide in this topic was written years ago and several things have changed in recent versions of Hugo.

The proper way for a new user to get introduced to Hugo is to follow the Quick Start guide on the Hugo Documentation website.

If you want to iterate over all regular pages then you can range over .Site.RegularPages

See more at:

Thanks for the advice, though …

The qickstart-guide doesn’t give any clue as to how to start with your own templating. It’s not obvious what the layout folder is supposed to be for if it concurrs conceptually with the templates mechanism. Michaels guide is close to the only thing to find on the internet, which explains how to get it all together consisely. From a didactic stance the Hugo documentation is close to useless for beginners. No human on this planet has the mental capacity to get all the disorganized concepts together at once. This is by far not how learning works. So people are forced to go on a trail through the thick jungle of Hugo terms and patch a mental model of it together by themselves.

Which is quite bad honestly, because Hugo is a neat technology.

2 Likes

You can get involved trying to improve the Documentation.

Pull Requests are welcome over here:

And by the way Michael’s guide is missing a few of the newer features as I already said above.

On a final note I do not see a thank you very much for pointing me to the .Site.RegularPages variable.

If you are going to be posting here you need to be mindful of your language and be polite.

If the above is beyond your ability I can always ban you from this forum.

You can go vent elsewhere. But not here. Not on my watch.

Sorry to be so straight forward. I don’t want to insult anyone, I just want to point out where the documentation could be improved. Thanks for pointing me to it. Though I’m not able to use it properly due to a lack of understanding what “regular” means in this context. Also the documentation page you linked explains terms with more vague terms that aren’t explained further then: leaf bundle, branch bundle. I can imagine what leaf and branch means, but there’s no explanation what “bundle” refers to. Another example I just stumbled upon: defining a variable in the form of “$varname := …”. This just works, but I couldn’t find documentation about it. The variables section doesn’t mention it.

I might even try to stitch together a tutorial after knowing enough about hugo. Thanks for the fast response.

For an explanation of the bundles concept see: Page bundles | Hugo

In short Page Bundles are a way to organize content.

For example for a project with the following structure:

.
├── config.toml
└── content
    ├── about.md
    └── portfolio
    │  └── index.md
    └── posts
    │  └── post-1.md
    └── photos
        └── _index.md
        └── photo-1.md

.Site.RegularPages would list the generated pages of the following content files:

about.md
portfolio/index.md
photo-1.md
post-1.md

Regular stands for non-list pages or plain (leaf pages).

To create a leaf page bundle one needs to use a mandatory index.md .
For entering meta data on a section list (branch bundle) one needs to use an optional _index.md.

To limit the pages rendered by the .Site.RegularPages variable one can use the filtering techniques that are mentioned over here in the Docs.

Great! :+1: