Troubleshooting Guide - ScrumGuides/ScrumGuide-ExpansionPack GitHub Wiki

This guide helps you diagnose and resolve common issues when working with the Scrum Guide Expansion Pack project.

Problem: Command hugo not found after installation.

Solutions:

# Check if Hugo is installed
hugo version

# If not found, install Hugo Extended
# Windows (Chocolatey)
choco install hugo-extended

# Windows (Scoop)
scoop install hugo-extended

# Verify installation
hugo env

Problem: Site doesn't build due to Hugo version mismatch.

Check Requirements:

# Check current Hugo version
hugo version

# Required: Hugo Extended v0.120.0 or higher
# Upgrade if necessary
choco upgrade hugo-extended

Problem: Error about missing Hugo Extended features.

Solution:

# Verify you have Hugo Extended
hugo env | Select-String "extended"

# Should show: extended: true
# If false, reinstall Hugo Extended

Problem: hugo server fails to start.

Diagnostic Steps:

# Navigate to correct directory
cd site

# Check Hugo -Configuration-Reference
hugo config

# Try with verbose output
hugo server -D --verbose --debug

# Check for port conflicts
netstat -an | Select-String ":1313"

Common Solutions:

• Ensure you're in the /site directory
• Check that port 1313 isn't already in use
• Verify hugo.yaml syntax is correct
• Clear Hugo cache: hugo --gc

Problem: New content doesn't show on the site.

Checklist:

• File is in correct location (/content/)
• Front matter includes draft: false
• File has .md extension
• Content follows proper Markdown syntax
• Hugo server was restarted after adding content

Debug Commands:

# List all content Hugo recognizes
hugo list all

# Check specific content
hugo list drafts
hugo list future
hugo list expired

Problem: Changes don't automatically refresh the browser.

Solutions:

# Start server with explicit live reload
hugo server -D --liveReload --watch

# Try binding to all interfaces
hugo server -D --bind 0.0.0.0 --liveReload

# Clear browser cache (Ctrl+F5)

Problem: Language switcher doesn't work properly.

Check -Configuration-Reference:

# Verify in hugo.yaml
languages:
  en:
    languageName: "English"
    weight: 1
  de:
    languageName: "Deutsch"
    weight: 2

Verify Content Structure:

content/
├── en/
│   └── guide/
│       └── index.md
└── de/
    └── guide/
        └── index.md

Problem: Some text appears in wrong language.

Solutions:

1. Check i18n files:

   # i18n/en.yaml
   - id: "nav_home"
     translation: "Home"
   
   # i18n/de.yaml
   - id: "nav_home"
     translation: "Start"

2. Verify template usage:

   {{ i18n "nav_home" }}

3. Check for missing Translation-Guide:

   # Search for untranslated strings
   Select-String -Path "layouts/**/*.html" -Pattern "{{ i18n" | Where-Object { $_.Line -notmatch "translation" }

Problem: Markdown content appears as plain text.

Common Causes:

• Incorrect file extension (should be .md)
• Missing or malformed front matter
• Hugo goldmark -Configuration-Reference issues

Solutions:

# Test markdown processing
hugo server -D --verbose

# Check goldmark -Configuration-Reference in hugo.yaml
markup:
  goldmark:
    renderer:
      unsafe: true

Problem: Images don't display on the site.

Diagnostic Steps:

1. Check file location:

   static/images/your-image.jpg  # ✅ Correct
   content/images/your-image.jpg # ❌ Wrong
   

2. Verify image path in markdown:

   ![Alt text](https://github.com/ScrumGuides/ScrumGuide-ExpansionPack/blob/main/docs//images/your-image.jpg) # ✅ Correct
   ![Alt text](https://github.com/ScrumGuides/ScrumGuide-ExpansionPack/blob/main/docs/images/your-image.jpg) # ❌ Wrong

3. Check file permissions:

   # Verify file exists and is readable
   Test-Path "static/images/your-image.jpg"

Problem: Content doesn't appear due to front matter issues.

Valid Front Matter Example:

---
title: "Page Title"
description: "Page description"
date: 2025-06-09
draft: false
weight: 10
---

Common Issues:

• Missing closing ---
• Invalid YAML syntax (tabs instead of spaces)
• Missing required fields

Problem: hugo command fails to build the site.

Diagnostic Steps:

# Build with verbose output
hugo --verbose --debug

# Check for template errors
hugo --templateMetrics

# Validate -Configuration-Reference
hugo config

Common Solutions:

• Fix template syntax errors
• Resolve missing partials or layouts
• Check for circular references
• Verify all required assets exist

Problem: Hugo takes too long to build.

Performance Analysis:

# Analyze build performance
hugo --templateMetrics --templateMetricsHints

# Check what's being processed
hugo --verbose | Select-String "processing"

Optimization Tips:

• Use hugo --gc to clean up
• Optimize large images
• Review template complexity
• Enable caching for -Development-Guide

Problem: -Deployment-Guide workflow fails.

Check Workflow Status:

# Using GitHub CLI
gh run list --workflow=deploy.yml
gh run view --log <run-id>

Common Issues:

• Missing secrets in repository settings
• Incorrect Azure Static Web Apps token
• Hugo version mismatch in workflow
• Build errors not caught locally

Problem: Site doesn't deploy or load correctly.

-Configuration-Reference Checklist:

• staticwebapp.config.json is valid JSON
• Routes are configured correctly
• Build output is in correct directory
• Custom domain is configured properly

Debug Steps:

1. Check Azure portal for -Deployment-Guide logs
2. Verify build output in GitHub Actions
3. Test routes manually
4. Check browser console for errors

Problem: Bootstrap styles not applied.

Solutions:

<!-- Check that Bootstrap is included in baseof.html -->
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" />

Problem: Custom styles don't appear.

Checklist:

• CSS file is in /static/css/ directory
• CSS is linked in template
• Browser cache is cleared
• CSS syntax is correct

Debug Steps:

# Check CSS file exists
Test-Path "static/css/style.css"

# Verify CSS is served
# Visit: http://localhost:1313/css/style.css

Problem: Analytics not tracking visits.

Check -Configuration-Reference:

# In hugo.yaml
params:
  googleAnalytics: "G-XXXXXXXXXX"

Verify Implementation:

<!-- Should be in <head> section -->
{{ if .Site.Params.googleAnalytics }}
<!-- Google Analytics code -->
{{ end }}

Problem: SEO meta tags not appearing.

Check Template:

<!-- In baseof.html <head> section -->
<meta name="description" content="{{ .Description }}" />
<meta property="og:title" content="{{ .Title }}" />
<meta property="og:description" content="{{ .Description }}" />

Problem: Pages load slowly.

Optimization Checklist:

• Images optimized (WebP format, appropriate sizes)
• Minification enabled (hugo --minify)
• CDN caching configured
• Unused assets removed

Performance Testing:

# Test with Hugo's built-in server
hugo server --minify

# Use browser dev tools to analyze performance
# Check Network tab for slow resources

Problem: Generated site is too large.

Analysis:

# Check generated site size
cd public
Get-ChildItem -Recurse | Measure-Object -Property Length -Sum

Optimization:

• Compress images before adding to /static/
• Remove unused CSS and JavaScript
• Use Hugo's image processing for responsive images
• Enable minification and compression

Common Issues:

• Port 1313 already in use
• File path issues on Windows
• Hugo cache corruption

Solutions:

# Use different port
hugo server -D --port 1314

# Clear Hugo cache
hugo --gc

# Reset -Development-Guide environment
Remove-Item -Recurse -Force public/, resources/

Common Issues:

• Robots.txt blocking indexing
• Different -Configuration-Reference not loading
• Analytics not working in preview

Check -Configuration-Reference:

# hugo.preview.yaml should have:
enableRobotsTXT: false
params:
  googleAnalytics: "" # Disabled for preview

Common Issues:

• SSL certificate problems
• Custom domain not working
• Caching issues

Solutions:

1. SSL Issues: Wait for certificate provisioning (up to 24 hours)
2. Domain Issues: Check DNS -Configuration-Reference
3. Caching: Clear CDN cache in Azure portal

1. Check Hugo version and ensure it's Extended
2. Verify you're in correct directory (/site for Hugo commands)
3. Test with minimal -Configuration-Reference to isolate issues
4. Check browser console for JavaScript errors
5. Review recent changes that might have caused issues

# Enable verbose logging
hugo server -D --verbose --debug --log

# Generate -Configuration-Reference info
hugo config > hugo-config-dump.txt

# List all content
hugo list all > content-list.txt

Create a GitHub issue when you:

• ✅ Followed -Troubleshooting-Guide steps above
• ✅ Provided detailed error messages
• ✅ Included system information (Hugo version, OS, etc.)
• ✅ Described steps to reproduce the issue

When reporting issues, include:

## Problem Description
Brief description of the issue

## Environment
- OS: Windows/macOS/Linux
- Hugo Version: (from `hugo version`)
- Browser: Chrome/Firefox/Safari
- Environment: Local/Preview/Production

## Steps to Reproduce
1. Step one
2. Step two
3. Expected vs actual result

## Error Messages

Paste any error messages here

## Additional Context
Any other relevant information

• Hugo Documentation: https://gohugo.io/documentation/
• Azure Static Web Apps Docs: https://docs.microsoft.com/azure/static-web-apps/
• Bootstrap Documentation: https://getbootstrap.com/docs/
• GitHub Actions Docs: https://docs.github.com/actions

🔙 Back to: Documentation Home
🏠 Return to: Project Root