Dynamic OG Image Generation in Hugo Paper: Boost Social Media Engagement

Open Graph (OG) images are crucial for social media sharing. Hugo Paper’s dynamic OG image generation automatically creates beautiful, relevant preview images using the Unsplash API—no manual work required.

What Are OG Images?

Open Graph images are the preview images that appear when you share a link on social media platforms like:

Facebook - Shows in news feed and timeline
Twitter - Displays as Twitter Card
LinkedIn - Appears in professional posts
Discord/Slack - Shows in message previews
WhatsApp - Displays in link previews

Why OG Images Matter

Impact on engagement:

📈 30-50% higher click-through rates
👁️ 3x more visual attention
🔄 2x more shares
💬 Better conversation starters

Without OG image:

[Generic site icon]
Your Amazing Blog Post
yourblog.com

With OG image:

[Beautiful relevant image 1200x630px]
Your Amazing Blog Post
A compelling description that makes people want to click
yourblog.com

The Traditional Problem

Manual Approach

Most Hugo themes require you to:

Create images manually - Design in Photoshop/Canva
Save and optimize - Export at correct size
Upload to static folder - Manage file organization
Reference in frontmatter - Add path to each post

Time cost: 10-15 minutes per post

Problems:

❌ Time-consuming
❌ Requires design skills
❌ Inconsistent quality
❌ Storage overhead
❌ Easy to forget

Static Fallback Approach

Using one default image for all posts:

# config.toml
[params]
  ogImage = "/images/default-og.jpg"

Problems:

❌ Same image for every post
❌ No visual differentiation
❌ Lower engagement
❌ Missed opportunities

Hugo Paper’s Dynamic Solution

Hugo Paper generates OG images dynamically using the Unsplash Source API:

How It Works

1. Extract keywords from post
   ↓
2. Generate Unsplash URL
   ↓
3. Insert into HTML meta tags
   ↓
4. Social media fetches image from Unsplash CDN

Key Advantages

✅ Zero build time - URLs generated instantly
✅ No storage needed - Images served from Unsplash CDN
✅ High-quality images - Professional photography
✅ Relevant content - Matches your keywords
✅ No API key required - Completely free
✅ Automatic updates - Fresh images from Unsplash

Quick Start Guide

Step 1: Enable Dynamic OG Images

Edit config/_default/params.toml:

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

Step 2: Add Keywords to Your Posts

---
title: "Getting Started with Hugo"
keywords:
  - hugo
  - static-site
  - tutorial
---

Generated URL:

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

Step 3: Build and Test

# Build your site
hugo

# Check the generated HTML
grep "og:image" public/post/your-post/index.html

Expected output:

<meta property="og:image" content="https://source.unsplash.com/1200x630/?hugo,static-site" />
<meta property="twitter:image" content="https://source.unsplash.com/1200x630/?hugo,static-site" />

Test your OG images with these tools:

Facebook: Sharing Debugger
Twitter: Card Validator
LinkedIn: Post Inspector

Configuration Options

Mode Settings

[ogImage]
  mode = "unsplash"  # Options: "manual", "unsplash"

Modes:

manual - Only use manually specified images
unsplash - Use Unsplash API for dynamic generation

Keyword Sources

[ogImage.unsplash]
  keywordSource = "keywords"  # Options: "keywords", "tags", "categories", "title"

Examples:

Using Keywords (Recommended)

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

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

Using Tags

keywordSource = "tags"

---
tags:
  - react
  - javascript
  - tutorial
---

→ https://source.unsplash.com/1200x630/?react,javascript

Using Categories

keywordSource = "categories"

---
categories:
  - Technology
  - Web Development
---

→ https://source.unsplash.com/1200x630/?technology,web-development

Using Title

keywordSource = "title"

---
title: "Mountain Hiking Guide"
---

→ https://source.unsplash.com/1200x630/?mountain,hiking,guide

Image Dimensions

[ogImage.unsplash]
  width = 1200   # Image width in pixels
  height = 630   # Image height in pixels

Recommended sizes:

1200x630 - Optimal for all platforms (default)
1200x675 - Alternative 16:9 ratio
1080x1080 - Square format (Instagram)

Platform requirements:

Platform	Minimum	Recommended	Maximum
Facebook	200x200	1200x630	8192x8192
Twitter	120x120	1200x675	4096x4096
LinkedIn	180x110	1200x627	-

Keyword Count

[ogImage.unsplash]
  keywordCount = 2  # Number of keywords to use (1-5)

Best practices:

1 keyword - Very specific images
2 keywords - Balanced (recommended)
3+ keywords - More specific, fewer results

Random Fallback

[ogImage.unsplash]
  useRandomOnEmpty = true  # Use random image when no keywords

When enabled, posts without keywords get a random high-quality image instead of the fallback.

Priority System

Hugo Paper uses a smart priority system:

1. Manual cover image (highest priority)
   ↓
2. Manual image field
   ↓
3. Dynamic Unsplash generation
   ↓
4. Fallback image (lowest priority)

Example: Manual Override

---
title: "Special Post"
cover: "/images/custom-cover.jpg"  # This takes priority
keywords:
  - hugo
  - tutorial
---

The cover image will be used instead of dynamic generation.

Example: Dynamic Generation

---
title: "Regular Post"
keywords:
  - hugo
  - blogging
# No cover or image specified
---

Unsplash URL will be generated from keywords.

Best Practices

1. Choosing Effective Keywords

Good keywords:

✅ Visually descriptive: “mountain”, “ocean”, “city”
✅ Specific: “react-hooks” vs “programming”
✅ 2-3 keywords for best results
✅ Think about what images you want

Poor keywords:

❌ Abstract concepts: “efficiency”, “productivity”
❌ Too generic: “technology”, “business”
❌ Too many keywords: 5+ keywords
❌ Non-visual terms: “tutorial”, “guide”

Examples:

# Good - Will find beautiful mountain photos
keywords:
  - mountain-photography
  - alpine-sunset
  - hiking

# Poor - Will find generic tech images
keywords:
  - technology
  - tutorial
  - guide

2. Keyword Combinations

Effective combinations:

# Nature blog
keywords: [forest, sunrise, landscape]

# Tech blog
keywords: [coding, workspace, developer]

# Food blog
keywords: [cooking, ingredients, kitchen]

# Travel blog
keywords: [travel, destination, adventure]

# Photography blog
keywords: [camera, photography, portrait]

3. Testing Your Images

Always preview your OG images:

# 1. Build your site
hugo

# 2. Open the Unsplash URL in browser
# Copy from generated HTML and test

# 3. Use social media debuggers
# Facebook: https://developers.facebook.com/tools/debug/
# Twitter: https://cards-dev.twitter.com/validator

4. Fallback Strategy

Always configure a fallback image:

[ogImage]
  fallback = "/images/og-default.jpg"

Fallback image requirements:

1200x630 pixels
High quality (< 1MB)
Represents your brand
Works for any post

Advanced Usage

Custom Unsplash Collections

Use specific Unsplash collections for consistent branding:

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

How to find collection IDs:

Browse Unsplash Collections
Open a collection
Copy ID from URL: unsplash.com/collections/[ID]

Conditional Image Generation

Generate different images based on post type:

<!-- layouts/partials/head/og-image.html -->
{{- 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 -}}

Multiple Keyword Sources

Try multiple sources in order:

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

Performance Considerations

Build Time Impact

Traditional approach (Satori/Puppeteer):

100 posts = +100 seconds build time
Storage: ~50 MB
Requires Node.js dependencies

Hugo Paper (Unsplash):

100 posts = +0 seconds build time
Storage: 0 MB
No dependencies

CDN Benefits

Unsplash provides:

✅ Global CDN distribution
✅ Automatic image optimization
✅ Fast loading times
✅ High availability (99.9% uptime)

API Limits

Unsplash Source API limits:

50 requests per hour per IP
No API key required
Automatic CDN caching

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

Troubleshooting

No OG Image Generated

Check:

Is mode = "unsplash" in config?
Does the post have keywords/tags/categories?
Is og-image.html partial included in head?

Solution:

# Verify configuration
grep -A 5 "ogImage" config/_default/params.toml

# Check generated HTML
grep "og:image" public/post/your-post/index.html

Wrong Keywords Used

Problem: Using title instead of keywords

Solution:

[ogImage.unsplash]
  keywordSource = "keywords"  # Change from "title"

Images Not Loading

Check:

Test Unsplash URL directly in browser
Check network connectivity
Verify Unsplash service status

Solution:

# Test URL directly
curl -I "https://source.unsplash.com/1200x630/?test"

# Should return 200 OK

Fallback Not Working

Check:

Does fallback image exist in static/?
Is path correct in config?
Is image accessible?

Solution:

# Verify file exists
ls static/images/og-default.jpg

# Check in generated site
ls public/images/og-default.jpg

Real-World Examples

Tech Blog

---
title: "React Hooks Tutorial"
keywords:
  - react
  - javascript
  - coding
---

→ Beautiful coding workspace images

Travel Blog

---
title: "Best Beaches in Bali"
keywords:
  - bali
  - beach
  - tropical
---

→ Stunning beach and tropical images

Food Blog

---
title: "Italian Pasta Recipes"
keywords:
  - pasta
  - italian-food
  - cooking
---

→ Delicious food photography

Photography Blog

---
title: "Landscape Photography Tips"
keywords:
  - landscape
  - photography
  - nature
---

→ Professional landscape photos

Comparison: Manual vs Dynamic

Aspect	Manual Images	Dynamic (Unsplash)
Time per post	10-15 minutes	0 seconds
Storage	~500 KB/image	0 KB
Build time	+0s	+0s
Quality	Varies	Professional
Consistency	Manual effort	Automatic
Cost	Design tools	Free
Maintenance	High	None
Flexibility	Full control	Keyword-based

SEO Impact

Before Dynamic OG Images

Generic preview images
Low click-through rates
Poor social engagement
Inconsistent branding

After Dynamic OG Images

Relevant, eye-catching previews
30-50% higher CTR
Better social sharing
Professional appearance

Measuring Success

Track these metrics:

- Social media referral traffic
- Click-through rates from social
- Share counts
- Engagement rates
- Time on site from social traffic

Next Steps

Enable dynamic OG images in your config
Add keywords to your existing posts
Test with social media debuggers
Monitor engagement metrics
Refine keyword strategy based on results

Conclusion

Dynamic OG image generation is a game-changer for social media optimization. By automating image selection with Unsplash, you save time while ensuring every post has a beautiful, relevant preview image.

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

Questions? Join our GitHub Discussions or open an issue.

Dynamic OG Image Generation in Hugo Paper: Boost Social Media Engagement

Table of Contents

What Are OG Images?

Why OG Images Matter

The Traditional Problem

Manual Approach

Static Fallback Approach

Hugo Paper’s Dynamic Solution

How It Works

Key Advantages

Quick Start Guide

Step 1: Enable Dynamic OG Images

Step 2: Add Keywords to Your Posts

Step 3: Build and Test

Step 4: Verify on Social Media

Configuration Options

Mode Settings

Keyword Sources

Using Keywords (Recommended)

Using Tags

Using Categories

Using Title

Image Dimensions

Keyword Count

Random Fallback

Priority System

Example: Manual Override

Example: Dynamic Generation

Best Practices

1. Choosing Effective Keywords

2. Keyword Combinations

3. Testing Your Images

4. Fallback Strategy

Advanced Usage

Custom Unsplash Collections

Conditional Image Generation

Multiple Keyword Sources

Performance Considerations

Build Time Impact

CDN Benefits

API Limits

Troubleshooting

No OG Image Generated

Wrong Keywords Used

Images Not Loading

Fallback Not Working

Real-World Examples

Tech Blog

Travel Blog

Food Blog

Photography Blog

Comparison: Manual vs Dynamic

SEO Impact

Before Dynamic OG Images

After Dynamic OG Images

Measuring Success

Next Steps

Related Resources

Conclusion