04 – Hello World in Hugo

Once you have Hugo installed, let’s start by building the most simple website possible in Hugo. All it will do is display a single page with the words “Hello world!”

Open your terminal and execute the following command:

hugo new site hugo-tutorial

If Hugo was installed correctly, you should see a congratulations message and a new directory hugo-tutorial. (Of course, you can name your site something else if you prefer.)

If you use tree to list the contents of the directory, you will see the following:

.
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

You’ll see a number of directories and two files. config.toml contains your site’s configuration. default.md is a default template for front matter, which is Hugo’s terminology for content metadata that you will include in each content file.

We’ll discuss front matter and default.md later. For now, let’s go ahead and create our first content file. Execute the follow in your terminal:

hugo new hello-world.md

You’ll notice that this is the same hugo new command we used earlier to create our site, but instead of two arguments, we supplied just a filename. When you pass hugo new a filename with a .md extension, it infers that we want to create new content, and will create the file under the content directory.

Here’s what our directory listing looks like now:

├── archetypes
│   └── default.md
├── config.toml
├── content
│   └── hello-world.md
├── data
├── layouts
├── public
├── resources
│   └── _gen
│       ├── assets
│       └── images
├── static
└── themes

You’ll see that Hugo has created our hello-world.md file, and also public, resource and static directories. We’ll talk about these later, so you can ignore them for now.

Using your favorite text editor, open the hello-world.md file and you’ll see the following:

---
title: "Hello World"
date: 2022-04-01T18:13:13-04:00
draft: true
---

Our Markdown file has been pre-populated with some content delinated by three hyphens. In Hugo lingo, this is called front matter and is metadata about the file that we can reference in our templates. You can see that the title, date, and draft variables have been generated automatically. This default front matter is defined in the default.md file in the archetypes directory, and can be modified to suit your own requirements.

Hugo has numerous predefined front matter variables for common things you might need for your document, such as data stamps, taxonomies, and images. You can also create user-defined variables. This is a powerful feature of Hugo that we’ll explore in chapter XXXXXX.

You’ll notice that the title has been pre-populated based on the file name we specified earlier. You can change the title if you wish, but for this exercise we’ll keep it as is and add some content to our page.

Edit your file to change the draft status, and also add some content below the front matter:

---
title: "Hello World"
date: 2022-04-01T18:13:13-04:00
draft: false
---
This is my first Hugo page!

… and then save your file.

We have now have a complete Hugo document with some default front matter and content. We’re almost ready to render this in a web server, but first we need to provide Hugo with a layout document. These belong in the layouts directory.

First, let’s create a special directory called _default:

mkdir layouts/_default

As the name implies, _default is where Hugo will look when it can’t find a more specific template file for your document. (Hugo has complicated template lookup rules which we’ll describe later.)

In vim or your favorite editor, create a file called single.html in this newly created directory:

vim layouts/_default/single.html

We’re going to create a very basic template. In your new single.html file, add the following code:

<h1>{{ .Title }}</h1>
{{ .Content }}

… and then save your file.

We have a couple concepts to introduce. The first is that Hugo templates use double braces to access variables. In this example, we are accessing two pre-defined variables. .Title references the title variable in our front matter. .Content references the content of our hello-world.md file, which is everything below the front matter section.

When we surround a variable name with double braces, Hugo’s templating engine will output the content of the variable in place.

Now that we’ve created some content and a template file to display it with, we’re ready to view our completed website.

Execute the following at the top-level of your hugo-tutorial directory:

hugo server -D

This will fire up Hugo’s built-in web server, and the -D switch tells us that we want to include any documents marked draft: true in the output.

You’ll see a bunch of output including some warnings about missing template files. If it worked, you’ll see this:

Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

To view our page, go to http://localhost:1313/hello-world/ in your browser. You should see the following:

If you view source in your browser, you’ll see our title with an tag and a tag around our line of content. This is because Markdown renders paragraphs automatically.

The built-in web server is great for development, but that’s not how you would deploy your website to production. Type ctrl-C to stop the server and then execute:

hugo -D

The -D parameter tells it that we want to include draft content in our build. (Our Hello World article has draft: true set in the front matter). You’ll see some warnings and then a message like this:

                   | EN
-------------------+-----
  Pages            |  3
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  0
  Processed images |  0
  Aliases          |  0
  Sitemaps         |  1
  Cleaned          |  0

Total in 17 ms

When you list the public directory, you’ll see the following:

├── public
│   ├── categories
│   │   └── index.xml
│   ├── hello-world
│   │   └── index.html
│   ├── index.xml
│   ├── sitemap.xml
│   └── tags
│       └── index.xml

In addition to our Hello World page, you’ll see that Hugo has created several XML files for RSS, a sitemap, and taxonomies. This works out-of-the-box with zero configuration, but you can

To deploy your website to production, simply copy the content of the public folder to your server. It’s that simple!

In the next chapter, we’ll tackle a less trivial example and introduce concepts on how to better organize our Hugo content.