Hugo Blog Workflow
This skill provides comprehensive guidance for working with Hugo static site generators, with specific expertise in blog management, content creation, theme customization, and deployment workflows.
What This Skill Does
Manages Hugo development servers and build processesCreates and organizes blog posts, pages, and contentCustomizes Hugo themes and configurationHandles GitHub Pages deploymentMaintains site architecture and navigationSupports content taxonomies (tags, categories, series)Instructions
1. Development Server Management
When the user wants to preview or develop the site:
Use `hugo server -D` to start development server with draft contentUse `hugo server` for published content onlyAccess the site at `http://localhost:1313/` (default)Server auto-reloads on file changesCheck Hugo version with `hugo version` if troubleshooting2. Content Creation
When creating new blog posts:
```bash
Create new post
hugo new posts/descriptive-post-title.md
```
**Frontmatter template:**
```yaml
---
title: "Descriptive Post Title"
date: YYYY-MM-DD
draft: false
tags: ["tag1", "tag2"]
categories: ["category"]
---
```
When creating new pages:
```bash
hugo new about/index.md
hugo new projects/index.md
```
**Content guidelines:**
Use descriptive filenames with hyphens (kebab-case)Place images in `static/` directoryUse relative links for internal contentLeverage Hugo shortcodes for enhanced functionalityKeep drafts with `draft: true` until ready to publish3. Site Architecture
**Key directories:**
`/content/` - All markdown content (posts, pages)`/content/posts/` - Blog posts`/static/` - Static assets (images, CSS, favicon)`/themes/` - Theme files`/public/` - Generated site output (git-ignored or deployment target)**Configuration file:**
`hugo.toml` (or `config.toml`) - Main site configurationContains baseURL, theme, params, menus, taxonomies4. Building and Deployment
**Production build:**
```bash
Build static site to public/ directory
hugo
Clean previous build
rm -rf public/
hugo
```
**GitHub Pages deployment:**
1. Run `hugo` to generate static files in `public/`
2. Commit and push changes to repository
3. GitHub Pages automatically deploys from configured source
**Useful commands:**
```bash
View all content with status
hugo list all
Verbose output for debugging
hugo --verbose
Check for broken links
hugo --verbose
```
5. Theme Customization
**Risotto theme (terminal-inspired):**
Minimalist design with terminal aestheticBase16 color schemes (16 palettes available)CSS Grid responsive layoutNo JavaScript dependency**Available palettes:**
`base16-dark`, `base16-light``gruvbox-dark`, `gruvbox-light``solarized-dark`, `solarized-light``dracula`, `tokyo-night-dark`, `tokyo-night-light``material`, `papercolor-dark`, `papercolor-light``apprentice`, `tender``windows-95`, `windows-95-light`**Customization:**
Switch palette in `hugo.toml`: `params.theme.palette = "palette-name"`Add custom CSS to `static/css/` directoryPlace favicon files in `static/` directory6. Configuration Management
**Key `hugo.toml` sections:**
```toml
baseURL = "https://example.github.io/"
languageCode = "en-us"
title = "Site Title"
theme = "risotto"
[params]
theme.palette = "base16-dark"
[author]
name = "Author Name"
email = "[email protected]"
[[params.socialLinks]]
icon = "github"
title = "GitHub"
url = "https://github.com/username"
[menu]
[[menu.main]]
identifier = "about"
name = "About"
url = "/about/"
weight = 10
```
7. Content Organization Best Practices
**Taxonomies:**
Use `tags` for specific topics or technologiesUse `categories` for broader content groupsUse `series` for multi-part posts**File naming:**
Use lowercase with hyphens: `my-blog-post.md`Use descriptive names that indicate contentKeep URLs clean and SEO-friendly**Frontmatter best practices:**
Always include `title`, `date`, `draft` statusAdd relevant tags and categoriesUse ISO date format: `2024-01-15`8. Troubleshooting
**Common issues:**
**Build errors**: Run `hugo --verbose` to see detailed output**Theme not found**: Check theme is in `themes/` and matches config**Broken links**: Use `hugo --verbose` to check for issues**Port already in use**: Kill existing server or use `hugo server -p 1314`**Changes not reflecting**: Clear browser cache or use incognito mode9. Workflow Integration
**Typical development flow:**
1. Start development server: `hugo server -D`
2. Create new content: `hugo new posts/topic.md`
3. Edit content in text editor
4. Preview changes in browser (auto-reload)
5. Remove `draft: true` when ready to publish
6. Build for production: `hugo`
7. Deploy via git push (GitHub Pages) or upload `public/` directory
10. Reading Configuration
Before making changes:
Always read `hugo.toml` (or `config.toml`) to understand current configurationCheck `content/_index.md` for homepage contentReview theme documentation if customizingExamine existing content for frontmatter patternsImportant Notes
Hugo uses Goldmark for markdown rendering (CommonMark compliant)Content files must be in `content/` directory to be processedStatic files in `static/` are copied directly to `public/` rootDraft content only appears with `-D` flag or `draft: false`The `public/` directory is regenerated on each build (don't edit directly)Always test locally before deploying to productionExample Usage
**User**: "Create a new blog post about malware analysis"
**Expected workflow:**
1. Run `hugo new posts/malware-analysis-techniques.md`
2. Open the created file
3. Update frontmatter with appropriate title, tags (`malware`, `analysis`, `security`)
4. Add content below frontmatter
5. Start dev server if not running: `hugo server -D`
6. Preview at localhost:1313
**User**: "Change the site theme to gruvbox dark"
**Expected workflow:**
1. Read `hugo.toml` configuration file
2. Locate `params.theme.palette` setting
3. Change value to `gruvbox-dark`
4. Restart Hugo server to see changes
5. Verify theme applied correctly in browser