Debugging adalah skill essential untuk Hugo development. Ketika template tidak bekerja sesuai ekspektasi atau build gagal, kemampuan untuk quickly diagnose dan fix issues sangat penting. Panduan ini akan membahas berbagai tools dan techniques untuk debugging Hugo sites secara effective.

Hugo menyediakan beberapa built-in features untuk debugging, namun knowing how to use them effectively membutuhkan pemahaman tentang Go templates, Hugo internals, dan development workflow yang proper.

Built-in Debugging Features

Verbose Logging

# Basic verbose
hugo --verbose
More detailed output
hugo -v
Debug mode
hugo --debug
With timing information
hugo --timing

Printf Debugging

Template debugging dengan printf adalah teknik sederhana tapi powerful:

{{/* Debug current context */}}
{{ printf "%#v" . }}
{{/
 Debug specific field /}}
{{ printf "Title: %s" .Title }}
{{ printf "Params: %+v" .Params }}
{{ printf "Page: %+v" . }}
{{/
 Debug all available methods /}}
{{ range $key, $value := . }}
{{ printf "%s: %+v" $key $value }}
{{ end }}

Hugo Doctor

# Comprehensive check
hugo doctor
Check specific aspects
hugo doctor config
hugo doctor site
hugo doctor exposures

Template Debugging

Debug Template Rendering

{{/* layouts/partials/debug.html */}}
<div class="debug-panel" style="background: #f5f5f5; padding: 20px; margin: 20px 0;">
    <h3>Template Debug Info</h3>
    <pre><code>Page Title: {{ .Title }}
Page Kind: {{ .Kind }}
Page Type: {{ .Type }}
Section: {{ .Section }}
Slug: {{ .Slug }}
Permalink: {{ .Permalink }}
WordCount: {{ .WordCount }}
ReadingTime: {{ .ReadingTime }}
Date: {{ .Date }}
Lastmod: {{ .Lastmod }}
Draft: {{ .Draft }}
Params:
{{ range $k, $v := .Params }}
{{ $k }}: {{ printf "%#v" $v }}
{{- end }}
</code></pre>
</div>

Template Function Reference

{{/* Available global functions */}}
{{ printf "Now: %s" now }}
{{ printf "Today: %s" today }}
{{/
 Collections /}}
{{ printf "Regular pages: %d" (len .Site.RegularPages) }}
{{ printf "Sections: %d" (len .Site.Sections) }}
{{/
 Resources /}}
{{ range .Resources }}
{{ .ResourceType }}: {{ .RelPermalink }}
{{ end }}

Debugging Template Execution

{{/* Conditional debugging */}}
{{ if ne hugo.Environment "production" }}
    {{ printf "Debug: Current section is %s" .Section }}
{{ end }}
{{/
 Logging /}}
{{ warnf "Debug: Processing page %s" .Title }}
{{ errorf "Error in template: %s" .Title }}

Common Issues dan Solutions

Template Not Rendering

{{/* Check if template is being called */}}
{{ warnf "Template baseof called" }}
{{ block "main" . }}
    {{ warnf "Block main called" }}
    Default content
{{ end }}

Empty Values

{{/* Safe access patterns */}}
{{ .Title | default "Untitled" }}
{{ with .Params.description }}
    Description: {{ . }}
{{ else }}
    Description: Not provided
{{ end }}
{{/
 Check if value exists /}}
{{ if isset .Params "image" }}
Image: {{ .Params.image }}
{{ end }}

Loop Issues

{{/* Range dengan safety check */}}
{{ with .Pages }}
    {{ range . }}
        {{ .Title }}
    {{ end }}
{{ else }}
    No pages found
{{ end }}
{{/
 Check range index /}}
{{ range $index, $element := .Pages }}
{{ printf "Index %d: %s" $index $element.Title }}
{{ end }}

Development Server Features

Live Reload

# Start server dengan live reload
hugo server
Dengan draft pages
hugo server -D
Dengan specific port
hugo server --port 1313
Dengan bind address
hugo server --bind 0.0.0.0

Watch and Rebuild

# Disable automatic rebuild
hugo server --noWatch
Watch specific directories
hugo server --watch --poll 1000
Disable cache
hugo server --noHTTPCache

Incremental Builds

# Enable incremental builds
hugo server --i18n-warnings
Verbose i18n warnings
hugo server --printI18nWarnings

Browser DevTools Integration

Source Maps

Hugo generates source maps untuk debugging:

{{/* Source map akan di-generate otomatis */}}
{{ $js := resources.Get "js/main.js" | js.Build "main.js" }}

Local Development dengan ngrok

# Expose local Hugo server
ngrok http 1313
atau dengan custom subdomain
ngrok http 1313 --subdomain my-hugo-site

VS Code Integration

VS Code Settings

{
    "files.associations": {
        "*.html": "html",
        "*.css": "css",
        "*.js": "javascript"
    },
    "html.format.templating": true,
    "emmet.includeLanguages": {
        "go-html": "html"
    }
}

Recommended Extensions

• Go (for Go development)
• Hugo Language and Syntax Highlight
• Tailwind CSS IntelliSense
• ESLint
• Prettier

Debug Configuration

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Hugo Server",
            "type": "node",
            "request": "launch",
            "program": "${workspaceFolder}/node_modules/.bin/hugo",
            "args": ["server", "-D"],
            "console": "integratedTerminal"
        }
    ]
}

CI/CD Pipeline Debugging

GitHub Actions Workflow Debug

# .github/workflows/debug.yml
name: Debug Workflow
on: [push]
jobs:
debug:
runs-on: ubuntu-latest
steps:

uses: actions/checkout@v4

  - name: Show environment
    run: |
      echo "Hugo version: $(hugo version)"
      echo "Node version: $(node --version)"
      echo "Working directory: $(pwd)"
      echo "Files: $(ls -la)"

  - name: Debug Hugo config
    run: |
      hugo config
      hugo --printPathWarnings
      hugo --printI18nWarnings
Build Artifact Inspection
# Download dan inspect build artifacts
gh run download <run-id>
Check build output
cat public/index.html | head -100
Performance Profiling
Build Timing
# Show timing information
hugo --timing
Detailed timing
hugo --profile
Memory Profiling
# Enable memory profiling
hugo --profile --profileDir=./profiles
Analyze profiles dengan pprof
go tool pprof ./profiles/mem.pprof
Logging Configuration
Hugo Logging
# Set log level
hugo --logLevel debug
Log to file
hugo --logFile hugo.log
Custom Logging
{{/* Di templates */}}
{{ warnf "Warning: %s" "message" }}
{{ errorf "Error: %s" "message" }}
{{ printf "Debug: %v" . }}
Template Testing
Unit Testing Templates
// template_test.go
package main
import (
"testing"
"github.com/gohugoio/hugo/hugolib"
)
func TestTemplateRendering(t *testing.T) {
sites, _ := hugolib.NewIntegrationTestBuilder(
hugolib.IntegrationTestConfig{
T:           t,
Content: 
[title: &quot;Test Post&quot;],
},
).Build()
// Check output
// Assert(template.ContainsString(...))
}
Integration Testing
// integration_test.go
package main
import (
"testing"
"github.com/gohugoio/hugo/hugolib"
)
func TestFullSite(t *testing.T) {
sites, _ := hugolib.NewIntegrationTestBuilder(
hugolib.IntegrationTestConfig{
T:           t,
LogLevel:    hugolib.LogWarn,
Content: []string{
"posts/post-1.md",
"posts/post-2.md",
},
Templates: []string{
"index.html": 
{{ range .Site.RegularPages }}{{ .Title }}{{ end }},
},
},
).Build()
// Verify output
b := sites.H.Sites[0]
if !contains(b.String(), &quot;Test Post&quot;) {
    t.Error(&quot;Expected content not found&quot;)
}
}
Best Practices Checklist
Pre-Commit Checks
#!/bin/bash
# scripts/pre-commit-check.sh
set -e
Run Hugo check
hugo check
Validate templates
hugo --printUnusedTemplates
Check for broken links
(add link checker)
Verify build
hugo --minify
Development Workflow
Gunakan hugo server untuk live development
Check Hugo doctor secara regular
Gunakan printf debugging untuk template issues
Test di multiple browsers
Measure performance dengan Lighthouse
Document custom configurations
Common Error Messages dan Solutions
Error
Solution
template not found
Check template paths dan naming
can’t evaluate field
Verify field exists di context
EOF in shortcode
Check shortcode syntax
resource not found
Verify asset path
duplicate output
Check output formats config
Kesimpulan
Debugging Hugo sites membutuhkan kombinasi dari built-in features, development tools, dan systematic approach. Dengan menguasai teknik-teknik yang dibahas dalam panduan ini, Anda akan lebih efficient dalam troubleshooting dan maintaining Hugo sites.