TGIH: Themeless and Gitless Introduction to Hugo
  by Nancy McGough

On This Page

Goals

In the steps below, we use the static site generator Hugo to create a simple web site that…

  1. does not require any understanding of Hugo’s lookup order,

  2. does not use a themes directory, which makes it easier to satisfy goal #1,

  3. does not require git, and

  4. does not include any BS Web stuff such as cookies, pop-ups, JavaScript[1], remote fonts, or remote stylesheets.

Prerequisites

Background

This Themeless and Gitless Introduction to Hugo assumes you have experience…​

  • creating simple HTML+CSS web sites, and

  • using the command line.

It does not assume anything about what platform and tools (other than Hugo) you are using.

Mindset

This article is aimed at someone who would like to learn about some of the inner workings of Hugo and is comfortable tinkering with code. In other words, it is aimed at a “hacker” in the following sense.

hacker

A person who delights in having an intimate understanding of the internal workings of a system, computers and computer networks in particular. The term is often misused in a pejorative context, where "cracker" would be the correct term. See also: cracker

Tools

Extended Hugo

To follow the steps in this article, you need to have an extended version of Hugo installed on your system. Information about this is in Step 0 and Step 1 below.

Other Tools

To develop a web site with Hugo, you need to be able to access the following interfaces or views of your system.

InterfaceUsed For

command-line interface (terminal)[2]

running hugo commands, including starting and stopping the Hugo server

web browser

viewing http://localhost:1313/

file browser

viewing and managing Hugo-related files and directories

plain text editor

editing the web site’s archetype, assets, configuration, content, and layout files

Most platforms have built-in tools for accessing the above four interfaces. If you would like to use an app that integrates some of these interfaces, I recommend one of the following.

All of these run on multiple platforms and are free/libre open source software. I currently use Visual Studio Code, which is also known as Code and VS Code.

For more about integrated development environments, see these pages at wikipedia.org:

Shell tip

When you use a command-line interface or terminal, you do it in a shell, which is a layer between you and the operating system. I’ve tried to write this article so that the commands work in most shells. The main shell advice I have is the following.

Tip

Use a shell that saves the command-line history between sessions. This way you can use the Up Arrow and Down Arrow keys to step through your command history.

  • On nix-based platforms (BSD, Linux, macOS, Unix, etc.), most command-line shells do this by default.

  • On Windows, PowerShell does this by default, but cmd.exe does not. This is one reason I prefer PowerShell to cmd.exe.

For more information about shells, see Shell (computing) - Wikipedia

Hugo preferences

Site development files in home directory

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

  1. most backup apps automatically back up the home directory,

  2. most sync apps, such as Dropbox and Sync.com, sync a subdirectory of the home directory,[3]

  3. you and hugo should not have permission problems creating, editing, moving, or deleting files and directories in your home directory, and

  4. in most shells, you can use cd ~ to go to your home directory.[4]

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

  • In PowerShell and nix-based shells, run:

    • echo $HOME

  • In cmd.exe, run:

    • set home

Executable anywhere on path

The hugo executable is one file and can be placed anywhere on your path. To find out your path, run one of the following commands at a command-line prompt.

  • In a nix-based shell, run:

    • echo $PATH

  • In PowerShell, run:

    • $Env:Path

  • In cmd.exe, run:

    • set path

Tip
If you use a package manager to install hugo you will not need to deal with your path because the package manager will take care of that.

Information about installing Hugo is in Step 0 below.

Non-standard Hugo preferences

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

  • I want to deal with a minimal number of layout[5] files and I do not want to have to think about Hugo’s lookup order.

  • The layout file for a Hugo web site’s home page can be named either home.html or index.html. I prefer to name it home.html because the word index is semantically overloaded in Hugo.

  • For Hugo configuration, I prefer YAML to TOML[6] and thus use a config.yaml file rather than a config.toml file.

  • In YAML files, I like to minimize the use of commas and quotation marks.

0. Install extended hugo

To install an extended version of hugo, do one of the following.

Tip

Using a package manager makes it easy to install, update, and uninstall Hugo. Wikipedia has a list of software package management systems. On Windows, I use and recommend Scoop.

1. Check your hugo

To check that hugo is on your path, is version 0.43 or higher, and is an extended version, run the following at a command prompt:

hugo version

You should see something like this:

Hugo Static Site Generator v0.55.6/extended windows/amd64 BuildDate: unknown
                                      👆

You can find out what directory hugo is in with one of the following shell commands.

  • In a nix-based shell, run:

    • which hugo

  • In PowerShell, run:

  • In cmd.exe, run:

    • where hugo

Important
Make sure you are using Hugo Extended version 0.43 or later because old and unextended versions of Hugo do not support SCSS (Sassy CSS), which we use in the site we build below.

2. View Hugo’s built-in help

To learn about Hugo’s commands and flags run this command at a command prompt:

hugo -h | more

The trailing | more in the above command pipes the output through the more pager. Within more, you can press space to page down and press q to quit.

Note
  • -h, --help, and help, are equivalent hugo command-line arguments. The results are on Infinite Ink’s hugo -h page.

  • | more works in the command-line interface of many platforms, including Windows[7] and nix-based platforms (BSD, Linux, macOS, Unix, etc.).

3. Create Hugo and Backups directories

Create a directory named Hugo, which will contain all the Hugo-related files and directories we use in this article. Within this Hugo directory, create a subdirectory named Backups. You should now have this directory structure:

Hugo/
  Backups/

There is nothing special about these two directory names, but to be able to easily follow the steps below, I recommend that you use these names.

Tip
Put this Hugo directory somewhere in your home directory. More about this tip is in Hugo preferences above.

4. Download the TGIH site skeleton

Download the site skeleton from Infinite Ink’s GitHub account. One way to download it is to click on this link of the .zip file:

After themeless-gitless-intro-hugo-master.zip has downloaded, unzip it and put the TGIH directory in your Hugo directory. Your Hugo directory will now look like this:

Hugo/
  Backups/
  TGIH/

Before we edit the TGIH files, make a backup copy of the freshly downloaded and unzipped TGIH directory and include some historical information in the name of this backup directory, for example you could append the download date like this:

Hugo/
  Backups/
    TGIH-2019-06-12/
  TGIH/

The backup TGIH directory name could also include the latest date that’s displayed on the themeless-gitless-intro-hugo repository.

4.1. Overview

The TGIH directory is the site root directory and for the rest of this article we work in this directory. The Backups/TGIH-2019-06-12 will come into play only if there is a problem with the site.

The TGIH directory currently looks like this:

  TGIH/
    archetypes/
      default.md
    assets/
      style.scss
    content/
      articles/
        markdown-experiments.md
    layouts/
      _default/
        baseof.html
        home.html
        list.html
        single.html
        tag.html
    static/
      images/
        go-logo_black.png
    config.yaml

4.1.1. No themes directory

If you are familiar with Hugo, you might wonder why there is no themes directory. A themes directory is not required and the site we build below does not use one — that’s why this article is called Themeless and Gitless Introduction to Hugo.

4.2. Provenance

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!

5. Build and view the site

These files are enough to build the beginning of a web site. At a command-line prompt, go to the TGIH directory and run:

hugo server -D
             👆

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 this at the top:

Building sites …
                   | EN
+------------------+----+
  Pages            | 15
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  1
  Processed images |  0
  Aliases          |  0
  Sitemaps         |  1
  Cleaned          |  0

And this at the bottom:

Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

In a web browser, open http://localhost:1313/. You should see something like this:

My New Hugo Site screenshot

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, and bolded text. The hugo command created this HTML page from the file markdown-experiments.md in the content/articles/ directory. Details about this .md file are in Step 6 below.

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

  TGIH/
    archetypes/
      default.md
    assets/
      style.scss
    content/
      articles/
        markdown-experiments.md
    layouts/
      _default/
        baseof.html
        home.html
        list.html
        single.html
        tag.html
    resources/
      _gen/
        assets/
          scss/
            style.scss_f300667da4f5b5f84e1a9e0702b2fdde.content
            style.scss_f300667da4f5b5f84e1a9e0702b2fdde.json
          images/
    static/
      images/
        go-logo_black.png
    config.yaml

5.1. Hugo server tips

  • If you leave this hugo server running, Hugo will LiveReload the site when you make changes.

  • While the server is running, you can open another terminal and run other hugo commands there.

  • If there is a problem with the site, use Ctrl-C to stop the Hugo server and then restart it.

For more Hugo server tips, see Debugging tips near the end of this article.

6. View markdown-experiments.md

This section is about looking at a file in the content/ directory. You do not need to make any edits, but it’s OK if you do. Use your text editor to open markdown-experiments.md, which is in the content/articles/ directory.

Abstractly the file looks like this:

Front matter

Content
 

Details are below.

6.1. Front matter

The file begins with with three dashes[8] --- 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. Hugo variables are also known as parameters.

6.2. Blank line

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

6.3. Content

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.

Note
  • I use “Content” — with an initial capital letter — to mean the part of the file after the front matter.

  • In Go Templates, which are discussed below, this Content is sometimes available as {{ .Content }}.

7. Meta

7.1. About Hugo’s markup languages

Hugo includes support for these markup languages:

File
Extension(s)
Markup LanguageBuilt-in
Helper

.md
.mdown
.markdown

Blackfriday-flavored Markdown

✔️

.mmark

mmark-flavored Markdown

✔️

.org

org-mode

✔️

.htm
.html

HTML

✔️

.ad
.adoc
.asciidoc

AsciiDoc

.pdc
.pandoc

Pandoc

.rst

reStructuredText

To use one of the last three markup languages — AsciiDoc, Pandoc, or reStructuredText — you need to install a helper program. If you install a helper program, it must be on your path so hugo can find it.

In this article, all our content files have the file extension .md and hugo interprets these as Blackfriday-flavored markdown.

To learn more about Hugo’s support for markup languages, see gohugo.io’s Supported Content Formats

7.2. About YAML

To learn about YAML syntax, see en.wikipedia.org/wiki/YAML. The main thing you need to know for this article is that YAML can include atoms, maps and lists.[9]

A map is a key/value pair. Here are a couple example YAML maps:

key1: value1
key2: value2

Here is an example of a YAML list:

- item1
- item2
- item3

These data structures can have names, also known as keys. For example:

name1:
  key1: value1
  key2: value2

name2:
  - item1
  - item2
  - item3

Note that name1 is a key whose value is a couple maps and name2 is a key whose value is a three-item list. Naming a collection is a way to turn it into an object or block that can be referenced.

In general, you do not need to use quotation marks around YAML strings. Quoting a string is required if it:

  • includes a colon (:), hash (#), greater than (>), or any character that has a special meaning in YAML.

  • looks like a number (decimal, hexadecimal, exponential E or e notation, etc.)

  • is one of YAML’s reserved boolean words (true, false, off, etc.)

A list is also known as an array. A named collection of maps, for example name1, is also known as an associative array, a dictionary, or a hash table.

Important

In YAML:

  • Spacing matters.

  • Tabs are not allowed.[10]

  • Lines that begin with a hash (#) are comments and are ignored.

8. Create one.md

Open a new terminal, make sure you are in the TGIH directory, and run:

hugo new articles/one.md
         ---------------
                👆
         this path is relative to TGIH/content/

The one.md file is created in the content/articles/ directory.

Note
  • Do not specify content in the path because that is included automatically by the hugo new command

  • In Hugo forward slash (/) will work as a directory delimiter on any platform, including Windows.

  • Do not put a space or any whitespace character in the path or filename.

  • Separate words with a dash (-)[8] because the new-content archetype (discussed in Step 11 below) creates the article title by replacing dashes with spaces.

  • Use all lower case for directory and file names in the content/ directory because most web servers force URL paths to be all lower case.[11]

  • In Hugo, the default is to use the content file name (without the extension) as part of the web page URL.

Your TGIH/content/ directory now looks like this:

content/
  articles/
    markdown-experiments.md
    one.md

Look at http://localhost:1313/ in a web browser and the One and Markdown Experiments articles should be listed on the home page like this:

My New Hugo Site screenshot
Tip

If you do not see both the One and Markdown Experiments articles listed, make sure:

  • hugo server is running with the -D flag

  • one.md is located in the articles/ directory

9. Edit one.md

Use your text editor to open one.md, which looks like this:

---
# Important: If this is not a draft, comment out the next line
draft: true
title: One
date: 2019-05-16
# below are non-built-in parameters (lower case keys recommended)
subtitle:
tags:
  - hugo
  - intro
---

Below the blank line after the front matter add some markdown content, for example:

**Hello World!** This is written in *markdown*, a lightweight markup language.

When you save your changes, the Hugo server will automatically update the markdownified web page. In Hugo markdownify means convert markdown to HTML.

9.1. Learn markdown

To learn markdown syntax, see:

10. Edit config.yaml

The config.yaml file in the root of the TGIH directory is used to specify global variables. Use a text editor to open this file, which looks like this:

baseURL: http://example.org/
languageCode: en-us
title: My New Hugo Site

This is Hugo’s default config.yaml. Use your editor to add a comment, a blank line, and change the title to Hello World. The file will now look something like this:

# 2019-06-12: changed title

baseURL: http://example.org/
languageCode: en-us
title: Hello World

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

10.1. About configuring Hugo

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

  • in a file named config.toml, config.yaml, or config.json in the root of a site

  • in command-line flags

  • in environment variables

  • in multiple files in a config directory

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

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

hugo config | more

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

11. Edit the archetype for new .md content files

When you use the hugo new command to create a .md file (like we did in Step 8 above), Hugo uses archetypes/default.md as a template for the new file.

11.1. Open and view archetypes/default.md

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

---
## Important: If this is a draft, next line should NOT begin with #
# draft: true
title: {{ replace .Name "-" " " | title }}
date: {{ dateFormat "2006-01-02" .Date }}
## below are user-defined parameters (lower case keys recommended)
subtitle:
tags:
  - tag1
  - tag2
---

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

11.1.1. Front matter

The double curly braces in in the title and date key values are Go Template code.

Note
A curly brace is sometimes called a mustache or handlebar, but Go templates are different from Mustache and Handlebar templates.

11.1.2. Content

Currently the Content part of this archetype file is empty. You can write some notes to yourself, some content snippets, or whatever you would like to be included in every .md file created with the hugo new command. For example, you could put something like the following in your markdown archetype.

---
## Important: If this is a draft, next line should NOT begin with #
# draft: true
title: {{ replace .Name "-" " " | title }}
date: {{ dateFormat "2006-01-02" .Date }}
## below are user-defined parameters (lower case keys recommended)
subtitle:
tags:
  - tag1
  - tag2
---

markdown here


<!--
  HTML, including an HTML comment like this, is OK in markdown
-->

HTML comments will not appear on a web page, but will be viewable if someone uses a web browser to “view source” so be careful what you put in HTML comments.

11.1.3. Go Template code works anywhere in an archetype

You can include Go Template code anywhere in an archetype file, including in the Content section. I like to have an HTML comment that records the exact moment that I created the file by putting this in the Content section of my archetype file:

<!--
  created {{ .Date }}
-->

This is a note to myself that my readers will not see unless they “View source”.

11.2. Edit archetypes/default.md

In Step 12 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:

---
## Important: If this is a draft, next line should NOT begin with #
# draft: true
title: {{ replace .Name "-" " " | title }}
date: {{ dateFormat "2006-01-02" .Date }}
## below are user-defined parameters (lower case keys recommended)
subtitle:
tags:
  - tag1
  - tag2
---

markdown here


<!--
  created {{ .Date }}
-->

11.3. Save and close archetypes/default.md

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

12. Create more content: another-one.md and about.md

Thanks to the updates to the archetype file we made in the last step, the .md files we create in this step will include some default text below the front matter.

At a command-line prompt, make sure you are in the TGIH directory, and run these two commands:

hugo new articles/another-one.md
hugo new about.md

The content directory now looks like this:

content/
  about.md
  articles/
    another-one.md
    markdown-experiments.md
    one.md

In http://localhost:1313/ in your web browser, note that the about link in the navigation bar now works.👍

13. Experiment with the content .md files

In your text editor open about.md, another-one.md, markdown-experiments.md, and one.md. Note that about.md and another-one.md include the content that we added to the archetype file in Step 11.2.

13.1. Front matter

In the front matter, experiment with the values of the following keys.

13.1.1. draft key

The beginning of the front matter in most of the content .md files looks like this:

---
## Important: If this is a draft, next line should NOT begin with #
# draft: true

Turn at least one of these articles into a draft by changing the front matter to this:

---
## Important: If this is a draft, next line should NOT begin with #
draft: true

13.1.2. date key

The order of the articles listed on the home page (http://localhost:1313/) is based on the date key. Change the dates so that the order is changed.

Important
Make all dates today or earlier. By default hugo does not build any page with a date in the future.

To learn about other ways to order the article list, see Order Content at gohugo.io.

13.1.3. subtitle key

The front matter includes a subtitle key that has no value:

subtitle:

In some or all of the .md files add a value to this key, for example:

subtitle: this is a subtitle

Make sure to leave a space between the colon (:) and the subtitle value.

13.2. Content

13.2.1. Include an image

The TGIH directory that you downloaded in Step 4 includes an image in the static subdirectory. To use this image in one of your .md files, use this markdown syntax:

![Go Logo](/images/go-logo_black.png)
           👆
           notice this leading slash

As soon as you save the .md file with this markdown, the following image will be rendered in the web page.

Go Logo

This is the Go logo, which you can read about at blog.golang.org/go-brand

13.2.2. Include an emoji code

Include an emoji code in the Content of at least one of the .md files. For example:

:smile:

This will not be rendered as an emoji until the next step (Step 14).

Note

14. Edit config.yaml again

Open config.yaml in your edtor.

14.1. enableEmoji

Add the following line anywhere in the file.

enableEmoji: true

As soon as you save config.yaml, the :smile: emoji code you entered in the previous step should render in the web browser as:

  😄

15. Explore the layouts directory

The layouts directory looks like this:

layouts/
  _default/
    baseof.html
    home.html
    list.html
    single.html
    tag.html

These files — along with the .scss file in the assets/ directory — create the look and feel of the web site.

15.1. About Hugo layout files

Each Hugo layout file:

  • is written in the Go Template language, which is also known as GO HTML,

  • has the extension .html, and

  • can access site and page variables.

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

KindUses layout file
baseof.html and …

home

home.html

page

single.html

taxonomy

tag.html

15.2. Edit home.html

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

<span {{ if .Draft }}style="background-color: yellow;"{{ end }}>{{ .Title }}</span>

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

Next add some HTML content under the h1 heading, for example the bolded line below:

<h1 class="title">{{ .Title }}</h1>

<p>Here are the articles on this site ordered by date.</p>

This added text is written in HTML, which is why it is within HTML paragraph tags (<p> and </p>).

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

16. Explore the assets directory

The assets directory looks like this:

    assets/
      style.scss

style.scss is the stylesheet for the site.

16.1. About SCSS

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

This is a CSS multi-line comment:

/*
  this is a CSS comment
*/

And this is an SCSS single-line comment:

// this is an SCSS comment

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.

16.2. Edit style.scss

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

// 2019-06-12: changed $highlight variable

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:

// 2019-06-12: changed $highlight variable

// $highlight: rgb(250, 100, 50);
$highlight: blue;

When you save this change, the header colors will immediately change in all pages of http://localhost:1313/.

17. Prepare for publication

When you are ready to publish your site at a web-hosting provider, you will run the hugo command without the server subcommand. This will create the for-publication site files in TGIH/public.

17.1. Test build without -D or --buildDrafts

In the TGIH directory, run:

hugo server
            👆
            no flag here

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:

draft: true

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

# draft: true

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

17.2. Check baseURL

In config.yaml, the default baseURL setting is the bolded line below.

baseURL: http://example.org/
                           👆
                           notice this trailing slash

The slash (/) at the end of the baseURL can’t hurt and sometimes helps, so I recommend that you include it.

When you are really ready to publish — rather than learning Hugo in this Themeless and Gitless Introduction to Hugo — replace example.org with your site’s domain name.

17.3. Run hugo without subcommands or flags

In the TGIH directory, run:

hugo
     👆
     no subcommands or flags

17.4. Explore the public directory

The hugo command created the TGIH/public directory. If none of the content .md files have draft: true in the front matter, this is the directory structure:

|   index.html
|   index.xml
|   sitemap.xml
|   style.css
|
+---about
|       index.html
|
+---articles
|   |   index.html
|   |   index.xml
|   |
|   +---another-one
|   |       index.html
|   |
|   +---markdown-experiments
|   |       index.html
|   |
|   \---one
|           index.html
|
+---categories
|       index.html
|       index.xml
|
+---images
|       go-logo_black.png
|
\---tags
    |   index.html
    |   index.xml
    |
    +---markdown
    |       index.html
    |       index.xml
    |
    +---tag1
    |       index.html
    |       index.xml
    |
    +---tag2
    |       index.html
    |       index.xml
    |
    \---testtesttest
            index.html
            index.xml

18. Publish the site

To publish the site, copy all the files and directories in the public directory to the appropriate directory on your web-hosting provider’s server.

Debugging tips

If there is a problem with the site, here are some things you can try.

  • Use Ctrl-C to stop the Hugo server and then restart it.

  • In your web browser, do a “hard reload” or “hard refresh.” How to do this in many web browsers is in en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache.

  • Run hugo with the -v (which is equivalent to --verbose) flag.

  • Check that the port number in your web browser (http://localhost:port) is correct. If you have multiple Hugo servers running, you may need to look at http://localhost:1314. This can happen when you are using multiple terminals.

  • View your site with a different web browser.

  • Explicitly specify a different port, e.g. hugo server -D -p 8888.

  • Put debug code in layout files.

  • Run hugo with flags such as --debug, --ignoreCache, --path-warnings, --log, or --verboseLog. For brief info about these and other flags, see Infinite Ink’s hugo -h page.

  • Delete the Hugo server cache. To find its location, run hugo config | more and look for the value of cachedir.

Thanks!

Most of the tools and resources that I used to write this article are free/libre open source software (FLOSS). Thank you to the free-culture and open-source movements, and…

 

Footnotes


1. The TGIH web site does not use JavaScript, but the Hugo server uses JavaScript for LiveReload.
2. A command-line interface is sometimes called a command-line interpreter, CLI, command-line shell, console, or terminal.
3. If you use a “sync app”, such as Dropbox or Sync.com, you may want to put your Hugo directory in ~/Dropbox or ~/Sync. To learn about these type of apps and services, see en.wikipedia.org/wiki/File_hosting_service.
4. Using tilde (~) as a shortcut for the home directory works in PowerShell and nix-based shells, but it does not work in cmd.exe.
5. Hugo layouts, which are also called templates, are written in Go HTML.
6. I prefer YAML to TOML mainly because I do not want to have to put all “TOML tables” at the bottom of the config.toml file. Instead I want to structure my config file in a way that makes sense to me.
7. Windows has many different command-line shells, including cmd.exe, PowerShell, and WSL shells (bash, zsh, etc.). The more pager is built-in to all of these.
8. The Unicode name for “dash” (-) is hyphen-minus. Details are at Hyphen-minus - Wikipedia.
9. I like to think that the AML part of YAML stands for Atoms, Maps, and Lists, but this is not what the YAML acronym really stands for.
10. Tabs are allowed in later versions of YAML, but it is safest to not use them.
11. If you want to use upper-case characters in a web page URL, put disablePathToLower: true in your config.yaml.