Samui? Samui!David's Neighbour's Notizen über sein Leben als Auswanderer auf der Insel Koh Samui in Thailand. Auf Deutsch, und so...

Pictures

  / / / /

This component for GoHugo adds partials and shortcodes to resolve and process images on your website. It offers responsive image formats and optimised loading based on current browser abilities.

The simplest way is to use this module as a drop-in. Just install it and forget you ever did. It will work out of the box with the default settings and replace the internal handling of image markdown (![alt text](image path)) and the {{< figure >}} shortcode. You can adapt it’s features to your needs by using the partials and global configuration options.

Notes

  • Image processing (aka. resizing, filters, cropping etc) is only available in Global and Page Resources. Global Resources are located in the assets folder of your repository, Page Resources are located within the content directory with your content files in so called Page Bundles. The images in your static directory are loaded as they are, not processed (other than evaluation of content type and sizing) and will not result in responsive image tags. All other features or options will work.
  • Lookup order of images:
    • page bundle
    • global resources (assets folder)
    • static folder
    • after that, a warning about the image not being found is issued on CLI and on the page itself it fails silently
  • Using the name attribute implies that page resources are used, and no further lookup will be done if the image is not found in the page bundle.

Markdown

This module implements a markdown render hook for GoHugo that resizes and prepares HTML for responsive images. It is the simplest way to use this module. Just install it and forget you ever did. It will work out of the box with the default settings and replace the internal handling of image markdown (![alt text](image path)).

Shortcodes

Available shortcodes currently are image, figure and gallery. Those shortcodes are served by partials that you can use in your own layout files with more extensive configurability. figure overrides the GoHugo internal figure shortcode. All shortcodes add responsive image processing and markup to your website.

Figure

Possible call scenarios:

With unnamed parameters (static images preferred):

{{< figure "path/to/image" >}}
{{< figure "path/to/image" "alt-title" >}}

With named parameters:

{{< figure src="path/to/image" title="" alt="" >}}
{{< figure src="path/to/image" title="" alt="" >}}caption{{< /figure >}}
{{< figure name="resource name" title="" alt="" >}}caption{{< /figure >}}

Parameters

Option Type Notes
name string Resource name to show (required, if no src parameter is used, resources are defined in frontmatter or it’s the filename of the image in a page bundle)
src string Image to show (required, if no name parameter is used). must be relative to the static folder
link string Links the image to an URL
linktarget string Target of the link (optional, default is to open the link in the same tab. Typically you would want _blank as value for a new window, but anything goes here)
class string Additional classes for the image (optional)
alt string alt attribute for the image (optional, suggested)
title string title attribute for the image (optional)
command string Command for image processing (optional, required with options)
options string Options for image processing (optional, required with command)
width number Width of the image (optional, could be evaluated from the resulting image)
height number Height of the image (optional, could be evaluated from the resulting image)

Notes

Tagvariants:

{{< figure >}}Something{{< /figure >}}
{{< figure title="Something" >}}

The two samples above have the same output. Using the title-attribute removes the requirement to add a closing tag. But you can add as much markdown/formatting to your caption by using an opening and closing tag for the shortcode. While the title tag is “markdownified”, this might be an easier way to add more complex content to your caption.

Commands:

TODO: Currently this allows for only one command/options combination. The future way will be to add an “array” of commands and options that are executed successively.

Image Shortcode:

The {{< image >}} shortcode is a synonym for the {{< figure >}} shortcode and has the same features/options. It is added for compatibility with older implementations and themes.

to be written.

Notes: right now it expects a galleryid parameter for a folder inside of pagebundle/gallery/galleryid and a type for bootstrap4 or bootstrap5. All images in that directory are parsed and shown. No sorting (todo), no gallery selection by frontmatter (todo).

Parameters

Option Type Notes

Partials

Figure

The figure partial executes the markdown creation of single images and can be called with an options dictionary of the following content:

{
 "name": "",
 "src": "",
 "height": 100,
 "width": 100,
 "title": "",
 "alt": "",
 "class": "",
 "link": "link to put the image in, param `link` required on the shortcode",
 "caption": "markdownified content of .Inner, used for the caption of the image",
 "srcset": "",
}

To be written.

Global Configuration

To be written.

[dnb]
  [dnb.pictures]
    aspect_ratio = '2:1'
    default_image = 'images/og_sitewide.png'
    [dnb.pictures.responsive]
      [dnb.pictures.responsive.fullwidth]
        break_points = ['520', '540', '720', '960']
        image_sizes = ['494', '517', '674', '914']
      [dnb.pictures.responsive.halfwidth]
        break_points = ['520', '540']
        image_sizes = ['494', '517']

dnb:
  pictures:
    aspect_ratio: "2:1"
    default_image: images/og_sitewide.png
    responsive:
      fullwidth:
        break_points:
        - "520"
        - "540"
        - "720"
        - "960"
        image_sizes:
        - "494"
        - "517"
        - "674"
        - "914"
      halfwidth:
        break_points:
        - "520"
        - "540"
        image_sizes:
        - "494"
        - "517"

{
   "dnb": {
      "pictures": {
         "aspect_ratio": "2:1",
         "default_image": "images/og_sitewide.png",
         "responsive": {
            "fullwidth": {
               "break_points": [
                  "520",
                  "540",
                  "720",
                  "960"
               ],
               "image_sizes": [
                  "494",
                  "517",
                  "674",
                  "914"
               ]
            },
            "halfwidth": {
               "break_points": [
                  "520",
                  "540"
               ],
               "image_sizes": [
                  "494",
                  "517"
               ]
            }
         }
      }
   }
}

Optimisation

To be written.

Notes about:

  • resources directory
  • caching (with hugo-netlification)
  • preloading (needs implementation)
  • maybe a walkthrough how this module implements current features?

Further Readings

Usage Examples

Markdown Render Hook 

![Good Dog 1](dog-1.jpg)

Pictures

![Good Dog 2](dog-2.jpg "with a title text")

Pictures

![Good Dog 3](dog-3.jpg?size=wide "with css-processed instructions")

Pictures

![Assets Cat](images/pictures/assets-cat.jpg "cat picture from the assets directory")

Pictures

![Static Cat](/dnb/pictures/static-cat.jpg "cat picture from the static directory")

Static Cat 

{{< gallery gallery="gallery1" >}}
gallery1/dog-1.jpg
gallery1/dog-2.jpg
gallery1/dog-3.jpg

Image Shortcode 

{{< image src="dog-1.jpg" >}}
{{< image src="dog-2.jpg" >}}

Sample Photo Sources