This article
assumes that you
know
how
to use
Hugo
to generate
web pages from
source files
that are not bundles.
One way to learn about this is
in
Infinite Ink’s
Hugo Tutorial: Themeless & Gitless Introduction to the Hugo Static Site Generator.
Here is part of that tutorial’s
content
directory,
along with
some Hugo terminology:
| TGIH/content | .Kind[2] | Also Known As |
|---|---|---|
| home | List Page |
| page | Regular Page |
| section | List Page |
page | Regular Page |
Note that…
Infinite Ink’s Hugo Tutorial uses a project directory named TGIH.
None of the TGIH content files and directories are bundles.
Some TGIH content files and directories are converted to bundles in the examples below.
Since Hugo v0.18, which was released 2016-December-19, “every piece of content is a Page.”
A source file
below
the content/ directory
named
either
index.md
or
_index.md
means that
hugo
will
generate
the
destination
file(s)
from
some or all of the
files in
a
directory.
When index.md is used, the containing directory is called a leaf bundle
and when _index.md is used, the containing directory is called a
branch bundle.
ℹ |
|
Step 17.4[3] in Infinite Ink’s Hugo Tutorial discusses the transformation of some TGIH[4] files from source to destination to URL (viewable in a web browser after deployment). Here is a modified version of that transformation table.
source in | about.md | articles/one.md |
|---|---|---|
↓ | ↓ | ↓ |
destination in | about/index.html | articles/one/index.html |
↓ | ↓ | ↓ |
URL (if baseURL | ii.com/about/ | ii.com/articles/one/ |
An equivalent alternative is to
replace
about.md
with
about/index.md
and
replace
articles/one.md
with articles/one/index.md.
The transformations then looks like this:
source in | about/index.md | articles/one/index.md |
|---|---|---|
↓ | ↓ | ↓ |
destination in | about/index.html | articles/one/index.html |
↓ | ↓ | ↓ |
URL (if baseURL | ii.com/about/ | ii.com/articles/one/ |
With
this structure,
the
source
directories
content/about/
and
content/articles/one/
are
each a
leaf bundle.
In
step 15
in Infinite Ink’s Hugo Tutorial,
I wrote about adding content to the TGIH home page,
which is a
List Page,
by adding the
following
highlighted
HTML paragraph
to
the home.html[6]
layout file.
<h1 class="title">{{ .Title }}</h1>
<p>
Here are the articles on this website <strong>ordered by publication date</strong>, starting with the most recently published article.
</p>
An alternative is to put the following highlighted line in home.html.
<h1 class="title">{{ .Title }}</h1>
{{ .Content }}
And create content/_index.md that contains the following.
---
# front matter, possibly empty, is required
---
Here are the articles on this website **ordered by publication date**, starting with the most recently published article.
The content/ directory
is an example of a
branch bundle
and this content/_index.md file contains metadata
(essentially empty
in this case) and Markdown content for the home page.
The transformation will look like this:
source in | _index.md |
|---|---|
↓ | ↓ |
destination in | index.html |
↓ | ↓ |
URL (if baseURL | ii.com/ |
Note that if this _index.md file does not exist,
the home page is created
entirely
from
the
TGIH
layouts/_default/home.html
layout file,
which references
some
config
settings,
such as the title site variable.
In this section I describe
some
metaphors
that I use to
remember the
meanings
of
_index.extension
and
index.extension.
I imagine
the
leading
underscore (_)
as
one or more of the following.
a doorway or portal that allows Hugo to enter and process any child page — either a Regular Page or a List Page — within this directory🚪
a
tree branch
or
plant branch
that may comprise multiple
leaves
and/or
multiple
a fragment of capital letter L, which reminds me that
_index
is used for
a
List Page
I remember the meaning of
index.extension
by noting that there is
no doorway
or
branch (i.e.,
no _)
and Hugo will
process
this directory as a
Regular Page,
which is also known as a
leaf
To learn more about Hugo bundles, see:
discourse.gohugo.io/t/naming-content-files-index-md-vs-index-md-vs-foo-md/24043
regisphilibert.com/blog/2018/01/hugo-page-resources-and-how-to-use-them/
the shortcodes get-leaf-text and html4-get-bundle-image in Infinite Ink’s Hugo Tips, Shortcodes, and Fragments
hugo config command includes uglyURLs: false, which is the default, and baseURL: ii.com/.home.html or index.html. I prefer to name it home.html because the word index is semantically overloaded in Hugo.