Hinode logo
  • About 
  • Docs 
  • Components 
  • Guides 
  • Releases 
  •  
  •    Toggle theme
    •   Light
    •   Dark
    •   Auto
  •  
    •   Light
    •   Dark
    •   Auto
Docs
    • Introduction
    • Commands
    • Hosting and deployment
    • Upgrading
    • Contribute
    • Troubleshooting
    • Content management
    • Content organization
    • Typography
    • Links and cross-references
    • Images and figures
    • Tables
    • Icons
    • Layout
    • Colors
    • Color modes
    • Fonts
    • Languages
    • Navigation
    • Documentation
    • Analytics
    • Modules
    • Abbr
    • Accordion
    • Alert
    • Animation
    • Badge
    • Breadcrumb
    • Button
    • Button group
    • Card
    • Card group
    • Carousel
    • Collapse
    • Command prompt
    • Docs
    • Example
    • File
    • Icon
    • Image
    • Kbd
    • Link
    • Map
    • Mark
    • Navbar
    • Navs and tabs
    • Release
    • Spinner
    • Spinner
    • Sub
    • Sup
    • Timeline
    • Toast
    • Tooltip
    • Overview
    • Styles
    • Scripts
    • Icons
    • Module development
    • Server headers
    • Server-side redirection
    • Credits
    • License
    • Introduction
    • Commands
    • Hosting and deployment
    • Upgrading
    • Contribute
    • Troubleshooting
    • Content management
    • Content organization
    • Typography
    • Links and cross-references
    • Images and figures
    • Tables
    • Icons
    • Layout
    • Colors
    • Color modes
    • Fonts
    • Languages
    • Navigation
    • Documentation
    • Analytics
    • Modules
    • Abbr
    • Accordion
    • Alert
    • Animation
    • Badge
    • Breadcrumb
    • Button
    • Button group
    • Card
    • Card group
    • Carousel
    • Collapse
    • Command prompt
    • Docs
    • Example
    • File
    • Icon
    • Image
    • Kbd
    • Link
    • Map
    • Mark
    • Navbar
    • Navs and tabs
    • Release
    • Spinner
    • Spinner
    • Sub
    • Sup
    • Timeline
    • Toast
    • Tooltip
    • Overview
    • Styles
    • Scripts
    • Icons
    • Module development
    • Server headers
    • Server-side redirection
    • Credits
    • License

Image

Share via
Hinode
Link copied to clipboard

Use the image shortcode to display a responsive image with a specific aspect ratio.

On this page
 

  • Overview
  • Arguments
  • Examples
    • Aspect ratio
    • Color mode
    • Figures
    • Vector images

Overview  

New in v0.18.3 - The image shortcode now supports an additional ratio “3x2”. It also recognizes page resources correctly.

Use the image shortcode to display a responsive image with a specific aspect ratio. The source link can refer to either an image available in the /assets/img folder of your site or a public web location. The shortcode renders the image as a so-called image set  to optimize the image for different screen sizes and resolutions. Behind the scenes, Hugo renders the images in WebP format and stores them in a local folder (resources or public). The images are processed using the quality setting specified in the [imaging] section of the main config file  (defaults to 75). Supported image types are .png, .jpeg, .gif, .tiff, .bmp, and .webp. A fallback image of type .jpeg is provided for older browsers.

 
The shortcode supports vector images too (identified by their extension .svg). However, these images are not processed but rather used as is.

As an example, the following shortcode displays an image with its original aspect ratio. The image is adjusted for the active color mode. The shortcode processes two images behind the scenes, being img/responsive-light.png and img/responsive-dark.png. Only the image that matches the current color mode is shown.

Image caption
Image caption
markdown
{{< image src="img/responsive.png" mode="true" caption="Image caption" >}}

Arguments  

The shortcode supports the following arguments:

ArgumentRequiredDescription
srcYesRequired url of the image, e.g. “img/responsive.png”. Images with multiple color modes are expected to have a basename that ends with either -dark or -light.
ratioNoOptional aspect ratio of the image, either “1x1”, “3x2”, “4x3”, “16x9”, or “21x9”. If set, the image is resized and cropped to match the ratio. Vector images are resized instead of cropped to fit within the given dimension.
portraitNo
v0.18.3  
  Optional flag to adjust the ratio from landscape to portrait. The image itself is not rotated, only the crop area is adjusted. This value is ignored when no ratio is set.
wrapperNo
v0.18.3  
  Optional class attributes of the wrapper element, e.g. “mx-auto”.
classNoOptional class attribute of the inner img element, e.g. “rounded”.
titleNoOptional alternate text of the image.
captionNoOptional figure caption.
modeNoOptional flag indicating if the image should support color modes. If set, the shortcode searches for images that having a matching color-mode suffix such as light or dark.
loadingNo
v0.21.0  
  Optional loading behavior of the image, either “eager” (default) or “lazy”. The loading of lazily loaded images is deferred until the image is within scrolling range of the viewport. This should reduce the initial loading time of the website. It is recommended to lazily load only those images that are below the page fold.

Examples  

Change the style of your card with class attributes and shortcode arguments.

Aspect ratio  

As an example, the following shortcodes display a centered image with various aspect ratios.

Set the ratio to 1x1 for a square aspect ratio.

markdown
{{< image src="img/flowers.jpg" ratio="1x1" wrapper="col-6 mx-auto" >}}

Set the ratio to 3x2 for a landscape aspect ratio.

markdown
{{< image src="img/flowers.jpg" ratio="3x2" wrapper="col-6 mx-auto" >}}

Set the ratio to 4x3 for a landscape aspect ratio.

markdown
{{< image src="img/flowers.jpg" ratio="4x3" wrapper="col-6 mx-auto" >}}

Set the ratio to 16x9 for a landscape aspect ratio.

markdown
{{< image src="img/flowers.jpg" ratio="16x9" wrapper="col-6 mx-auto" >}}

Set the ratio to 21x9 for a landscape aspect ratio.

markdown
{{< image src="img/flowers.jpg" ratio="21x9" wrapper="col-6 mx-auto" >}}

Omit the ratio to keep the original aspect ratio.

markdown
{{< image src="img/flowers.jpg" wrapper="col-6 mx-auto" >}}

Color mode  

Set mode to true to use an image that is color-mode aware. The shortcode processes two images behind the scenes, being img/responsive-light.png and img/responsive-dark.png. Only the image that matches the current color mode is shown.

markdown
{{< image src="img/responsive.png" mode="true" >}}

Figures  

Add a caption to transform the image into a figure with caption.

Figure caption
markdown
{{< image src="img/watch.jpg" caption="Figure caption" >}}

Vector images  

The shortcode supports vector images of type .svg too. The shortcode supports the regular arguments, however, vector images are contained instead of cropped when the ratio is set. The next example shows a color-mode-aware vector image. The background is set to a contrasting color to illustrate the ratio behavior.

 
Unlike bitmap images, vector images are not processed but used as is. They should be maintained in the site’s static folder instead of the assets folder. Add a leading / to specify the absolute image location.
markdown
{{< image src="/img/logo_var.svg#logo" class="img-fluid w-50" wrapper="text-center" >}}
Last updated: November 5, 2023 • Update to Hinode v0.21.0 (1c81288)
On this page
  • Overview
  • Arguments
  • Examples
    • Aspect ratio
    • Color mode
    • Figures
    • Vector images
Image
Image
Hinode is a clean documentation and blog theme for your Hugo site based on Bootstrap 5.
Code licensed MIT, docs CC BY-NC 4.0
Currently v0.21.8
 
Links
Home 
About 
Docs 
Components 
Releases 
Guides
Getting started 
Developing modules 
Optimization 
Versioning 
Community
Issues  
Discussions  
Contribute 
Hinode
Code copied to clipboard