DFD Hugo metadata image module

A Hugo module for handling metadata images (gathering from or adding to metadata).



GitHub repository


Site with examples



  • Page-level microformats (e.g. Open Graph/Twitter) support (not to be confused with mf2 / microformats.org in-body microformats)

Basic usage of the module


  1. You must have in directory containing a hugo site (e.g. such as created by hugo new site <directory>).
  2. You must have a recent version of Go installed (see section Prerequisite in ‘Use Hugo Modules’ in the Hugo documentation).
  3. The site must be initialized as a Hugo module (see ‘Initialize a New Module’ in the Hugo documentation, or the output of hugo mod init).
  4. Before the site will build correctly, you will also need a theme installed.

Importing the module

  1. The first step to making use of this module is to add it to your site or theme. In your configuration file:


    path = "github.com/danielfdickinson/metadata-image-mod-hugo-dfd"



          - path: github.com/danielfdickinson/metadata-image-mod-hugo-dfd
  2. Execute

    hugo mod get github.com/danielfdickinson/metadata-image-mod-hugo-dfd
    hugo mod tidy

Add the image

  1. Place your image in a page bundle (e.g. cover-screenshot.png)
  2. OR under assets in your project root

If you don’t use a page bundle or assets, the image can still be used, but cannot be made responsive

Image handling partials

See DFD Hugo image handling module for more information.

Metadata gathering

See DFD Hugo metadata module for more information.

Metadata types that can be gathered are:

Gathering image metadata may also create an image for specifically for use with microformats (see for microformats , below).

.Site or .Page params

‘alt’ text from one of:

  • imageFeaturedAlt
  • imageCoverAlt
  • imageThumbnailAlt
  • featuredImageAlt
  • featuredAlt

’title’ from one of:

  • imageFeaturedTitle
  • imageCoverTitle
  • imageThumbnailTitle
  • featuredImageTitle
  • featuredTitle

For microformats

microformatWidth1200Default width for microformat image (e.g. Open Graph)
microformatHeight630Default height for microformat image (.e.g Open Graph)
microformatSizingMethodFillDefault method for resize/crop of microformat image [ Fit | GrowFit | Fill | Resize ]
microformatImageOverlay(none)Dict with src, x, and y for image, and x, y position to overlay ‘src’ on the main image
microformatTextOverlay(none)Slice of dicts with text, opts (which is a dict, see Hugo docs) which specifies text to overlay over an image and the options (color, size, etc). Overrides use of title and/or description as overlay text (below).
microformatTitleAsOverlayTextfalseUse page .Title as overlay text
microformatDescriptionAsOverlayTextfalseUse page .Description as overlay text
microformatOverlayTitleColor#fffColour for title as overlay text
microformatOverlayTitleSize96Size in pixels for title as overlay text
microformatOverlayTitleSpacing2Line spacing for title as overlay text
microformatOverlayTitleStartX0Start X position for title as overlay text
microformatOverlayTitleStartY0StartY position for title as overlay text
microformatOverlayTextColor#fffColour for description as overlay text
microformatOverlayTextSize96Size in pixels for description as overlay text
microformatOverlayTextSpacing2Line spacing for description as overlay text
microformatOverlayTextStartX0Start X position for description as overlay text
microformatOverlayTextStartY0Start Y position for description as overlay text

Auto-generating ‘social cards’

description: "Example of an auto-generated social card. Obviously can be much prettier."
imageFeatured: "/light-blue-gradient-social-card.png"
microformatTitleAsOverlayText: true
microformatOverlayTitleStartX: 64
microformatOverlayTitleStartY: 64
microformatOverlayTitleColor: "#111"
microformatDescriptionAsOverlayText: true
microformatOverlayTextStartX: 24
microformatOverlayTextStartY: 290
microformatOverlayTextColor: "#222"
imageFeaturedCardOnly: true
headerTextOmit: false
summaryTextOnly: true
imageFeaturedGenAltPrefix: "Metadata image module"

Light blue gradient with the title ‘Social Card’ and the text ‘Example of an auto-generated social card. Obviously can be much prettier’

Contributions welcome

If your issue can’t be found when searching both open and closed issues, please add it!

Please check open issues on danielfdickinson/metadata-image-mod-hugo-dfd for enhancements and bugs that you would like resolved, write the fix, and submit a pull request!

As well, documentation improvements are always handy.

Thank you, and I hope you find this repository useful.

Support and general questions

Please use GitHub Discussions for support and general questions.