Official Hugo v0.20 docs

A. Pages that don’t list lower level pages (e.g. /about/) ¶

Assuming the current version (0.20), a default Hugo folder layout looks like this:

archetypes
config.toml
content
data
layouts
static
themes

If you’d like to generate a bare, one-page site, create an ‘index.html’ in the layouts section. You can write HTML and CSS here, and voila, you have a site. However, if you want to add more pages (e.g. About, Contact etc.) that are not blog posts or listing blog posts, the process is slightly more complicated.

Let’s say we’re trying to create an About page at the url ‘mydomain.com/about/’. We need the following elements to make this happen:

1. In the content directory, create a directory called about. In this directory, create a file named _index.md. This can contain the content of the about page, but not necessarily.
2. In the layouts directory, create a directory called section. In this directory, create a file called about.html. This will define the about page’s layout.

Now Hugo looks in a bunch of locations and is pretty flexible in how it generates pages (e.g. ‘_index.md’ is not necessary, only need a single default layout etc.). Point being, this is NOT the only way to structure your folders to get this result.

However, I find that explicit is better than implicit¹. I want pages to be explicity defined rather than falling back on default behavior that I may not expect. Your directory should now look like this:

archetypes
config.toml
content
    |_ about
         |_ _index.md
layouts
  |_ section
        |_ about.html
static
themes

Running “hugo” at this point should yield an about folder with an index.html file in the public folder. I won’t go into how to create a Hugo template that fills content. The official docs explain that well.

B. Pages that list lower level pages (e.g. /blog/) ¶

Again, starting from the same folder structure:

archetypes
config.toml
content
data
layouts
static
themes

Let’s create a /blog/ page that lists all our posts.

1. In the content directory, create a directory called blog. In this directory, create a file named _index.md. Like before, but we’ll leave this file blank. Your markdown posts will go in the folder.
2. In the layouts directory, create a directory called blog. In this directory, create two files list.html and single.html. Include the snippet below in “list.html” to list all posts in the “content/blog” directory with the most recent post at the top of the list.

<ul>
{{ range .Data.Pages.ByDate.Reverse }}
    <li>
    {{ .Date.Format "2006-01-02" }} | <a href="{{ .Permalink }}">{{ .Title }}</a>
    </li>
{{ end }}
</ul>

Your folder directory should now look like this:

archetypes
config.toml
content
    |_ blog
        |_ _index.md
        |_ post1.md
        |_ post2.md
layouts
    |_ blog
        |_ list.html
        |_ single.html  #Defines layout for each post
static
themes

Running “hugo” should create a /blog/ page that lists post1 and post2.