hugo version
hugo
hugo
Hugo
and Backups
directoriesTGIH
site skeletonone.md
one.md
config.yaml
🔧.md
content filesanother-one.md
and about.md
.md
filesconfig.yaml
again🔧layouts
directoryassets
directory2020-December-31 Hugo v0.80.0 released. To keep up with Hugo releases, see discourse.gohugo.io/c/announcements, github.com/gohugoio/hugo/releases, gohugo.io/news, old.reddit.com/r/gohugo/, or twitter.com/@GoHugoIO.
2020-June-25
Updated
this tutorial’s
step
15. Explore the layouts directory
so that it uses the new Hugo v0.73.0+ .Kind
[1]
terminology.
2020-May-31 As of today, this Hugo Tutorial has been on the web for one year!🎉🎊🎆
2020-April & March Significant updates in this tutorial, including renaming and renumbering some sections; rewriting 14.2. markup; and creating 17.5.2. taxonomies🏷, 17.5.3. Case sensitivity of variables, and 19.2. Learn about Hugo bundles.
This tutorial assumes that you have experience…
creating simple HTML+CSS websites
and launching apps from a command line.
It does not assume anything about what platform and apps (other than Hugo) that you are using.
Also this tutorial assumes that you…
would like to learn about some of the inner workings of Hugo
and are comfortable tinkering with code.
In other words, this tutorial is for you if you are 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”
To follow the steps in this tutorial, you need to have an extended version of the static site generator Hugo installed on your system. Information about this is in step 0 and step 1 below.
To develop a website with Hugo, you need to be able to access the following interfaces or views of your system.
Interface | Used For |
---|---|
command line | running |
web browser | viewing http://localhost:1313/ |
file browser | viewing and managing Hugo-related files and directories |
plain text editor | editing the website’s archetypes, assets, configuration, content, and layout files |
Most platforms have built-in apps 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.
Code, which is also known as Visual Studio Code and
IntelliJ IDEA Community Edition
All four of these run on multiple platforms and are free/libre open source software (FLOSS).
For more about integrated development environments, see these pages at wikipedia.org:
When you use a terminal to interact with an operating system, you do it in a shell, which is a layer or interface 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.
💡 | Use a shell that saves the command-line history (or buffer) between sessions. This way you can use the Up Arrow and Down Arrow keys to step through your command history.
|
For more information about shells, see Shell (computing) - Wikipedia.
$HOME
(~
)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…
most backup apps automatically back up your home directory,
most sync apps, such as Dropbox and Sync.com, sync a subdirectory of the home directory,[4]
you
and hugo
should not have permission problems creating, editing, moving,
or deleting files and directories in your home directory,
and in most
command-line
shells, you can use
cd ~
to go to your home
directory.[5]
To find out your home directory, open a terminal and at the prompt run one of the following commands.
In nix-based shells and PowerShell, run either:
echo $HOME
cd ~
(this will change directory to ~ (your home directory))
In cmd.exe, run:
set home
$PATH
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.
In a nix-based shell, run:
echo $PATH
In PowerShell, run:
$Env:Path
(or equivalently all lower case $env:path
)
In cmd.exe, run:
set path
💡 | 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.
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.
I want to deal with a minimal number of layout[6] files and I do not want to have to think about Hugo’s layout lookup order.
The home page layout file 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[7]
and
thus use a
config.yaml
file rather than a config.toml
file.
Many
Hugo themes
and tutorials
use a config.toml
.
In YAML syntax, I like to minimize the use of commas, quotation marks, and square brackets.
This article uses the following admonition icons.
Icon | Meaning |
---|---|
‼ | Important |
ℹ | Note |
💡 | Tip |
hugo
To install
an
extended
version of hugo
,
do one of the following.
Follow the guide at gohugo.io/getting-started/installing/, which includes information about using package managers
or download the latest
hugo_extended_version_platform
from github.com/gohugoio/hugo/releases
and put
the executable
somewhere on your path
(discussed
above in Executable anywhere on $PATH).
💡 |
|
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-line prompt:
hugo version
You should see something like this:
Hugo Static Site Generator v0.80.0/extended windows/amd64 BuildDate: unknown 👆
‼ | Make sure you are using Hugo Extended v0.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. |
💡 |
|
To learn about Hugo’s commands and flags run this command at a command-line prompt:
hugo -h | more
The trailing
| more
(“pipe
more”)
in the above command
pipes[11]
the output
of hugo -h
through the more
pager.
Within more
, you can
press
Space
to page down
and press
q
to quit.
Hugo
and Backups
directoriesCreate 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.
💡 | I recommend that you put
this Hugo directory
somewhere
below
your
home
directory.
Details
about this
tip
are
in
Hugo preferences
above. |
TGIH
site skeletonDownload the
site skeleton from
the
themeless-gitless-intro-hugo
repository
in
Infinite Ink’s GitHub account.
One way to download it is to click on the following link of the
repo’s
.zip
file.
After
themeless-gitless-intro-hugo-master.zip
has downloaded,
unzip it and then put the
TGIH[14]
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-2021-01-14/ TGIH/
TGIH
directoryThe 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
themes
directoryIf you are familiar with Hugo, you
may 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
tutorial’s
subtitle
is
Themeless & Gitless Introduction to the Hugo Static Site Generator.
For the rest of this article we work in this
TGIH/
directory,
which
is called the…
project base directory,
project root directory,
project working directory,
project directory,
project root,
root,
or workingdir.
The Backups/TGIH-2021-01-14/
directory will come into play only
if there is a problem with the website.
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!
These files are enough to build the beginning of a website.
At a command-line prompt,
go to the TGIH
directory and run:
hugo server -D 👆
The -D
flag,
which
is equivalent to the
--buildDrafts
hugo server
command to build drafts.
The Hugo server displays a lot of information, including something like this at the top:
Start building sites … | EN +------------------+----+ Pages | 15 Paginator pages | 0 Non-page files | 0 Static files | 1 Processed images | 0 Aliases | 0 Sitemaps | 1 Cleaned | 0 Built in 100 ms
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, go to…
http://localhost:1313/ 👆 notice that this is not https
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.
TGIH
directory againIn a file browser,
note that the hugo server
command
generated
a
resources/_gen/
directory
so now
the
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
In some
terminal emulators — for example
Visual Studio Code's built-in terminal,
ConEmu,
and
mintty — you can
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 you regularly use multiple terminals, I recommend using
a tabbed terminal emulator.
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 Infinite Ink’s Debugging Your Hugo Website.
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
a Hugo content file is structured
like this:
header |
---|
body |
In Hugo the header is called front matter and the body is called various things, including:
body
body content
Content
content body
main matter
RawContent
In this Hugo tutorial, the body is called Content (with the “C” capitalized). Here is the anatomy of a Hugo content file using this terminology:
front matter |
---|
Content |
Details are below.
The file
begins with
with
three
dashes[15]
(---
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).
‼ | Front matter is required in a Hugo content file. If you do not need to specify any metadata, use empty front matter, for example this: --- --- or this: --- # This front matter is intentionally left blank. --- |
After the YAML front matter,
which ends with
---
ℹ | If the front matter is in TOML or YAML format, this blank line is not required but if the front matter is in JSON format, it is required. |
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[16] or later).
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…
front matter of content files,
site configuration files,
and data files.
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.
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.
ℹ |
|
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:
💡 | If you do not see both the One and Markdown Experiments articles listed, make sure:
|
one.md
Use a text editor to
open
one.md
, which looks like this
(with the date replaced with the date you created it):
--- # 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.
To learn Markdown, see:
Infinite Ink’s
markdown-it
markdown-experiments.md
,
which
we viewed
above
in
step 6
and
includes some of the
Markdown markup
from the
markdown-it
live demo
💡 | A nice FLOSS multi-platform WYSIWYG Markdown editor is Mark Text. If you are on Windows, you may want to check out Markdown Monster. |
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: https://example.org/ languageCode: en-us title: My New Hugo Site
title
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:
# 2021-01-14: changed title baseURL: https://example.org/ languageCode: en-us title: Hello World
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
a Hugo config file,
variables,
such as
baseURL ,
languageCode ,
and
title ,
are sometimes case sensitive
so I recommend that you specify them using the upper- and
lower-case letters that are specified
in
gohugo.io/getting-started/configuration/. |
In Hugo, there are many ways to specify global variables, including
in a file named
config.json
,
config.toml
, or config.yaml
in the root of the project
in environment variables
in multiple files in a config/
directory
in the root of the project
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:
hugo config | more
For more information about configuring Hugo, see Configure Hugo at gohugo.io.
.md
content filesWhen you use the hugo new
command
to create a .md
file
(as we did in
step 8
above),
Hugo uses
archetypes/default.md
as a template for the new file.
archetypes/default.md
Use a text editor to
open
default.md
,
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.
The double curly braces in
in the
title
and date
key values
are
Go Template code.
ℹ | A curly brace is sometimes called a mustache or handlebar, but Go Templates are different from Mustache and Handlebar templates. |
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
bolded lines
in the content part of your markdown archetype file.
--- ## 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 may be viewable if someone uses a web browser to “view page source” so be careful what you put in HTML comments.[19]
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 {{ now }} -->
The above HTML comment is a note to self that my readers will not see unless they use their web browser to “view page source.”[19]
archetypes/default.md
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
:
--- ## 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 {{ now }} -->
archetypes/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
Go Templates,
including
Hugo
archetypes,
layouts,
and
|
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 your web browser, note that
the about link in the navigation bar
of all the http://localhost:1313/ pages
now
.md
filesIn a 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.
In the front matter, experiment with the following parameters.
draft
The beginning of the front matter in
most of the
.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
content files
into a draft by
changing the front matter to the following
(i.e., remove the #
that is before draft: true
).
--- ## Important: If this is a draft, next line should NOT begin with # draft: true
ℹ | If a content file is a draft, the hugo command will process it only if the
--buildDrafts -D
flag,
is used. |
date
The
order of the
articles listed on the home page
(http://localhost:1313/)
is based on the
date
parameter.
Change the dates so that the order is changed.
‼ | 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.
subtitle
The front matter includes a subtitle
parameter
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.
After the YAML front matter, which ends
with three dashes
(---
ℹ | If the front matter is in TOML or YAML format, this blank line is not required but if the front matter is in JSON format, it is required. |
The TGIH directory that you downloaded in step 4
includes an image
in the static/
subdirectory.
To use this image in a TGIH .md
file,
use this Markdown syntax:
 👆 notice this leading slash
When you save the
.md
file with this
Markdown,
the following image will be
displayed
on
the web page.
This is the Go logo, which you can read about at blog.golang.org/go-brand.
💡 | The text
inside this Markdown’s square brackets
is used as the
|
ℹ |
|
Include
the following three
emoji codes
in the
Content of at least one of the .md
files.
:man_astronaut: :star: :woman_astronaut:
‼ | These
will not be rendered as
emoji[22]
until
step
“14.1 enableEmoji ✨”
below. |
ℹ | You can find emoji codes, which are also known as emoji shortcodes and CLDR short names, at:
According to discourse.gohugo.io/t/support-github-emoji/6164/2, the Hugo emoji codes come from github.com/kyokomi/emoji. |
💡 | ⇽This tip icon is the The titles of
steps
14 and 14.1 below include,
respectively,
the
|
config.yaml
again🔧Open config.yaml
in a text editor.
enableEmoji
✨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.
# 2021-01-14: added next line enableEmoji: true
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:
👨🚀 ⭐ 👩🚀
markup
If you are using Hugo
v0.60.0+
and want to
use
raw HTML
in your Markdown,
include the following
nested map
in
your config.yaml
.[23][24]
markup: goldmark: renderer: unsafe: true
With this
“unsafe” setting,
Hugo will
pass
raw HTML — for example
<br>
— through
to the
destination file.
‼ | Without this
“unsafe”
setting,
<br>
and any other raw HTML
in a
Markdown source file will be replaced
with
in the
markdownified[25]
destination file. |
Note that this setting is needed only if you are using Hugo’s default Markdown parser (Goldmark). For more about this, see…
gohugo.io’s Configure Markup
Infinite Ink’s Hugo’s Markup Languages: AsciiDoc, HTML, Markdown, Org-mode, Pandoc, & reStructuredText.
layouts
directoryThe 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 website.
Each Hugo layout file…
is written in the Go Template language, which is also known as Go HTML,
can access site variables and page variables
and has a file extension that signifies the
output format
(html
in these TGIH layout files).
The TGIH website has three kinds of pages and Hugo renders them as follows:
Kind[1] | Uses base layoutbaseof.html andmain blockfrom… | View example rendering at |
---|---|---|
home |
| localhost:1313/ |
page |
| localhost:1313/about/ |
term |
| localhost:1313/tags/tag1/ |
home.html
Open home.html
in a 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 under the h1
heading,
for example:
<h1 class="title">{{ .Title }}</h1>
<!-- 2021-01-14: added next paragraph -->
<p>
Here are the articles on this website <strong>ordered by publication date</strong>, starting with the most recently published article.
</p>
This added paragraph is written in HTML, which is why
it is within the HTML
<p>
and </p>
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>
.
ℹ | Another way to add text to the home web page is discussed in Infinite Ink’s Introduction to Hugo Bundles in the section Branch bundle example. |
For more about…
the home web page layout, see gohugo.io/templates/homepage/
layout files in general, see gohugo.io/categories/templates/
ℹ | In Go HTML…
|
assets
directoryThe assets
directory looks like this:
assets/ style.scss
style.scss
is the stylesheet for the site.
style.scss
is written in Sassy CSS, which is a
superset of
CSS.
SCSS supports
the following
two types of
comments.
/* CSS multi-line comment */
// SCSS single-line 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.
style.scss
Open assets/style.scss
in a text editor
and insert a comment at the top that says
something like this:
// 2021-01-14: 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:
// 2021-01-14: changed $highlight variable // $highlight: rgb(250, 100, 50); $highlight: blue;
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/.
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/
.
-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.
💡 | To list all drafts, run
hugo list drafts
at a command-line prompt.
Details about the
hugo list command are at
www.ii.com/hugo-cli/#_hugo_list_help. |
hugo
without subcommands or flagsIn the TGIH
directory, run:
hugo 👆 no subcommands or flags
public
directoryThe 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.
| 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
💡 | 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. |
When you build a website with
the
above hugo
command,
the
files
and directories
in
the
static/
[27]
directory, which are highlighted in the directory tree above,
are simply copied to the public/
directory.
Non-static files are processed by hugo
and their destinations are determined by
configuration settings,
front matter,
and
layout files.
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.
source in TGIH/ | destination in TGIH/public/ | URL (if baseURL is ii.com/) |
---|---|---|
static/images/go- | images/go- | ii.com/images/go- |
assets/style.scss | style.css | ii.com/style.css |
content/about.md | about/index.html | ii.com/about/ |
content/articles/one.md | articles/one/index.html | ii.com/articles/one/ |
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
(.cgi
,
.css
, .htm
, .html
, .php
, .png
,
.shtml
, etc.).
For more about all this, see:
Note that the above four gohugo.io URLs are “pretty.”
config.yaml
again🔧Open config.yaml
in a text editor.
baseURL
The
baseURL
setting
is the bolded line below.
baseURL: https://example.org/ 👆 notice this trailing slash
The slash (/
) at the end of the baseURL
can’t
hurt[21]
and sometimes helps, so I recommend that you include it.
When you are really ready to publish
—
rather than learning Hugo
in this
Hugo tutorial
—
replace example.org/
with
your site’s domain name and path, for example:
your.domain.name/
your.domain.name/path/to/your/site/
your.domain.name/blog/
💡 | Instead of setting
baseURL: / This makes it easier to publish the site on a test domain
and have all the intra-site links work.
For example, with this setting
the
TGIH pages
refer to the
stylesheet
as
|
taxonomies
🏷️Above
in step 17.3. Explore the public directory,
you can see that the hugo
command
created
directories named categories
and tags
.
These are Hugo’s
default
taxonomies.
Since the TGIH website uses tags but not categories,
we can clean things up by specifying the following
table[23]
in the config.yaml
.
taxonomies: tag: tags
This overrides Hugo’s default, which is:
taxonomies: category: categories tag: tags
To learn about taxonomies in Hugo, see gohugo.io/content-management/taxonomies/.
💡 | Hugo’s taxonomy terminology changed in v0.73.0, which was released 2020-June-23. Infinite Ink uses the v0.73.0+ terminology (taxonomy and term) but be aware that some old themes and old documents use the pre-v0.73.0 terminology (taxonomyTerm and taxonomy). A clue that a document is documenting Hugo v0.72.0 or earlier is if it contains the string taxonomyTerm without mentioning that it is obsolete in Hugo v0.73.0+. |
‼ | In
a Hugo config file,
variables,
such as
baseURL ,
languageCode ,
and
title ,
are sometimes case sensitive
so I recommend that you specify them using the upper- and
lower-case letters that are specified
in
gohugo.io/getting-started/configuration/. |
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.
Delete the public/
directory before running hugo
or use hugo --cleanDestinationDir
, which deletes everything in the public/
directory other than the
static files.
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:
hugo --cleanDestinationDir --minify
More build flags are listed on Infinite Ink’s Hugo CLI page.
To publish
or deploy
the site,
copy
all the files and directories in the
public/
directory to
the appropriate directory
on
your web-hosting provider’s server.
More information about hosting and deployment is at gohugo.io/hosting-and-deployment/.
exampleSite
from a themeA good way to learn more about Hugo is to do the following.
Browse themes.gohugo.io and find a theme that you like that includes…
an exampleSite
directory
and a README
with clear detailed instructions.
Download the theme and rename its directory
so that it includes the date you downloaded it,
for example
themename-2021-01-14
.
This is useful if you experiment with a lot of themes on a lot of days
over many years
(as I have done).
At a command-line prompt, go to
the
themename-2021-01-14/exampleSite/
directory
and
run
.
Note that
you will probably need to
edit the
config
file
that is in the
exampleSite
directory
so that
the
themesDir
and theme
configuration settings
are set to something like the following.
themesDir: ../.. theme: themename-2021-01-14
Follow the directions in
the README
and experiment with the theme’s files and its example site’s files.
Go to #1 and repeat with another theme.♾
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
.[28]
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.
This section is now on a separate Infinite Ink page called Debugging Your Hugo Website.
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…
Niklas Fasching for his whitespace theme (forked and used in steps 4-18)
markdown-it for the markdown-it live demo source (forked and used in step 6)
The Go programming language for the Go logo (used in step 13) and for the Go language, which is part of the reason that Hugo is so fast
WHOmagoo for giving me feedback on pre-publication versions of this article
Asciidoctor and many other tools and resources that helped me create this article and move the Infinite Ink site into the world of 2019 (and beyond) web development
To comment, you must be signed in to GitHub.
~/Dropbox
or ~/Sync
. To learn about these type of apps and services, see wikipedia.org/wiki/File_hosting_service.hugo.exe
on Windows with the Scoop package manager, first run scoop update
(which updates the Scoop app manifests) and then run either scoop install hugo-extended
scoop update hugo-extended
sudo dpkg --install ./hugo_extended_0.80.0_Linux-64bit.deb
will work if you invoke it from the directory that the .deb
is in. Since hugo
has no dependencies, there should be no issues installing it with dpkg --install
. (This is how I install hugo
on WSL, which is also known as “Windows’ Subsystem for Linux” and “Bash on Ubuntu on Windows.”)more
command is not included in Git Bash, but the less
command, which can do everything more
can do (and more), is.-
) is “hyphen-minus,” but its proper name is rarely used. Instead it is usually referred to as “dash,” “hyphen,” or “minus.” Details are at Hyphen-minus - Wikipedia.disablePathToLower: true
config.yaml
.hugo --minify
<svg>
tag. Information about using SVGs, including inline SVGs, is at svgontheweb.com/#implementation.https://example.org//images/go-logo_black.png
is interpreted as https://example.org/images/go-logo_black.png
.config.toml
, rather than a config.yaml
, the markup
table would need to be placed at the bottom of the config file. I wrote about this above in Endnote 9 and on Infinite Ink’s Hugo Tips, Shortcodes, and Fragments in Fragment 16.home.html
or index.html
. I prefer to name it home.html
because the word index
is semantically overloaded in Hugo.staticDir
parameter in a config file. The default is a single directory named static
..md
could be any of the 13 content file extensions that are known to Hugo (.ad
, .adoc
, .asciidoc
, .htm
, .html
, .markdown
, .md
, .mdown
, .mmark
, .pdc
, .pandoc
, .org
, or .rst
).