DFD Hugo image handling module

A Hugo module for handling images and image-related functionality for themes (including enabling responsive images).

Status

build-and-verify

GitHub repository

https://github.com/danielfdickinson/image-handling-mod-hugo-dfd

Features

  • From Hugo content files
  • Microformat (e.g. Open Graph/Twitter) support Note 3
  • Thumbnails Note 4
    • Configurable between thumbnail and full width or height image
    • Sitewide defaults that are overridable per-page
  • Fallback for non-resource images
  • Image conversion Note 5
  • Allows wrapping a link around the image(s) which points to the base image.
    • optionally can point to original format image
  • Allows wrapping a link around the image(s) which points to any URL.
  • Configurable responsive behaviour Note 6
  • Allow disabling responsive images Note 7

Basic usage of the module

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:

    config.toml

    [module]
      [[module.imports]]
        path = "github.com/danielfdickinson/image-handling-mod-hugo-dfd"
    

    OR config.yaml

    module:
      imports:
        - path: github.com/danielfdickinson/image-handling-mod-hugo-dfd
    
  2. Execute

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

Add the image

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

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

Add CSS to style the images

For the demo we use a small custom CSS file

Use markdown (render-image render hook makes it responsive)

Example #1

![Screenshot of a web page with an aqua theme]\(screenshot.png)

Use figure shortcode

Example #2

{{\< figure class="responsive-figure" title="Figure 1: Differences between markdown figures and figure shortcode" src="screenshot.png" alt="Screenshot of a web page with an aqua theme" caption="For a figure caption can be different than alt text">}}

Example #3

{{\< figure class="responsive-figure fullwidth" title="Figure 1: Differences between markdown figures and figure shortcode (full width)" src="screenshot.png" alt="Screenshot of a web page with an aqua theme" caption="For a figure caption can be different than alt text">}}

See ‘wrapped image’ partial, below, for the full set of parameters you can use with the shortcode.

Advanced usage

Image handling partials

Wrapped image

  • You have access to the helpers/wrapped-image partial in your layouts and shortcodes.
  • Outputs the HTML to display an image (an <img> tag) which is responsive by default Note 11.
  • Not all combinations of parameters make sense.
{{ partial "helpers/wrapped-image" (
    dict "width" 1920px
    "height" 1080px
    "thumbnailWidth" "90px"
    "thumbnailHeight" ""
    "alt" "Screenreader text"
    "altRendered" "alt text is HTML, not Markdown or plain (default false)"
    "title" "Title (screenreaders and often tooltips)"
    "image" "Image source (usually relative to page bundle or assets) or srcset (from another partial, below)"
    "page" .Page (Hugo page context; it is unlikely  that you will want this to be other than .Page)
    "class" "Classes (space separated string) to add to the wrapper element, or the img element if there is no image_wrapper"
    "link" "A link in which to wrap the image"
    "linkclass" "Classes (space separated string) to add to a wrapping link (only if 'link' specified)"
    "target" "For link: E.g. ('_blank')"
    "rel" "For link: E.g. ('nofollow')"
    "imageWrapper" "element in which to wrap <img> element"
    "caption" "A <figcaption> if image wrapper is <figure>, <span> if there is no title, or <div> if there is a title (because title will be wrapped in an <h2>)"
    "captionRendered" "caption is HTML, not Markdown or plain (default false)"
    "attr" "More caption text (but can be wrapped by a hyperlink via attrLink), only for a '<figure>'"
    "attrLink" "A hyperlink wrapped around attr, only if 'attr' above"
    "noImageWrapper" (If true you get a bare <img> element; default for render-image render hook)
    "imageSizes" "A slice of widths to use for the srcset"
    "thumbnailSizes" "A slice of width to use for thumbnail srcset"
    "singleSize" "If true, ignore srcset and *sizes; non-responsive img"
    "convertTo" "image format to which to convert (for this call only)"
    "thumbnails" "If true generate thumbnails; if fullsize is also true use a 'picture' element to pick the set of images (thumbnails or full size, based on screen size)
    "fullSize" "If true generate full size images; see thumbnails"
    "sizesAttr" "Overrides img (or source) 'sizes=' attribute"
    "thumbnailSizesAttr" "As with sizesAttr but for thumbnails"
    "minThumbnailViewport" "Minimum size of the viewport that is require to display thumbnails instead of full images"
    "loading" "If set, is the 'loading=' attribute for the 'img'"
    "noVisibleCaption" "If true then when there is a title and/or caption with an imageWrapper do not display the title and/or caption (attributes only)"
    )
-}}
  • You have access to the helpers/featured-images partial in your layouts and shortcodes.
  • Returns the set of featured images and related parameters for this page
    1. For image(s) specified by page-level parameters (frontmatter) search for images in page bundles or site assets:
      1. imageFeatured
      2. imageCover
      3. imageThumbnail
      4. featured_image
    2. If none found via step #1, look in the current page bundle for:
      1. *feature*
      2. *cover*,*thumbnail*
    3. If not found via step #2, find images by page-level params, searching for images in the static directory.

Featured images each have a url and may have

  • alt text
  • title
  • secure_url
  • the image resource (for images from a page bundle or from site assets)
  • width (for processable images only)
  • height (for processable images only).
{{ partial "helpers/featured-images" . -}}
{{ partial "helpers/featured-image" . -}}
  • As featured image but only returns the link (URL) of the featured image.
{{ partial "helpers/featured-image-link" . -}}

Metadata gathering

See DFD Hugo metadata module for more information.

Metadata types that can be gathered are:

  • media-images A slice of maps (dictionaries) with image information for use in microformats and other metadata; images matched are the same as featured images above.
  • media-image A map (dictionary) with image information for the first image from media-images which corresponds to featured image above.

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

.Site or .Page params

For all processable images

Currently:

  • png
  • jpeg/jpg
  • tif/tiff
  • bmp
  • gif
  • webp (only for Hugo extended)
ParamDefaultDescription
imageResponsivetrueMake images responsive (have srcset and sizes)
imageConvertTo(nil)Convert all images to specified format (must be an a format supported by Hugo; “webp” requires Hugo Extended)
imageImageSizes[“480”,“720”,“1080”,“1280”,“1600”,“2048”]Sizes (widths) of responsive image to generate
singleSizefalse (when true overrides default imageImagesSizes to “<image-width>x<image-height>”])Only generate one size of image

TODO: Add imageConvertMethod as an option for any image: [ Fit | GrowFit | Fill | Resize ].

For all image shortcodes

ParamDefaultDescription
imageLoading(nil)Default value of the ’loading=’ attribute for all images on the page (or site, for site-level)

For wrapped images

ParamDefaultDescription
imageLinkFull(nil)Link in which to wrap image if not provided by shortcode or partial (always applies to markdown images)
imageAddWrapper(nil)Element in which to wrap image if not provided by shortcode or partial (always applies to markdown images)
imageAddClass(nil)Classes (space separated string) to add to wrapper element or img element if no image wrapper
imageAltAsCaptionfalseUse alt text as caption when using image wrapper (unless caption specified)
imageSizesAttr80vwFor responsive images the default “sizes=” attribute
imageFullSizetruegenerate full sized image
imageThumbnailsfalseWhether or not to generate thumbnail images
imageThumbnailSizes[“180”,“360”,“512”]Default image sizes (widths) to generate when generating thumbnails
imageThumbnailWidth512Width of ‘base’ thumbnail
imageThumbnailHeight(based on thumbnail width and aspect ratio)Height of ‘base’ thumbnail
imageThumbnailSizesAttr20vwFor thumbnail images the default “sizes=” attribute
imageMinThumbnailViewport768pxMinimum viewport for which to generate thumbnails

‘alt’ text from one of:

  • imageFeaturedAlt
  • imageCoverAlt
  • imageThumbnailAlt
  • featuredImageAlt
  • featuredAlt

’title’ from one of:

  • imageFeaturedTitle
  • imageCoverTitle
  • imageThumbnailTitle
  • featuredImageTitle
  • featuredTitle

For microformats

ParamDefaultDescription
microformatWidth1200Default width for microformat image (e.g. OpenGraph)
microformatHeight630Default height for microformat image (.e.g OpenGraph)
microformatConvertMethodGrowFitDefault method for resize/crop of microformat image [ Fit | GrowFit | Fill | Resize ]

Examples

Test image #1

Source #1

https://github.com/danielfdickinson/image-handling-mod-hugo-dfd/blob/main/exampleSite/content/post/testimage1/index.md

CSS #1

Which uses the above CSS and imageConvertTo = "webp" in config.toml

Result #1

Image shows three different styling variations on a screenshot of a website

Test image #2

Source #2

https://github.com/danielfdickinson/image-handling-mod-hugo-dfd/blob/main/exampleSite/content/post/testimage2/index.md

CSS #2

Which uses the above CSS and imageConvertTo = "webp" in config.toml

Result #2

Image shows four different styling variations on a screenshot of a website

Test image #3

Source #3

https://github.com/danielfdickinson/image-handling-mod-hugo-dfd/blob/main/exampleSite/content/post/testimage3/index.md

CSS #3

Which uses the above CSS and imageConvertTo = "webp" in config.toml

Result #3

Image shows four different styling variations on a screenshot of a website

Test thumbnails #1

Source #4

https://github.com/danielfdickinson/image-handling-mod-hugo-dfd/blob/main/exampleSite/content/post/test-thumbnails-1/index.md

CSS #4

Which uses the above CSS and imageConvertTo = "webp" in config.toml

Result #4

Image shows three image thumbnails in a row (with large amounts space between them)

Test thumbnails #2

Source #5

https://github.com/danielfdickinson/image-handling-mod-hugo-dfd/blob/main/exampleSite/content/post/test-thumbnails-2/index.md

CSS #5

Which uses the above CSS and imageConvertTo = "webp" in config.toml

Result #5

Image shows three image thumbnails in a row (with some space between them)

Endnotes

Note 1

Markdown content only

Note 2

Override of default ‘figure’ shortcode from Hugo core

Note 3

Requires DFD Hugo metadata module or equivalent

Note 4

E.g. for blog/taxonomy/HTML sitemap/etc listings

Note 5

E.g. to webp

Note 6

Sizes attribute and sizes of images and/or alternate images based on media queries

Note 7

E.g. single image/size; useful if all you want is image conversion or just the wrapper functionality

Note 8

NB You can only use subdirectories with leaf bundles. For branch bundles the image must be in the same directory as the _index.md

Note 9

This allows using subdirectories under assets (e.g. assets/path/to/screenshot.png which would render to /path/to/screenshot.png).

Note 10

E.g. if you place the image under static

Note 11

But doesn’t have to be, optionally wrapped in <figure>, <span>, or <div>, all if which maybe optionally wrapped in a link (<a href="…"> element)

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/image-handling-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.