Salin dan Bagikan

Hugo Debugging dan Development Tools: Panduan Lengkap

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: "Test Post"]`,
        },
    ).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(), "Test Post") {
        t.Error("Expected content not found")
    }
}

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.

Hugo Debugging dan Development Tools: Panduan Lengkap

Hugo Debugging dan Development Tools: Panduan Lengkap

Built-in Debugging Features

Verbose Logging

Printf Debugging

Hugo Doctor

Template Debugging

Debug Template Rendering

Template Function Reference

Debugging Template Execution

Common Issues dan Solutions

Template Not Rendering

Empty Values

Loop Issues

Development Server Features

Live Reload

Watch and Rebuild

Incremental Builds

Browser DevTools Integration

Source Maps

Local Development dengan ngrok

VS Code Integration

VS Code Settings

Recommended Extensions

Debug Configuration

CI/CD Pipeline Debugging

GitHub Actions Workflow Debug

Build Artifact Inspection

Performance Profiling

Build Timing

Memory Profiling

Logging Configuration

Hugo Logging

Custom Logging

Template Testing

Unit Testing Templates

Integration Testing

Best Practices Checklist

Pre-Commit Checks

Development Workflow

Common Error Messages dan Solutions

Kesimpulan

Artikel Terkait