| name | hugo-dev |
| description | Develop and preview Hugo static sites. Use when editing Hugo templates, content, CSS, or config. Covers starting the dev server, live preview workflow, content creation, theme development, and building for production. |
Hugo Development
Dev Server
Always start the Hugo dev server in the background before making changes, so the user can see updates live in their browser.
Start Server
pkill -f 'hugo server' 2>/dev/null || true
sleep 1
cd <project-root>
: > /tmp/hugo-server.log
nohup hugo server --buildDrafts --bind 0.0.0.0 -p 1313 &>/tmp/hugo-server.log & disown
for i in $(seq 1 10); do
if grep -q 'Web Server is available' /tmp/hugo-server.log 2>/dev/null; then
echo "Hugo dev server running at http://localhost:1313/"
break
fi
sleep 0.5
done
Important: Always use nohup ... & disown and poll with a for loop. Do NOT use grep -m1 or tail -f to wait — they block the terminal.
Tell the user the site is available at http://localhost:1313/ after starting.
Check Server Status
pgrep -f 'hugo server' && echo "Running" || echo "Not running"
View Server Logs (if something looks wrong)
tail -20 /tmp/hugo-server.log
Stop Server
pkill -f 'hugo server' 2>/dev/null
Live Workflow
Hugo's dev server watches for file changes and automatically rebuilds. The workflow is:
- Start the dev server (see above)
- Make changes to templates, content, CSS, or config
- Changes appear in the browser automatically (Fast Render Mode)
- If changes don't appear (e.g. config changes), restart the server
Note: Changes to hugo.toml require a server restart. Template and content changes are picked up automatically.
Content
Create a New Blog Post
Blog posts use page bundles for co-located images:
mkdir -p content/blog/<slug>
Then create content/blog/<slug>/index.md:
---
title: "Post Title"
date: YYYY-MM-DD
description: "Brief summary for listings and meta tags."
tags: ["tag1", "tag2"]
draft: true # Remove when ready to publish
---
Post content in Markdown...
Place post-specific images in the same directory as index.md.
Data-Driven Sections
Projects, resume, and quotes are not individual content pages. They are driven by YAML data files:
data/projects.yaml — project entries (name, url, description, tech)data/resume.yaml — experience, education, skillsdata/quotes.yaml — quote entries (text, author, source)
Edit the YAML files to update these sections. The templates in themes/minimal/layouts/<section>/list.html render them.
Theme Development
File Locations
All theme files are in themes/minimal/:
themes/minimal/
├── assets/css/style.css # ALL styling — edit this for design changes
├── layouts/
│ ├── _default/
│ │ ├── baseof.html # Base template (html, head, body wrapper)
│ │ ├── list.html # Default list page (blog index)
│ │ └── single.html # Default single page (blog post)
│ ├── partials/
│ │ ├── head.html # <head> contents (meta, CSS)
│ │ ├── header.html # Site header + navigation
│ │ └── footer.html # Site footer
│ ├── index.html # Home page
│ ├── blog/ # (uses _default/ templates)
│ ├── projects/list.html # Projects listing
│ ├── quotes/list.html # Quotes listing
│ └── resume/list.html # Resume page
└── theme.toml
CSS Architecture
assets/css/style.css uses CSS custom properties for all design tokens. To change the look:
- Edit
:root { ... } for light mode colors
- Edit
@media (prefers-color-scheme: dark) { :root { ... } } for dark mode
- Key variables:
--color-bg, --color-text, --color-accent, --color-link, --font-body, --font-mono, --max-width, --spacing, --radius
Override Without Modifying Theme
To override a template without changing the theme, copy it to the site-level layouts/ directory with the same path:
cp themes/minimal/layouts/partials/footer.html layouts/partials/footer.html
Same for assets — site-level assets/ overrides themes/minimal/assets/.
Production Build
hugo --minify
Output goes to public/. This is the only command needed for CI/CD.
Troubleshooting
- Blank page: Check
hugo.toml has theme = 'minimal' and templates exist
- CSS not updating: Hard-refresh browser (Cmd+Shift+R) — Hugo fingerprints CSS
- Template errors: Check
tail -20 /tmp/hugo-server.log for error messages
- New section not appearing: Ensure
content/<section>/_index.md exists and a matching layout exists in themes/minimal/layouts/<section>/
