Managing images in Hugo doesn’t have to be a mess of <img> tags and custom styling. With the hugo-img-lightbox module, you can add responsive images, lazy loading, automatic resizing, figcaptions, and Lightbox2 support — all through a simple shortcode.

In this post, I’ll show you how the module works, how to install it, and how to use it in your content.

🔧 What the Module Does

This module provides:

• A shortcode: {{< img src=“image.png” alt="…" caption="…" >}} for inserting images
• Automatic resizing into responsive sizes (500w, 800w, 1200w)
• Lazy loading <img> elements
• Semantic <figure> and optional <figcaption>
• Lightbox2 integration for full-size preview on click
• Conditional asset loading (JS/CSS is only injected if the shortcode is used)

📦 Installation (via Hugo Modules)

Make sure you have Go installed (brew install go or visit go.dev )

1. In the root of your Hugo site, initialize Hugo Modules (if not already):

   hugo mod init mysite.local
   

2. In your config.toml, add the module:

   [module]
   [[module.imports]]
   path = "github.com/kholmqivst/hugo-img-lightbox"
   

3. Run Hugo to fetch it:

   hugo mod get github.com/kholmqivst/hugo-img-lightbox
   

4. In your layout (usually layouts/_default/baseof.html), load the Lightbox assets if needed:

   {{ if .Scratch.Get "usesLightbox" }}
     {{ partial "lightbox.html" . }}
   {{ end }}
   

🖼️ Usage in Markdown

Once set up, you can use the shortcode like this:

{{< img src=“Sophos-DHCP-over-IPSec.png” alt=“Sophos UI” caption=“Sophos DHCP configuration over IPSec” >}}

This will:

• Find the image in the same folder as your index.md (i.e., a page bundle)
• Resize it to multiple widths
• Wrap it in a <figure> with a caption
• Enable Lightbox2 when clicked

🧪 How It Works Internally

• The img.html shortcode uses .Page.Resources.Match to find the image in the current page bundle.
• It resizes the image to multiple sizes and builds a srcset.
• It sets a flag: .Page.Scratch.Set "usesLightbox" true, so your layout knows to load the Lightbox assets.
• If a caption is given, it is rendered as a <figcaption>.
• The Lightbox partial is only loaded if at least one image on the page uses the shortcode.

✅ Benefits

• Keeps your Markdown clean
• Respects page bundles and Hugo image processing
• Avoids loading unused JS or CSS
• Easily extendable if you want to support static images or external links

👋 Final Thoughts

This module helps keep your images clean, performant, and modern — and integrates beautifully with Hugo’s existing features like page bundles and image processing.

If you want to add features like fallback to static images, thumbnail-only lightboxes, or even gallery support, this module is a great foundation.

You can find the source and instructions on GitHub:

👉 github.com/kholmqvist/hugo-img-lightbox

Happy Hugo-ing!