ROOT/content/meta/about/index.adoc
This article assumes…
you are using Hugo v0.83.0[2] or newer,
you know how to use Hugo bundles,
and
you are comfortable with
zero-based numbering
(0,1,2,…
rather than
1,2,3,…),
which is used in
Go
slice expressions.
By default,
a
Hugo-generated
web page’s URL path
closely matches
the
path of its primary source file.
For example,
the
hugo
command
transforms
this
Infinite Ink
source file:
ROOT/content/meta/about/index.adoc
to this destination file:
ROOT/public/meta/about/index.html
When this destination file is put on the Infinite Ink web server, the URL is:
For more about this, see Infinite Ink’s…
To override Hugo’s default URL paths, you can…
specify Permalinks patterns in a Hugo config file
and/or use one or more of these keys in the front matter of a page’s primary source file:
url
slug
aliases
To learn about this, see gohugo.io/content-management/urls/.
Below
I
give
examples of
using
Permalinks
to specify
non-default
URLs.
The source file of this page is:
ROOT/content/articles/hugo-urls/nested/sections/index.adoc
^^^^^^^^
NoteAnd the destination file is:
ROOT/public/hugo-urls/nested/sections/index.html
The URL of this page is:
https://www.ii.com/hugo-urls/nested/sections/
The scheme is:
https
The hostname (also known as domain name and authority) is:
www.ii.com
The path is:
/hugo-urls/nested/sections/
Each of the following is a path segment:
hugo-urls nested sections
The last part of this
URL path, sections,
is sometimes called the slug.
To learn more about URL terminology, see wikipedia.org/wiki/URL.
articles path segment from this page’s URLSince I do not want
the string
articles
to be
in the URL of this page (or any page in the content/articles/ directory),
I do the following three steps.
Here is the part of Infinite Ink’s directory structure that is relevant to this page’s source file.
.
└── content
├── _index.md
└── articles
├── _index.md
└── hugo-urls
├── _index.md
└── nested
├── _index.md
└── sections
└── index.adocNote:
The four directories content,
articles,
hugo-urls,
and
nested
are each
a branch bundle.
The three directories
articles,
hugo-urls,
and
nested
are each
a section.
articles is sometimes
called the root section.
The last directory, sections, is a leaf bundle
and is not a section.
The file extensions .md and .adoc
can be any
of the
content file extensions known to Hugo.
The content of
each of the four _index.md files can be as simple as this:
--- # Important: Front matter is required. # Because of this _index.md file, this directory is a branch bundle. ---
Permalinks in config.yamlInfinite Ink’s config.yaml includes this:
Permalinks:
articles: /:sections[1:]/:slug/
^^^^
slice syntax
‼ | To use the above slice syntax, you need to be using Hugo v0.83.0[2] or newer. |
hugo command to build the websiteWith the above structure and settings, the hugo command generates this destination file:
ROOT/public/hugo-urls/nested/sections/index.html
products/shirts to p/shirts in Simone’s websiteOn 2021-August-29, Simone posted about Folder hierarchy in permalink in stackoverflow.com’s Hugo tag. Here is an excerpt of his question:
⋮ I want to have URLs like: • content/products/shirts/very-beautiful-shirt.md => /p/shirts/very-beautiful-shirt ⋮
From what he wrote, it seems his content/ directory includes this:
.
└── content
└── products
├── shirts
│ ├── simple.md
│ └── very-beautiful-shirt.md
└── hats
└── simple.mdAnd he wants the hugo command to generate this in the public/ directory:
.
└── public
└── p
├── shirts
│ ├── simple
│ │ └── index.html
│ └── very-beautiful-shirt
│ └── index.html
└── hats
└── simple
└── index.html
Steps A, B, and C below should do this.
To get the URLs that Simone wants, it seems (based on my experiments) that each directory on the path must be a bundle. Here is the structure that works for me:
.
└── content
├── _index.md
└── products
├── _index.md
├── shirts
│ ├── _index.md
│ ├── simple
│ │ └── index.md
│ └── very-beautiful-shirt
│ └── index.md
└── hats
├── _index.md
└── simple
└── index.md
Permalinks in config.yamlSpecify
this in a config.yaml:
Permalinks:
products: /p/:sections[1:]/:filename/
^^^^
slice syntax
Or this in a config.toml:
[permalinks]
products = '/p/:sections[1:]/:filename/'
^^^^
slice syntax
hugo command to build the websiteWith the above structure and settings, the hugo command generates
the destination files and URLs that Simone wants.
:sections slice syntaxSections slice syntax, such as
:sections[1:] used
above, was introduced in Hugo
v0.83.0.[2]
Here are some examples
that help to explain the meaning of this syntax.
| Syntax | Zero-Based Section(s) | Example if sections are articles/hugo-urls/nested |
|---|---|---|
| 0 |
|
| 1 |
|
| 2 |
|
| (last) |
|
| 1,2 |
|
| 0,1,2 |
|
| 0,1 |
|
|
| |
| 1,2,…,(last) |
|
Thanks to the following for some of the above examples.
gohugo.io’s URL Management
github.com’s Allow :sections[1:] etc. in permalinks config · Issue #8363 · gohugoio/hugo
ℹ |
|
To learn about Go slice expressions, see golang.org/ref/spec#Slice_expressions
For more about Hugo, see Infinite Ink’s…
Configuring Security in Hugo (featuring settings needed to use Asciidoctor and Pandoc)
Hugo’s .RenderString Method (featuring AsciiDoc admonitions in Markdown and Go HTML)
A Way to Compare Hugo’s Markup Languages (featuring inline footnotes)
🔗 Linkified Section Headings in Hugo-Generated Web Pages (featuring Markdown and AsciiDoc examples)
Variable and Parameter Names in Hugo (featuring camelCase🐫 and snake_case🐍)
Hugo Tutorial: Themeless & Gitless Introduction to the Hugo SSG
Hugo’s Markup Languages: AsciiDoc, HTML, Markdown,