Dynamic OG Image Generation in Hugo Paper

Hugo Paper introduces a powerful dynamic OG image generation feature that automatically creates beautiful, relevant social media preview images for your blog posts using the Unsplash API.

Table of contents

Introduction

Open Graph (OG) images are crucial for social media sharing, providing visual previews when your blog posts are shared on platforms like Twitter, Facebook, LinkedIn, and others. These preview images can increase click-through rates by 30-50% and significantly improve engagement.

While Twitter technically uses “Twitter Cards” rather than Open Graph, we’ll use the term “OG image” to refer to all social media preview images for simplicity.

The Traditional Approach

Traditionally, Hugo themes handle OG images in one of two ways:

1. Manual specification: Authors specify an image path in the frontmatter (cover or image field)
2. Static fallback: A single default image is used for all posts without a specified image

The problem: The static fallback approach means every blog post without a custom image uses the same generic preview, regardless of the post’s content. This results in:

• Poor visual differentiation between posts
• Lower engagement rates
• Time-consuming manual image creation for each post

Hugo Paper’s Dynamic Solution

Hugo Paper takes a different, more efficient approach using the Unsplash Source API to dynamically generate relevant OG images based on your post’s content.

How It Works

Instead of generating static image files at build time, Hugo Paper:

1. Extracts keywords from your post’s frontmatter (keywords, tags, categories, or title)
2. Generates an Unsplash URL that fetches a relevant, high-quality image
3. Serves images via CDN - no storage or bandwidth costs on your end

Dynamic OG images are automatically generated for posts that:

• Don’t specify a cover or image in the frontmatter
• Are not marked as draft
• Have the feature enabled in configuration

Key Advantages

• ✅ Zero build time impact - URLs are generated instantly
• ✅ No storage required - Images served from Unsplash CDN
• ✅ High-quality images - Professional photography from Unsplash
• ✅ Relevant content - Images match your post’s keywords
• ✅ No API key needed - Completely free to use

Configuration

Basic Setup

Enable dynamic OG image generation in your config/_default/params.toml:

[ogImage]
  mode = "unsplash"  # Enable Unsplash-based generation
  fallback = "/images/og-default.jpg"  # Fallback image
  
  [ogImage.unsplash]
    keywordSource = "keywords"  # Where to extract keywords from
    keywordCount = 2            # Number of keywords to use
    width = 1200                # Image width
    height = 630                # Image height
    useRandomOnEmpty = true     # Use random image if no keywords

Configuration Options

Priority System

Hugo Paper uses a smart priority system:

1. Manual cover - cover: "/path/to/image.jpg" in frontmatter
2. Manual image - image: "/path/to/image.jpg" in frontmatter
3. Dynamic generation - Based on keywords/tags/categories/title
4. Fallback image - Your configured default image

This ensures every post has an OG image while giving you full control when needed.

Usage Examples

Example 1: Using Keywords (Recommended)

Add relevant keywords to your frontmatter:

---
title: "Getting Started with Hugo"
description: "A comprehensive guide to Hugo static site generator"
keywords:
  - hugo
  - static-site
  - tutorial
---

Generated URL: https://source.unsplash.com/1200x630/?hugo,static-site

This will display a high-quality image related to Hugo and static sites.

Example 2: Using Tags

Configure to use tags instead:

[ogImage.unsplash]
  keywordSource = "tags"

---
title: "Photography Tips"
tags:
  - photography
  - landscape
  - nature
---

Generated URL: https://source.unsplash.com/1200x630/?photography,landscape

Example 3: Manual Override

You can always specify a custom image:

---
title: "Special Post"
cover: "/images/custom-cover.jpg"
keywords:
  - hugo
  - tutorial
---

The cover image will be used instead of dynamic generation.

Example 4: No Keywords (Random Image)

If no keywords are available and useRandomOnEmpty = true:

---
title: "My Post"
# No keywords, tags, or categories
---

Generated URL: https://source.unsplash.com/1200x630/random

Best Practices

Choosing Effective Keywords

Since keywords determine your OG images, choose them wisely:

• Be specific: Use “react-hooks” instead of just “react”
• Use 2-3 keywords: More keywords = more specific images
• Think visually: Choose keywords with good visual representation
• Avoid abstract terms: “photography” works better than “efficiency”

Good keywords:

keywords: [photography, landscape, mountains]

Better keywords:

keywords: [mountain-photography, alpine-sunset, hiking]

Testing Your Images

Always verify your OG images work correctly:

1. Build and check: Run hugo and inspect the generated HTML
2. Test URLs: Open the Unsplash URLs in your browser
3. Social media debuggers:
   • Facebook Debugger
   • Twitter Card Validator
   • LinkedIn Post Inspector

Optimizing for Different Platforms

The 1200x630px dimensions work perfectly across all platforms:

• Facebook: Native support for this size
• Twitter: Displays as large image card
• LinkedIn: Professional appearance
• Discord/Slack: Clear, readable previews

Performance Benefits

Unlike build-time image generation solutions, Hugo Paper’s approach has zero performance impact:

• ✅ No build time increase - URLs generated instantly
• ✅ No storage costs - Images served from Unsplash CDN
• ✅ Fast loading - Unsplash’s global CDN ensures quick delivery
• ✅ Scalable - Works for any number of posts without slowdown

Comparison:

Troubleshooting

Common Issues

No OG image generated:

• Check that mode = "unsplash" in your config
• Verify the og-image.html partial exists
• Ensure your post has keywords, tags, or categories

Wrong keywords used:

• Check your keywordSource setting
• Verify the frontmatter field exists and has values
• Try different keyword sources (keywords → tags → title)

Images not loading:

• Test the Unsplash URL directly in browser
• Check for network connectivity issues
• Verify Unsplash service status

Fallback not working:

• Ensure fallback image exists in your static/ directory
• Check the file path is correct
• Verify image file permissions

Debug Mode

Check the generated HTML to debug issues:

# Find OG image tags in generated HTML
grep -A 2 -B 2 "og:image" public/post/your-post/index.html

# Expected output:
# <meta property="og:image" content="https://source.unsplash.com/1200x630/?your,keywords" />

API Limits

Unsplash Source API has generous limits:

• 50 requests per hour for the same IP
• No API key required
• Automatic CDN caching

For static sites, this is more than sufficient since URLs are generated at build time, not at runtime.

Advanced Customization

Multiple Keyword Sources

Configure Hugo Paper to try multiple keyword sources in order:

{{- $keywords := .Params.keywords -}}
{{- if not $keywords -}}
  {{- $keywords = .Params.tags -}}
{{- end -}}
{{- if not $keywords -}}
  {{- $keywords = .Params.categories -}}
{{- end -}}

Custom Unsplash Collections

Use specific Unsplash collections for consistent branding:

[ogImage.unsplash]
  collection = "1163637"  # Nature collection

Conditional Image Generation

Generate different images based on post type:

{{- if eq .Type "tutorial" -}}
  {{- $ogImage := "https://source.unsplash.com/1200x630/?coding,tutorial" -}}
{{- else if eq .Type "review" -}}
  {{- $ogImage := "https://source.unsplash.com/1200x630/?product,review" -}}
{{- end -}}

Conclusion

Hugo Paper’s dynamic OG image generation represents a simple yet powerful approach to automated social media optimization. By leveraging the Unsplash API and Hugo’s templating system, you can:

• Improve engagement rates by 30-50% with relevant, high-quality images
• Save time by eliminating manual image creation
• Maintain consistency across all your blog posts
• Enhance professionalism with beautiful photography

The system works seamlessly with zero configuration required, while offering extensive customization options for advanced users.

Key Takeaways

1. Zero effort: Just add keywords to your frontmatter
2. High quality: Professional photography from Unsplash
3. Flexible: Multiple keyword sources and fallback options
4. Fast: Images served from Unsplash CDN
5. Reliable: Works with any Hugo site

Next Steps

1. Enable the feature in your params.toml
2. Add keywords to your existing posts
3. Test with social media debuggers
4. Customize the configuration to match your needs

For more detailed information, check out:

• Hugo Paper Documentation
• Dynamic OG Image Design Documentation
• Test Dynamic OG Images

Start using dynamic OG images today and watch your social media engagement soar! 🚀