Create Your First Page With Hugo

We are finally ready to start adding content to our Hugo managed website. In your terminal, run:

hugo new poetry/lewis-carroll/the-walrus-and-the-carpenter/index.md

Hugo will create the following directory structure under kontent:

kontent/
└── poetry
    └── lewis-carroll
        └── the-walrus-and-the-carpenter
            └── index.md

Next, let’s open the kontent/poetry/lewis-carroll/the-walrus-and-the-carpenter/index.md. The section between the triple dashes is called ‘front matter’ on planet Hugo. On my planet we might have called it ‘metadata’ or ‘page parameters’. Whatever it’s called, it contains variables specific to your page in YAML format. The title holds the HTML title of your page, date is the timestamp of when the content file has been created, and draft: true description: TBD tells Hugo not to generate the page yet when building your site. Drafts are visible, though, when you run Hugo server with -D option.

Let’s add some poetry to the bottom of the file. The result should look like this:

---
title: "The Walrus and the Carpenter"
date: 2020-05-09T15:26:09+02:00
draft: true
description: TBD
---

# The Walrus and the Carpenter

The sun was shining on the sea,  
Shining with all his might:  
He did his very best to make  
The billows smooth and bright –  
And this was odd, because it was  
The middle of the night.  

The content, that is, the text below the front matter section, is written using the Markdown format, so we’ve got two formats in one file, but that’s fine.

Say Hello to Markdown

Markdown is a incredibly simple format for those who need to write texts consisting primarily of headers, paragraphs, lists, links, and code fragments. It is also quite readable in its source form. In the example above, # denotes the biggest header, the paragraphs are separated with an empty line, and line breaks are created by adding two spaces at the end of line.

When Hugo builds your site, the markdown is converted to HTML, and then it replaces the variables in your templates.

For more details refer to Mastering Markdown at GitHub. It is claimed to be a three-minute read.

Paving the Path to Your Fist Hugo Page

If you take a look at http://localhost:1313 now, you will see a link leading to ‘Poetries’. Wait a tick… Wasn’t that ‘poetry’? I call it a ‘creative default’. We shall fix it in a moment, but first let’s explore a bit.

By clicking the link, you will get to the page with a link to ‘The Walrus and the Carpenter’. Notice that this page was generated using list.html template. Finally, by clicking on yet another link, we shall get to the page with the poem. This page is generated using single.html.

But wait – although the page URL is http://localhost:1313/poetry/lewis-carroll/the-walrus-and-the-carpenter , we’ve never saw a section for lewis-carroll. So, we’ve got yet another issue to fix.

Let’s fix the ‘Poetries’ issue first:

hugo new poetry/_index.md

The file kontent/poetry/_index.md contains already familiar front matter parameters, but is otherwise empty. This time, Hugo didn’t get creative with plurals, and the title reads ‘Poetry’. Let’s add a header to the content part of the file:

---
title: "Poetry"
date: 2020-05-10T12:14:02+02:00
draft: true
description: TBD
---

# Some Poetry for the Sake of Example

Now, if you start at http://localhost:1313 you should see a link to ‘Poetry’ section.

The second issue – the missing lewis-carroll section – is addressed the very same way:

hugo new poetry/lewis-carroll/_index.md

Even without any content in _index.md, the missing section now appears once you click the Poetry link. It should be the single link on the page. You might want to restart the server, should it not be the case.

Now you should be able to navigate all the way to the page with the poem normally.

A Brief Look at our Website Structure so far

There are several ways to provide structure (and navigation) for your Hugo-generated website. The simplest is by the means of sections. Sections are just mapped to the directory structure under the content directory of your project (kontent in our case). Each section has its own section page, either implicitly (as with our ‘Poetries’ case earlier), or explicitly, if you create an _index.md in the section’s directory (mind the underscore).

The empty sections are skipped by Hugo, so it is probably a good idea to create an _index.md file in each subsection straight away.

If, however, you will create an index.md file instead (without prepending underscore), the directory will become something else: a page bundle.

Page Bundles in a Hugo Project

Although it is possible to create a page by just creating a markdown file with an arbitrary name that ends with .md, more often than not a web page doesn’t stand alone, but rather has other resources linked to it: images, video, etc. Page bundles cater for that. They also are very practical once it comes to multilingual content (see the next chapter).

A page bundle represents one single page and its translations. Under a page bundle, only a file named index.md and its translations (like index.ru.md) are visible. Everything else is considered the page resources and can become visible only by inclusion into the page that a particular page bundle represents.

A page bundle can also include text resources, and if they are Markdown files, the same translation rules as for the main page apply. More on that in the next chapter.

By contrast, in a section all pages (or page bundles) are visible, plus the section’s own page capable of listing the section contents if list.html template provides for that. For the sake of experiment, create a deeply nested page:

hugo new foo/bar/baz/index.md

Try to navigate to it from the main page. It works, right? But if you now create an index.md file in one of the upstream directories, after restarting the Hugo server you will discover that you cannot get any further. And even if you type http://localhost:1313/foo/bar/baz in browser by hand, you will get 404 page not found error.