121 lines
3 KiB
Markdown
121 lines
3 KiB
Markdown
|
---
|
||
|
|
title: "Organizing This Site"
|
||
|
|
date: 2026-04-03
|
||
|
|
draft: false
|
||
|
|
tags: ['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:
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
tags: ['hugo', 'docker', 'tools']
|
||
|
|
```
|
||
|
|
|
||
|
|
Hugo auto-generates pages at `/tags/`, `/tags/hugo/`, etc.
|
||
|
|
|
||
|
|
To define custom taxonomies beyond tags/categories:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
# 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`:
|
||
|
|
|
||
|
|
```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:
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[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.
|