Minimum Viable Hugo

Hugo is a web framework which is frequently used to generate content from Markdown. This repository helps new users get started.

4 out of 5 web devs have experienced the following:

"Hugo sounds great! Let me try it out!"
"Okay, I made a new theme and a page in content/!!"
"Running hugo server -D now!!! ... Where is it!!!!"

This repo aims to fix that.

Quickstart

Updated October 2023 for Hugo v0.119.0. Works on a great deal many older versions as well.

# Start a new site.
# We --force because this will complain
# if *anything* else is in the directory,
# even something so meek as a freshborn .git/.
hugo new site . --force

# Make a new theme. Tell Hugo we want to use it.
hugo new theme minimum-viable-hugo
echo "theme = 'minimum-viable-hugo'" >> hugo.toml


# If you're on Hugo v0.118.0 or later, you can skip the next two gotchas.
# But they won't break anything, and may even teach you something.
# Check with
hugo version


# GOTCHA #1: Your root page is called _index.md.
hugo new _index.md
echo "Lorem ipsum dolor sit amet" >> content/_index.md

# GOTCHA #2: Hugo needs to be explicitly told to
# serve content from _index.md.
echo "{{ .Content }}" >> themes/minimum-viable-hugo/layouts/index.html


# Serve the site. Don't leave out the -D yet.
hugo server -D

Then go to localhost:#### in your browser and you should see it.

If you look at content/_index.md, it will look like

---
title: ""
date: 2023-02-27T18:21:50+02:00
draft: true
---

Lorem ipsum dolor sit amet

Change draft to false. Then you'll be able to run your site with just

hugo server

Advanced

Programming _index.md

There's nothing wrong with using Hugo and _index.md just to create one giant, plain, HTML page.

Eventually you might want to start adding things to it programmatically, using the YAML frontmatter. That's where that layouts/index.html comes in again.

If getting _index.md to print content is the "Hello, World!" of Hugo, then editing a layouts/ file is its FizzBuzz. It gives you the minimum viable mental model to start digging in and figuring out which layouts/ file you need to edit to do what you want.

One last tip: Keeping HTML comments

Hugo is designed for professionals. As such, any comments you add to a layouts/ page are stripped out by default.

However this can make learning the flow of template file to template file hard. So here's a workaround:

{{"<!-- from layouts/index.html -->" | safeHTML }}

And here's us looking at the comment in the source code of the page: