markusgraf_ch/docs/TAXONOMIES.md

# Hugo Taxonomies Guide

## Current Status

Taxonomies (categories and tags) are **currently disabled** in this Hugo site to keep it minimal.

## What Are Taxonomies?

Hugo taxonomies are classification systems for your content:
- **Categories** - Broad groupings (e.g., "Technology", "Personal", "Projects")
- **Tags** - Specific keywords (e.g., "golang", "web-development", "tutorial")

They're useful for blogs and content-heavy sites where visitors need to filter and find related content.

## Why Are They Disabled?

For a minimal personal website without a blog, taxonomies add unnecessary complexity:
- Creates extra pages (`/categories/`, `/tags/`) that aren't used
- Requires additional template files
- Generates warning messages during builds

## How to Re-enable Taxonomies

When you're ready to add a blog or need content categorization:

### Step 1: Enable Taxonomies in Configuration

Edit `hugo.toml` and **remove** or **comment out** this line:

```toml
# Remove this line:
disableKinds = ['taxonomy', 'term']
```

Or comment it out to keep for reference:

```toml
# Taxonomies disabled for minimal site - uncomment to enable:
# disableKinds = ['taxonomy', 'term']
```

### Step 2: Create Taxonomy Templates

Create two template files in `layouts/_default/`:

#### `layouts/_default/taxonomy.html`
This template displays all content items for a single category or tag.

```html
{{ define "main" }}
<div class="container">
  <div class="row">
    <div class="col-lg-8 offset-lg-2">
      <header class="mt-5 mb-4">
        <h1 class="display-4">{{ .Title }}</h1>
        <p class="lead text-muted">{{ .Data.Plural }}: {{ len .Pages }} {{ if eq (len .Pages) 1 }}item{{ else }}items{{ end }}</p>
      </header>

      <div class="list-group">
        {{ range .Pages }}
        <a href="{{ .RelPermalink }}" class="list-group-item list-group-item-action">
          <div class="d-flex w-100 justify-content-between">
            <h5 class="mb-1">{{ .Title }}</h5>
            <small class="text-muted">{{ .Date.Format "Jan 2, 2006" }}</small>
          </div>
          {{ if .Description }}
          <p class="mb-1">{{ .Description }}</p>
          {{ end }}
        </a>
        {{ end }}
      </div>
    </div>
  </div>
</div>
{{ end }}
```

#### `layouts/_default/terms.html`
This template lists all available categories or all available tags.

```html
{{ define "main" }}
<div class="container">
  <div class="row">
    <div class="col-lg-8 offset-lg-2">
      <header class="mt-5 mb-4">
        <h1 class="display-4">{{ .Title }}</h1>
        <p class="lead text-muted">Browse all {{ .Data.Plural | lower }}</p>
      </header>

      <div class="row">
        {{ range .Pages }}
        <div class="col-md-6 mb-3">
          <div class="card">
            <div class="card-body">
              <h5 class="card-title">
                <a href="{{ .RelPermalink }}">{{ .Title }}</a>
              </h5>
              <p class="card-text text-muted">{{ len .Pages }} {{ if eq (len .Pages) 1 }}post{{ else }}posts{{ end }}</p>
            </div>
          </div>
        </div>
        {{ end }}
      </div>
    </div>
  </div>
</div>
{{ end }}
```

### Step 3: Add Taxonomies to Content

Add categories and tags to your content front matter:

```markdown
---
title: "My Blog Post"
date: 2024-10-27
categories:
  - Technology
  - Web Development
tags:
  - hugo
  - golang
  - static-sites
---

Your content here...
```

### Step 4: Optional - Configure Menu Links

Add taxonomy pages to your navigation in `hugo.toml`:

```toml
[menu]
  [[menu.main]]
    name = "Categories"
    url = "/categories/"
    weight = 10
  [[menu.main]]
    name = "Tags"
    url = "/tags/"
    weight = 20
```

### Step 5: Optional - Customize Taxonomy Names

If you want different taxonomy names (e.g., "Topics" instead of "Categories"):

```toml
[taxonomies]
  topic = "topics"
  tag = "tags"
```

Then use in front matter:

```markdown
---
topics:
  - Web Development
tags:
  - hugo
---
```

## Testing After Re-enabling

After re-enabling and creating templates:

```bash
# Build the site
hugo

# Start the server
hugo server -D

# Visit in browser:
# http://localhost:1313/categories/
# http://localhost:1313/tags/
# http://localhost:1313/categories/technology/
# http://localhost:1313/tags/hugo/
```

You should see:
- No warnings in build output
- Category and tag listing pages
- Individual category/tag pages showing filtered content

## Custom Taxonomies

Hugo supports custom taxonomies beyond categories and tags:

```toml
[taxonomies]
  category = "categories"
  tag = "tags"
  series = "series"        # For blog post series
  author = "authors"       # For multi-author blogs
  project = "projects"     # For portfolio sites
```

Use in content:

```markdown
---
series: ["Getting Started with Hugo"]
authors: ["Markus Graf"]
projects: ["Personal Website"]
---
```

## References

- [Hugo Taxonomies Documentation](https://gohugo.io/content-management/taxonomies/)
- [Hugo Template Lookup Order](https://gohugo.io/templates/lookup-order/)
- Bootstrap Components used: Cards, List Groups (see [Bootstrap Docs](https://getbootstrap.com/docs/5.3/))

## See Also

- `IMPLEMENTATION_SUMMARY.md` - Overview of the Hugo site structure
- `hugo.toml` - Main configuration file
- `layouts/_default/` - Template directory