Image Effects

The theme offers effects for your linked images.

You can define additional custom image effects and set defaults in your configuration.

The default image effects shipped with the theme are

Name	Description
border	Draws a light thin border around the image
dataurl	if the linked image points to a resource, it is converted to a base64 encoded dataurl
inlinecontent	if the linked image points to a SVG resource, the content will be used instead of an `<img>` element, this is useful for applying additional CSS styles to the elements inside of the SVG which is otherwise impossible
lazy	Lets the image be lazy loaded
lightbox	The image will be clickable to show it enlarged
shadow	Draws a shadow around the image to make it appear hovered/glowing

One way to use them is to add them as URL query parameter to each individually linked image.

This can become cumbersome to be done consistently for the whole site. Instead, you can configure the defaults in your hugo.toml as well as overriding these defaults in a page’s front matter.

Effect Priority

Image effects are applied in the following priority order (lowest to highest):

Built-in defaults
Site-wide configuration in hugo.toml
Page front matter configuration
URL query parameters
Template caller attributes parameter (highest priority)

Explicitly set URL query parameter will override the defaults set for a page or your site. When calling the image partial directly from templates, effects passed via the attributes parameter have the highest priority and will override all other settings.

If an effect accepts boolean values, only setting the parameter name without a value in the URL will set it to true.

Without any settings in your hugo.toml imageEffects defaults to

[imageEffects]
  border = false
  dataurl = false
  inlinecontent = false
  lazy = true
  lightbox = true
  shadow = false

imageEffects:
  border: false
  dataurl: false
  inlinecontent: false
  lazy: true
  lightbox: true
  shadow: false

{
   "imageEffects": {
      "border": false,
      "dataurl": false,
      "inlinecontent": false,
      "lazy": true,
      "lightbox": true,
      "shadow": false
   }
}

Front Matter This can be overridden in a pages front matter for example by

+++
[params]
  [params.imageEffects]
    lazy = false
+++

---
params:
  imageEffects:
    lazy: false
---

{
   "params": {
      "imageEffects": {
         "lazy": false
      }
   }
}

Or by explicitly override settings by URL query parameter

![Minion](https://octodex.github.com/images/minion.png?lazy=true&lightbox=false)

The settings applied to the above image would be

[imageEffects]
  border = true
  dataurl = false
  inlinecontent = false
  lazy = true
  lightbox = false
  shadow = false

imageEffects:
  border: true
  dataurl: false
  inlinecontent: false
  lazy: true
  lightbox: false
  shadow: false

{
   "imageEffects": {
      "border": true,
      "dataurl": false,
      "inlinecontent": false,
      "lazy": true,
      "lightbox": false,
      "shadow": false
   }
}

Template Usage

When calling the image partial directly from templates, you can pass effect preferences via the attributes parameter. Effect names can be prefixed with no to disable them.

{{- $attributes := dict "class" "nolightbox border" }}
{{ partial "shortcodes/image.html" (dict "page" . "url" "image.png" "attributes" $attributes) }}

This approach has the highest priority and will override all other effect settings, including URL query parameters. Effect classes are processed but not added to the final HTML class attribute. Non-effect classes pass through unchanged.

For example, class = "nolightbox custom-img-class" will disable the lightbox effect and add custom-img-class to the HTML output, but neither lightbox nor nolightbox will appear in the final class attribute.