. └── hugo-bundles/ ├── index.md └── hgopher.svg
This article
assumes
you
know
how
to use
Hugo
to generate
web pages from
source files
that are not bundles.
One way to learn about
that
is
in
Infinite Ink’s
TGIH: Themeless & Gitless Introduction to the Hugo SSG (a Hugo tutorial).
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…
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 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.
The source of this article is an example of a leaf bundle with a page resource. Here are the details.
If a leaf bundle looks something like this…
. └── hugo-bundles/ ├── index.md └── hgopher.svg
…then
you can use the following
Markdown image syntax in index.md
to reference
the image.
 ----------- 👆 path relative to index.md
With the above source directory structure, Hugo will generate a destination directory structure and HTML code that a web browser will display like this web page, including the following image:
💡 |
|
hugo new
to create a leaf bundleIf ROOT/archetypes/default.md
exists, you can
use a command like the following to
create a new
leaf bundle:
hugo new articles/directory-name/index.md -------------- 👆 used as .Name in archetype’s Go HTML
To learn about Hugo archetypes, see step 11. Edit the archetype for new .md content files in Infinite Ink’s Hugo Tutorial.
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.
In this section I describe
some
metaphors
I use to
remember the
meanings
of
_index.extension
and
index.extension
.
I remember the meaning of
_index.extension
by
imagining
that
the
leading
underscore (_
)
is
one or more of these:
a fragment of capital letter L, which reminds me that
_index
is used for
a
List Page
a doorway that allows Hugo to enter and process any child page — either a child Regular Page or a child List Page — within this directory🚪
a
tree branch
or
plant branch
that may comprise multiple
leaves
and/or
multiple
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.
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/
www.ii.com’s
the shortcodes get-leaf-text and html4-get-bundle-image in Hugo Shortcodes
For more about Hugo, see Infinite Ink’s…
Hugo Shortcodes: Including Go Templates in Hugo Content Files
🔗 Linkified Section Headings in Hugo-Generated Web Pages (featuring Markdown and AsciiDoc examples)
Hugo’s .RenderString
Method (featuring AsciiDoc admonitions in Markdown and Go HTML)
A Way to Compare Hugo’s Markup Languages (featuring inline footnotes)📊
Configuring Security in Hugo (featuring settings needed to use Asciidoctor and Pandoc)🔒
Variable and Parameter Names in Hugo (featuring camelCase🐫 and snake_case🐍)
TGIH: Themeless & Gitless Introduction to the Hugo SSG (a Hugo tutorial)
Hugo’s Markup Languages: AsciiDoc, HTML, Markdown,
Transforming Text with Hugo (featuring plainify
, htmlUnescape
, and more)
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.@nm@mathstodon.xyz
or
#InfiniteInk
in it.