Note: It was suggested to me that I provide only the steps in yesterday’s post, without the explanatory lead-in. That way, the intended targets — new Hugo users — would get the good stuff right from the start. So, here goes.
If you’ve been interested in trying the Hugo static site generator (SSG), here’s a four-step procedure which I believe you’ll find easier to follow than the official “Quick Start” documentation:
- Install Hugo.
- Use a one-line Hugo command to create a Hugo project.
- Add a minimal number of bare-bones files so the project can generate a working website.
- Use another one-line Hugo command to run its development server, so you can see how the website looks.
Now, the details . . .
Note: The following instructions are for only the two major computer operating systems for consumers, Windows and macOS. I doubt Linux users, given their likely inclination toward more geeky pursuits, would need this kind of help.
Step 1 • Install Hugo
Hugo is an app that you install on your computer. You can do that by either (a.) relying on a package manager app or (b.) directly downloading from the Hugo GitHub repository. You likely will find the first easier, so let’s go with package managers. Below, for each OS, is an explanation of how to do that. Click the appropriate one to toggle its view. Each shows how to install Hugo Extended, which is always the preferred version.
macOS
Click/tap here to toggle open/close.
Open the Terminal app.
If you already have the Homebrew package manager app installed, skip to the next item.
Otherwise, install Homebrew by entering the following via Terminal:Once the Homebrew installation is complete, go on to the next item./bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Install Hugo by entering the following via Terminal:
This will be the Hugo Extended version, since that’s the only one Homebrew includes.brew install hugo
In the future, you can upgrade Hugo to the latest version in Homebrew’s possession by entering:brew upgrade hugo
This concludes Step 1 for macOS. You can now toggle this back to “closed.”
Windows
Click/tap here to toggle open/close.
Open the Windows PowerShell app.
If you already have the Scoop package manager app installed, skip to the next item.
Otherwise, install Scoop. First, enter this via Windows PowerShell:Answer “Y” (for “Yes”) to the resulting prompt. Then, enter this:Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Once the Scoop installation is complete, go on to the next item.irm get.scoop.sh | iex
Install Hugo Extended by entering this via Windows PowerShell:
In the future, you can update Hugo to the latest version in Scoop’s possession by entering:scoop install hugo-extended
scoop update hugo-extended
This concludes Step 1 for Windows. You can now toggle this back to “closed.”
Step 2 • Create a local Hugo site
Let’s say we’ll call the new site my-site
.
Go into your user directory on your computer. If your user name on the computer is
JohnDoe
, that would be/Users/JohnDoe/
in macOS andC:\Users\JohnDoe\
in Windows.
From here on, we’ll refer to your terminal app. On macOS, the default is Terminal. On Windows, you can use either Command Prompt (cmd.exe) or Windows PowerShell; I suggest the latter.In your terminal app, enter:
(As it creates the site, Hugo will automatically display instructions that mention using a theme — but you can ignore them, because they relate to the aforementioned official procedure to which this is an alternative.)hugo new site my-site
The result will be a structure like the following in your user directory:my-site <-- The Hugo project folder └─ archetypes └─ config.toml <-- The only non-folder └─ content └─ data └─ layouts └─ public └─ static └─ themes
Everything from here on takes place in that my-site
folder.
Note: Windows users, we’ll refer to content/
and layouts/
— i.e., using forward slashes (the web’s norm) rather than backslashes.
Step 3 • Add minimal files to the site
Each of the files you’ll create below is a plain-text file. In macOS, the default text editor is TextEdit. In Windows, it’s Notepad. Either is fine for these. Each editor may complain about your adding .html or .md extensions to these, but you can ignore such messages.
- In
layouts/
, add a folder called_default
. - In
layouts/
, create a file calledindex.html
with the following content:{{ define "main" }} {{ .Content }} <p>This line is from <code>layouts/index.html</code>.</p> {{ end }}
layouts/index.html
is the layout for the site’s home page. - In
layouts/_default/
, create a file calledbaseof.html
with the following content (Hugo’s default is for English, so that’s why I uselang="en"
):<!DOCTYPE html> <html lang="en" charset="utf-8"> <head> </head> <body> {{ block "main" . }} {{ end }} </body> </html>
layouts/_default/baseof.html
is, to quote the Hugo documentation, “the shell from which all your pages will be rendered unless you specify anotherbaseof.html
closer to the beginning of the lookup order.”1
In
layouts/_default/
, create a file calledsingle.html
with the following content:{{ define "main" }} {{ .Content }} <p>This line is from <code>layouts/_default/single.html</code>.</p> {{ end }}
layouts/_default/single.html
is the default template for a single page.1In
content/
, add a file calledfirstpost.md
2 with the following content:--- title: "First post" --- This line is from `content/firstpost.md`. [Go to home](/)
In
content/
, add a file called_index.md
with the following content:Incidentally, the reason for that underscore in the name--- title: "Home page" --- This line is from `content/_index.md`. [Go to firstpost](/firstpost/).
_index.md
has to do with how Hugo helps you manage content, but a more detailed explanation thereof is well outside the scope of these intentionally simplified instructions.In the
config.toml
file at the Hugo project’s top level, add the following line3:disableKinds = ['taxonomy', 'term']
Now, the my-site
project has the absolute minimum requirement of layouts, content files4, and configuration changes so it will work without complaint when you run Hugo’s built-in development server.
Speaking of which . . .
Step 4 • Run the dev server
In your terminal app, navigate to the
my-site
Hugo project folder (if you’re not already working in it) and enter:hugo server
In your browser, visit the site at the URL that the terminal prompts you to visit, which should be
http://localhost:1313/
. The home page will have a link to “firstpost,” and vice versa.When finished, exit the server by going to the terminal app and using the Ctrl C key combination.
So, there you have it. You installed Hugo, created a little starter site, put some files on it, and ran the dev server so you could see what you’d built. Also, you got to see a little bit of the relationship between the templates and content files.
Of course, there are quite a few other SSG-related things you may want to know at some point: version control for safer management of your project(s), website layout/design/styling tips and tricks, and how to deploy your site to a host so it’ll actually be on the web — to mention just a few.
My intent in this post was simply to allow you to get your feet wet with Hugo and see if you like its water temperature; you can decide for yourself when you’re ready to learn how to swim, much less scuba-dive. And, when you are, the many SSG-related and Hugo-related resources of the web are as close as your preferred search engine.
Happy Hugo-ing.
The lookup order is explained in this vital part of the Hugo documentation. ↩︎ ↩︎
If you’re unfamiliar with the Markdown (
.md
) format for plain-text files, start with the original specification and then search for more details. ↩︎This simply prevents some warning messages that Hugo otherwise will throw when you invoke
hugo server
with this set of files in place. If you ever do wish to use these items, just delete this line from the config file. ↩︎Actually, only
content/_index.md
was utterly necessary where content was concerned, but I thought I’d also throw in thecontent/firstpost.md
file just to demonstrate the vitalsingle.html
template at work. ↩︎
Latest commit (ddfbbdb6
) for page file:
2023-09-22 at 10:57:57 AM CDT.
Page history