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[1] | 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[2] in Infinite Ink’s Hugo Tutorial discusses the transformation of some TGIH[3] 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[5]
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.
💡 | Here
are some
metaphors
that I use to
remember the meanings of
I imagine
the
leading
underscore (
I remember the meaning of
|
Request: Is this tip useful to you? Whether it is or isn’t, I’d love to hear your thoughts about it because I often wonder if anyone understands the way I’m thinking about things‽
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.