Using Hugo

Edit: 2023-05-29

If you want a walk through, instead of a reference guide, I’d start with Hugo’s Quick Start. Then I’d reference its External Learning Resources. This page has web based, video based, and book based resources for Hugo walk throughs.

These references more than make up for any criticism I had on Hugo’s documentation pages and are where I should have started.

I found Hugo’s Quick Start page concise and easy to use. I quickly had a website up and running. I get the idea of the branch and leaf directory structures. What I found a little challenging to do was format a page in any fashion other than the default.

For instance:

  • How do I change the Home link at the top left of the page?
    • I believe it’s by modifying the homepage template.
      • Edit: No, that’s not it. I modified config.toml and changed title = to “Home”. I’m not certain yet it that changes anything else about the site. . . like making internal variables see the site as “Home” or external references to things like social media see the site as “Home”.
    • I’ll need to dive into Go’s html templating to see how to do that.
      • A link to Digital Ocean’s tutorial for Go HTML templates.
      • Mostly I want to create the templates, not dive into Go. I’ll post something more relevant if I find it.
  • Can I make Home an icon instead of text?
  • Can I make the main menu at the right of the page align left, just after the home icon?
  • Can I make the home page more of a static page than an index like page of all the sub-pages.
    • In the content directory one would use index.md instead of _index.md to accomplish this

While I’m sure Hugo’s reference style documentation is great, I think I would’ve liked a quick How To on best practices for actually using Hugo once it’s up and running. For instance, do I modify the Ananke template files directly, or is there some other way I should be setting things up specifically for my website?

From Ananke’s readme, it appears I shouldn’t be modifying the template directly, which makes sense. I would’ve liked a little direction like this directly from Hugo’s documentation, even if it is a little. . . fundamental or obvious. It’s probably in there, I’m just not sure exactly where.

How do I setup

  • A blog?
  • A technical site with a table of contents or listing of pages on the left, similar to what we see at Hugo’s own documentation pages?

I would’ve liked to see a few common layout problems and show examples of setting them up with Hugo. Then dive into the reference.

TLDR; Conclusion:

To get a Hugo site up and running quickly it’s best to:

  • Use Hugo’s Quick Start page to get the site going.
  • Use the Ananke Theme as a replacement for the Quickstart guidelines I was looking for. Download the demo site and see how they did what they did with it.