Mastering Images in Hugo

Learn how to implement and optimize images in your Hugo markdown content

Image Examples in Markdown

This post demonstrates various ways to implement images in Hugo markdown files using the images module. We’ll cover everything from basic image insertion to advanced optimization techniques.

Basic Image Implementation

Using Standard Markdown Syntax

The simplest way to add an image is using standard markdown syntax:

![Alt text](image.jpg "Optional title")

However, this doesn’t take advantage of Hugo’s powerful image processing capabilities.

Using Hugo Shortcodes

For better control and optimization, use the custom shortcodes provided by the images module:

Basic Image Shortcode

{{< img src="inline-example.jpg" alt="Example image in content" >}}

This automatically generates multiple sizes, WebP formats, and implements lazy loading.

Figure with Caption

{{< figure src="example-1.svg" alt="Figure example" caption="This figure demonstrates **Hugo's image processing** with a *markdown-enabled* caption" >}}

Advanced Image Techniques

Custom Sizing

You can specify custom breakpoints for responsive images:

{{< img src="example-1.svg" alt="Custom sizes" sizes="300,600,1000" >}}

Disabling Lazy Loading

For above-the-fold images, disable lazy loading for better performance:

{{< img src="example-1.svg" alt="No lazy loading" lazy="false" >}}

Image Galleries

Create responsive image galleries with lightbox functionality:

{{< gallery images="example-1.svg,example-2.svg,example-3.svg" cols="3" >}}

Click on any image to open the lightbox viewer with keyboard navigation support.

Image Optimization Comparison

Before and After Hugo Processing

Let’s compare images before and after Hugo’s optimization:

Before Optimization

After Hugo Processing

Performance Benefits

Automatic Optimizations

Hugo’s image processing provides several automatic optimizations:

1. Multiple Formats: WebP generation with fallbacks
2. Responsive Sizes: Automatic breakpoint generation
3. Quality Optimization: 85% quality for optimal size/quality balance
4. Lazy Loading: Intersection Observer implementation
5. Proper Dimensions: Width and height attributes for layout stability

Loading Performance

Images below the fold are loaded only when they enter the viewport, significantly improving initial page load times.

SEO and Accessibility

Proper Alt Text

Always provide descriptive alt text for accessibility:

{{< img src="example.jpg" alt="Detailed description of what the image shows" >}}

Structured Data

The shortcodes automatically include proper structured data:

• Width and height attributes
• Proper alt text
• Optimized file formats
• Responsive srcset attributes

Best Practices

1. Choose the Right Shortcode

• {{< img >}}: Basic responsive images
• {{< figure >}}: Images with captions
• {{< gallery >}}: Multiple related images
• {{< hero-image >}}: Large featured images

2. Optimize Source Images

• Use high-quality source images (Hugo will optimize them)
• Prefer landscape orientation for hero images
• Keep source files in common formats (JPG, PNG, WebP)

3. Consider Context

• Use lazy="false" for above-the-fold images
• Provide meaningful alt text for screen readers
• Use captions to provide additional context

4. Test Across Devices

The responsive images automatically adapt to:

• Mobile devices: Smaller, optimized images
• Tablets: Medium-sized images
• Desktop: Full-resolution images
• High-DPI displays: Appropriate pixel density

Technical Implementation

Page Resources

This post uses Hugo’s page resources feature. Images are stored alongside the content:

content/posts/image-examples/
├── index.en.md
├── post-hero.jpg
├── inline-example.jpg
├── comparison-before.jpg
├── comparison-after.jpg
├── gallery-1.jpg
├── gallery-2.jpg
└── gallery-3.jpg

Frontmatter Configuration

Images are defined in the frontmatter:

resources:
- src: "post-hero.jpg"
  title: "Post Hero Image"
  params:
    alt: "Hero image for the image examples post"

This allows Hugo to process and optimize them automatically.

Conclusion

The images module provides a comprehensive solution for handling images in Hugo:

• Native Hugo Processing: Leverages Hugo’s built-in image optimization
• Modern Web Standards: WebP, responsive images, lazy loading
• Accessibility: Proper alt text and structured data
• Performance: Optimized loading and file sizes
• Developer Experience: Simple shortcode syntax

By following these patterns, you can create fast, accessible, and visually appealing content that works across all devices and browsers.

This post demonstrates the complete image handling capabilities of the Hugo Modular i18n project. All techniques shown here follow modern web standards and accessibility guidelines.