jmopines/site/content/config/site-organization.md

title	date	draft	tags
Organizing This Site	2026-04-03	false	hugo workflow meta

A reference for how this Hugo site is organized and what configuration options are available.

Sections

Sections are created automatically from the directory tree under content/. Any directory with an _index.md file becomes a section with its own list page.

content/
├── _index.md           ← home page
├── about/
│   ├── _index.md       ← /about/ list page
│   ├── whoami.md
│   └── now.md
├── software/
│   ├── _index.md       ← /software/ list page
│   ├── ollama.md
│   └── hugo-setup/     ← page bundle (leaf)
│       ├── index.md
│       └── architecture.svg
└── config/
    ├── _index.md       ← /config/ list page
    └── this-file.md

No config changes are needed — Hugo derives sections from the filesystem.

Taxonomies

Tags and categories are enabled by default. Assign them in front matter:

tags: ['hugo', 'docker', 'tools']

Hugo auto-generates pages at /tags/, /tags/hugo/, etc.

To define custom taxonomies beyond tags/categories:

# hugo.toml
[taxonomies]
  tag = "tags"
  category = "categories"
  series = "series"          # custom

Page bundles

A leaf bundle is a directory with index.md (not _index.md). All sibling files become page resources — images, data files, etc. — that travel with the article.

A branch bundle uses _index.md and represents a section (it can have children).

File	Type	Has children?
index.md	leaf bundle	No
_index.md	branch bundle	Yes

Automatic dating

Three mechanisms, configured in hugo.toml:

enableGitInfo = true

[frontmatter]
  date = [':filename', ':default']
  lastmod = [':git', ':fileModTime']

• :filename — extracts date from 2026-04-03-my-post.md.
• :default — falls back to the date field in front matter.
• :git — uses the Git author date of the last commit.
• :fileModTime — uses the file's mtime on disk.

Automatic tagging

Hugo does not auto-tag content. Tags must be set manually in front matter. The closest workaround is cascade in a section _index.md, which pushes shared parameters to descendants — but it only works for custom .Params fields, not real taxonomy terms.

For true auto-tagging, use an external script or LLM to populate front matter before building.

Menu

The Terminal theme reads showMenuItems from config. To add sections to the nav menu:

[languages.en.menu]
  [[languages.en.menu.main]]
    identifier = "about"
    name = "About"
    url = "/about"
  [[languages.en.menu.main]]
    identifier = "software"
    name = "Software"
    url = "/software"
  [[languages.en.menu.main]]
    identifier = "config"
    name = "Config"
    url = "/config"

Set showMenuItems = 3 (or more) to display them all without a "Show more" toggle.