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
• Shortcodes
  • Figure
    • Parameters
    • Notes
  • Gallery
    • Parameters
• Partials
  • Figure
  • Gallery
• Global Configuration
• Optimisation
• Further Readings
• Usage Examples
  • Markdown Render Hook
  • Gallery Shortcode
  • Image Shortcode
• Sample Photo Sources

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):

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

With named parameters:

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

Parameters

Notes

Tagvariants:

1{{< figure >}}Something{{< /figure >}}
2{{< 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.

Gallery

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

Partials

Figure

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

 1{
 2 "name": "",
 3 "src": "",
 4 "height": 100,
 5 "width": 100,
 6 "title": "",
 7 "alt": "",
 8 "class": "",
 9 "link": "link to put the image in, param `link` required on the shortcode",
10 "caption": "markdownified content of .Inner, used for the caption of the image",
11 "srcset": "",
12}

Gallery

To be written.

Global Configuration

To be written.

 1[dnb]
 2  [dnb.pictures]
 3    aspect_ratio = '2:1'
 4    default_image = 'images/og_sitewide.png'
 5    [dnb.pictures.responsive]
 6      [dnb.pictures.responsive.fullwidth]
 7        break_points = ['520', '540', '720', '960']
 8        image_sizes = ['494', '517', '674', '914']
 9      [dnb.pictures.responsive.halfwidth]
10        break_points = ['520', '540']
11        image_sizes = ['494', '517']

 1dnb:
 2  pictures:
 3    aspect_ratio: "2:1"
 4    default_image: images/og_sitewide.png
 5    responsive:
 6      fullwidth:
 7        break_points:
 8        - "520"
 9        - "540"
10        - "720"
11        - "960"
12        image_sizes:
13        - "494"
14        - "517"
15        - "674"
16        - "914"
17      halfwidth:
18        break_points:
19        - "520"
20        - "540"
21        image_sizes:
22        - "494"
23        - "517"

 1{
 2   "dnb": {
 3      "pictures": {
 4         "aspect_ratio": "2:1",
 5         "default_image": "images/og_sitewide.png",
 6         "responsive": {
 7            "fullwidth": {
 8               "break_points": [
 9                  "520",
10                  "540",
11                  "720",
12                  "960"
13               ],
14               "image_sizes": [
15                  "494",
16                  "517",
17                  "674",
18                  "914"
19               ]
20            },
21            "halfwidth": {
22               "break_points": [
23                  "520",
24                  "540"
25               ],
26               "image_sizes": [
27                  "494",
28                  "517"
29               ]
30            }
31         }
32      }
33   }
34}

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

• A list of up to date best practices for web images by nucliweb (those practices are all implemented in this module)

Usage Examples

Markdown Render Hook

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

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

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

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

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

Gallery Shortcode

1{{< gallery gallery="gallery1" >}}

Previous Next

Image Shortcode

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

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

Sample Photo Sources

• Good Dog 1, Good Dog 2, Good Dog 3, Static Cat, Assets Cat — License: Unsplash+ License