feat: initialize Hugo static site with Bootstrap 5.x
Initialize minimal Hugo site structure with Bootstrap 5.3.2 integration for markusgraf.ch conversion. Implements OpenSpec proposal add-minimal-hugo-site. Features: - Hugo project structure with standard directories - Base layout template (baseof.html) with Bootstrap 5.3.2 via CDN - Homepage (index.html) and single page (single.html) templates - Reusable partials: header, footer, navigation - Responsive Bootstrap grid layout - Mobile-first design with semantic HTML5 - Valid HTML output with basic accessibility features - Taxonomies disabled for minimal site (see docs/TAXONOMIES.md) Documentation: - IMPLEMENTATION_SUMMARY.md - Complete implementation guide - docs/TAXONOMIES.md - Guide for re-enabling categories/tags - static/README.md - Guide for placing static assets Configuration: - hugo.toml configured for markusgraf.ch - .gitignore for Hugo build artifacts All 24 tasks from OpenSpec proposal completed successfully. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Markus Graf
@@ -0,0 +1,224 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user