Hugo Tutorial: Themeless & Gitless Introduction to the Hugo Static Site Generator
Updated 2021-June-1

This tutorial assumes that you have experience…

It’s not essential, but it may make it easier for you to understand the big picture of how Hugo works if you also have experience…

Also this tutorial assumes that you…

In other words, this tutorial is for you if you are a “hacker” in the following sense.

This tutorial does not assume anything about what platform and apps (other than Hugo) that you are using.

In the steps below we create a website out of files in a directory named Hugo. I recommend that you put this Hugo directory somewhere below your home directory because…

To find out your home directory, open a terminal and at the prompt run one of the following commands.

The hugo executable is one file — with no dependencies🎉 — and it can be put anywhere on your path. To find out your path, run one of the following commands at a command-line prompt.

Information about installing Hugo is in step 0 below.

There are some things that I do in the steps below that you may wonder about if you have already used Hugo. The following list of my preferences will, I hope, help you to understand why things are the way they are in this tutorial.

The TGIH directory currently looks like this:

Most of the files in this directory were forked from Niklas Fasching's Hugo whitespace theme. The article markdown-experiments.md was forked from markdown-it. The image go-logo_black.png is the Go logo.

Thank you Niklas, markdown-it, and golang.org!

At a command-line prompt, go to the TGIH directory and run:

The -D flag, which is equivalent to the --buildDrafts flag, tells the hugo server command to build drafts.

The Hugo server displays a lot of information, including something like this at the top:

And this at the bottom:

In a web browser, go to…

You should see something like the following.

Click on the about link in the navigation bar and you will get a “404 page not found” page. We fix this in step 12 below.

Click on the yellow highlighted Markdown Experiments link and you will see a page that contains HTML elements, such as headers, lists, italicized text, and bolded text. The hugo command generated this HTML page from the file content/articles/markdown-experiments.md. Details about this .md file are in step 6 below.

In a file browser, note that the hugo server command generated a resources/_gen/ directory so now the TGIH directory looks like this:

For more Hugo server tips, see Infinite Ink’s Debugging Your Hugo Website.

The file begins with with three dashes^[18] (---). These dashes tell the hugo command that what follows is YAML front matter. Front matter is used to set page variables. For more information, see these pages on the gohugo.io site:

Front matter is also known as metadata. A Hugo variable is also known as a parameter (or more precisely as a parameter key and a parameter value).

After the YAML front matter, which ends with ---, is a blank line.

After the blank line is the Content. Since the filename extension is .md, the hugo command interprets this part of the file as Markdown, a lightweight markup language.

Hugo supports a lot of markup languages, including more than one flavor of Markdown. In this tutorial, all content files are interpreted as Goldmark-flavored Markdown (assuming you are using Hugo v0.60.0^[19] or newer).

To learn about this, see Infinite Ink’s Hugo’s Markup Languages: AsciiDoc, HTML, Markdown, Org-mode, Pandoc, & reStructuredText.

In Hugo, you can use JSON, TOML, or YAML in…

In this tutorial, we use YAML for the first two and do not use the third (data files).

To learn about YAML, see Infinite Ink’s YAML includes Atoms, Maps, and Lists.

To learn Markdown, see:

Use your text editor to add a comment, a blank line, and change the title to Hello World. The file will now look something like this:

If the hugo server is running and the web browser is displaying http://localhost:1313/, the title will immediately change to Hello World when you save config.yaml.

In Hugo, there are many ways to specify global variables, including

To me, the simplest is to use config.yaml in a project’s root so that is what I use in this tutorial.

To view your site’s current configuration, which includes a lot of default settings, run the following command from the TGIH directory:

For more information about configuring Hugo, see Configure Hugo at gohugo.io.

Use a text editor to open default.md, which looks like this:

I recommend that you do not edit this archetype file until step 11.2 below.

In step 12 below we create more Markdown content. In order to see how an archetype works, add the bolded text below to the Content part of default.md:

Close the default.md archetype file so you do not accidentally edit it in the steps below.

For more about Hugo archetypes, see:

In the front matter, experiment with the following parameters.

After the YAML front matter, which ends with three dashes (---), I like to put a blank line before the Markdown Content.

Add something like the following four lines to your config.yaml. I like to surround a setting like this with blank lines to make it stand out from other configuration settings, especially any table or list, that might be above or below it.

As soon as you save config.yaml, the three emoji codes you specified above in step 13.2.2 should render in the web browser as:

    👨‍🚀 ⭐ 👩‍🚀

If you are using Hugo v0.60.0+ and want to use raw HTML in your Markdown, include the following nested map (or a superset of it) in your config.yaml.^[26][27]

With this “unsafe” setting, Hugo will pass raw HTML — for example <br> — through to the destination file.

Note that this setting is needed only if you are using Hugo’s default Markdown parser (Goldmark). For more about this, see…

Each Hugo layout file…

The TGIH website has three kinds of pages and Hugo renders them as follows:

Open home.html in a text editor. The following line is why drafts are highlighted in yellow on the home page.

Change yellow to red, blue, green, rebeccapurple, gray, lightgray, or any of the hundreds of web colors.

Next add some HTML under the h1 heading, for example:

This added paragraph is written in HTML, which is why it is within the HTML <p> and </p> tags. (Note that when you write in a lightweight markup language, such as Markdown, you do not need to use paragraph tags because paragraphs are delimited by blank lines.)

When you save these changes, the home page of the site (http://localhost:1313/) will change the draft highlight color and display the text that you put between <p> and </p>.

For more about…

To learn about the Hugo assets directory, which is where global resources are located, see gohugo.io/hugo-pipes/introduction/.

style.scss is written in Sassy CSS, which is a superset of CSS. SCSS supports the following two types of comments.

For more about SCSS commenting, see Sass Comments at sass-lang.com. For information about SCSS in general, see Sass (stylesheet language) at wikipedia.org.

In the next section we use SCSS single-line comments.

Open assets/style.scss in a text editor and insert a comment that says something like this:

Next change the $highlight variable to whatever color you would like to use for headers and other highlighted text in the site. I recommend making a backup of the original $highlight setting by commenting out the original line.

style.scss will now look something like this:

When you save this change, the header colors will immediately change from rgb(250, 100, 50)      to blue      in all pages of http://localhost:1313/.

In the TGIH directory, run:

In a web browser, view http://localhost:1313/ and make sure that only the files that are ready for publication are built.

If an article is not ready for publication, its front matter should include this:

If it is ready for publication, its front matter should include this:

Commenting out the draft key works because Hugo’s default is draft: false. If you prefer, you could change draft: true to draft: false, rather than commenting out the draft key.

In the TGIH directory, run:

The hugo command creates a directory named public/ in the TGIH/ directory. If none of the .md files in the content/ directory have draft: true in the front matter, the following will be the structure of this TGIH/public/ directory.

To learn about sitemaps, including sitemap.xml, which is the third line in the directory tree above, see Infinite Ink’s Hugo and sitemap.txt.

The above two highlighted lines are discussed in the next section.

When you build a website with the above hugo command, the files and directories in the static/⁠^[30] directory, which are highlighted in the directory tree above, are simply copied to the public/ directory. A non-static file is processed by hugo and its destination is determined by configuration settings, layout files, the file’s file extension, and the file’s front matter.

The table below shows how some of the TGIH source files are transformed from source to destination to URL (viewable in a web browser after deployment). Some of the TGIH source files are listed in step 4.1 Explore the TGIH directory above.

The last two URLs in the URL column above, which are bolded, are called pretty URLs because they do not end with a file extension (.aspx, .cgi, .css, .htm, .html, .mhtml, .php, .png, .shtml, .xhtml, .xml, etc.).

For more about all this, see:

Note that the above four gohugo.io URLs are “pretty.”

Open config.yaml in a text editor.

If you use the hugo command to rebuild your site, it overwrites files in the public/ directory, but it does not delete files that are already there that are no longer used. If you publish everything in the public/ directory, people and bots browsing the web may stumble upon these old files.

To delete these old files, do one of the following.

In addition to --cleanDestinationDir, which was discussed in the previous step, you may want to use the --minify flag. This flag removes HTML comments and extraneous whitespace characters in the generated HTML files.

You can specify multiple flags like this:

More build flags are listed on Infinite Ink’s Hugo CLI page.

This section is now part of Infinite Ink’s Easy Way to Play With a Hugo Theme’s Example Site.

This tutorial does not use bundles because I wanted to keep it simple, but when you read the Hugo documentation and play with example sites from themes, you will see files below the content/ directory named index.md and _index.md.^[31] A content file with either of these names is part of a Hugo bundle. To learn about this, see Infinite Ink’s Introduction to Hugo Bundles.