Images and Media

The Mono theme provides several options for incorporating images and media into posts with clean and responsive layouts.

Images

Image Placement

There are two main ways to organize images in a Hugo site:

1. Post Bundle (Recommended): Place images alongside the post in a folder, where the markdown file is named index.md and images are in the same directory:

content/posts/my-post/
├── index.md
├── image1.jpg
└── image2.png

Which is then referenced with:

![Alt text](image1.jpg)

2. Static Folder: Otherwise, we can place them in the static folder that maps to the root of the site:

static/images/
├── placeholder.png
└── banner.jpg

And reference them with an absolute path:

![Alt text](/images/placeholder.png)

Post bundles are recommended as the standard way to manage images related to specific content, allowing for better organization and easier portability of posts. static folder images are better suited for site-wide assets like logos or icons.

Image Syntax

Basic Image Syntax: The simplest way to add an image is using standard Markdown syntax:

![Alt text for the image](image.jpg)

This renders a basic image with the specified alt text for accessibility:

All images in the Mono theme are responsive by default, automatically adjusting to fit the width of the container while maintaining their aspect ratio.

Controlling Image Size: To control image dimensions, use HTML with inline styles:

<img src="/images/placeholder-img.png" alt="Small image" style="width: 200px;">
<img src="/images/placeholder-img.png" alt="Half width" style="width: 50%;">
<img src="/images/placeholder-img.png" alt="Fixed dimensions" width="300" height="200">

Images with Captions: For images that require additional context, we can add captions using the HTML <figure> and <figcaption> elements:

<figure>
  <img src="image.jpg" alt="Image description">
  <figcaption>This is a caption for the image</figcaption>
</figure>

This produces an image with a caption styled as follows:

Image Grids

For creating visual galleries or comparing images side by side, we can use the image grid system.

Basic Grid: Use the figure-grid class to create a simple grid of images:

<div class="figure-grid">
  <img src="image1.jpg" alt="First image">
  <img src="image2.jpg" alt="Second image">
</div>

This creates a responsive grid that automatically adjusts based on screen size:

Grid with Captions: We can also include captions for each image in the grid:

<div class="figure-grid">
  <figure>
    <img src="image1.jpg" alt="First image">
    <figcaption>Caption for first image</figcaption>
  </figure>
  <figure>
    <img src="image2.jpg" alt="Second image">
    <figcaption>Caption for second image</figcaption>
  </figure>
</div>

This produces a grid where each image has its own caption:

The grid automatically adjusts to show a single column on mobile devices and multiple columns on larger screens, ensuring a good viewing experience across all devices.

SVG Images

SVG images are fully supported and can be included directly in markdown:

<svg width="100" height="100">
  <circle cx="50" cy="50" r="40" stroke="black" stroke-width="2" fill="red" />
</svg>

SVGs are ideal for icons, logos, and illustrations as they scale perfectly to any size without loss of quality.

Image Accessibility

Always include descriptive alt text for images to ensure content is accessible to all users:

![Detailed description of what the image shows and its significance](image.jpg)

For decorative images that don’t convey important information, we can use an empty alt attribute:

![](decorative-image.jpg)

Full-Width Images

To make an image span the full width of the page, breaking out of the content container for maximum visual impact, use the full-width-img shortcode:

{{< full-width-img 
    src="banner.jpg"
    alt="Description of the image" 
    caption="Optional caption for the image" 
>}}

This shortcode inserts a full-width image that extends beyond the normal content boundaries:

This is particularly effective for landscape images, hero images, or any visual that deserves special emphasis.

Banner Images for Posts

The Mono theme also supports banner images for posts through the front matter:

---
title: "Post Title"
banner:
  src: "banner.jpg"
  alt: "Description of the image"
  caption: "Optional caption for the image"
---

These banner images appear at the top of the post as a sort of header image.

Image Optimization

The Mono theme includes basic image optimizations:

• Lazy loading: Shortcode images (full-width-img, media) use loading="lazy" for faster page loads
• Banner resizing: Post banner images are automatically resized to appropriate dimensions

For best results, place images in post bundles (alongside the markdown file) rather than in static/, as Hugo can process bundled images.

Other Media

The Mono theme includes a unified media shortcode that handles both videos and audio files, providing a consistent, responsive media experience.

Embedding Videos

To embed videos from YouTube or Vimeo, use the media shortcode:

{{< media type="video" service="youtube" id="dQw4w9WgXcQ" >}}

This creates a responsive video container that maintains the proper aspect ratio.

For Vimeo videos:

{{< media type="video" service="vimeo" id="146022717" >}}

For self-hosted videos, specify the source path and media type:

{{< media type="video" src="/videos/my-video.mp4" mediaType="video/mp4" >}}

Embedding Audio

For audio content, use the same media shortcode with type="audio":

{{< media type="audio" src="/audio/sample-audio.mp3" mediaType="audio/mp3" >}}

This displays an audio player that spans the width of the content area:

For different audio formats:

{{< media type="audio" src="/audio/sample.ogg" mediaType="audio/ogg" >}}

Parameters

The media shortcode supports these parameters:

• type: Either “video” or “audio” (default: “video”)
• service: For videos, either “youtube”, “vimeo”, or “file” (default: “file”)
• id: The video ID for YouTube or Vimeo
• src: The file path for self-hosted media
• mediaType: The MIME type (default: “video/mp4” for videos, “audio/mp3” for audio)

All media elements are responsively styled and work well on all screen sizes.