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/ └── poetry └── lewis-carroll └── the-walrus-and-the-carpenter └── index.md
Next, let’s open 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
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.
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.
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
But wait – although the page URL is
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
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
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.
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.
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
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
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.