Enhancing YouTube Embeds in Hugo Custom Playlists and Fixing lite-youtube-embed Display Issues

Table of Contents

This guide provides solutions for two specific YouTube integration scenarios in Hugo: creating a flexible shortcode for embedding playlists, and resolving a common display issue where lite-youtube-embed videos unexpectedly shrink.

Embedding YouTube Playlists with a Custom Shortcode
#

While Hugo has a built-in youtube shortcode, it doesn’t natively offer the flexibility to easily embed entire playlists or start a playlist from a specific video within it. This custom shortcode addresses that need, allowing for more versatile playlist integration.

1. Identify Required YouTube IDs
#

To embed a playlist, you’ll need specific identifiers from YouTube:

Playlist ID: This is the main identifier for the entire playlist.
- Example URL: https://www.youtube.com/playlist?list=PLxxxxxxxxxxxxxxxxxxxx
- Your Playlist ID will be the string of characters after list=, e.g., PLxxxxxxxxxxxxxxxxxxxx.
Video ID (Optional): If you want the embedded playlist to start playing from a specific video within that playlist, you’ll also need that video’s ID.
- Example URL for a video within a playlist: https://www.youtube.com/watch?v=VIDEO_ID_TO_START&list=PLxxxxxxxxxx...
- The Video ID is the string after v=, e.g., VIDEO_ID_TO_START.

2. Create the `youtubePlaylist.html` Shortcode
#

Create a new file or update an existing one at layouts/shortcodes/youtubePlaylist.html in your Hugo project. Paste the following code into this file:

{{/* layouts/shortcodes/youtubePlaylist.html */}}
{{- $playlistId := .Get "id" | default (.Get 0) -}}
{{- $videoId := .Get "videoId" -}} {{/* Get optional specific video ID */}}
{{- $label := .Get "label" | default (printf "YouTube Playlist %s" $playlistId) -}}

{{ if $playlistId }} {{/* Playlist ID is always required */}}
  {{- $embedSrc := "" -}} {{/* Initialize embed source variable */}}

  {{- if $videoId -}}
    {{/* If a specific start video ID is given, use it with the playlist context */}}
    {{- $embedSrc = printf "https://www.youtube.com/embed/%s?list=%s" $videoId $playlistId -}}
  {{- else -}}
    {{/* Otherwise, use the default playlist starting point */}}
    {{- $embedSrc = printf "https://www.youtube.com/embed/videoseries?list=%s" $playlistId -}}
  {{- end -}}

  <div class="youtube-playlist-embed" style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%;">
    <iframe
      style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
      src="{{ $embedSrc }}" {{/* Use the constructed source URL */}}
      title="{{ $label }}"
      frameborder="0"
      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
      allowfullscreen>
    </iframe>
  </div>
{{ else }}
  {{ errorf "youtubePlaylist shortcode requires at least an 'id' parameter (the YouTube Playlist ID)." }}
{{ end }}

This shortcode constructs the appropriate YouTube embed URL based on whether a specific starting videoId is provided alongside the main playlist id.

3. Usage in Markdown
#

Now you can embed playlists in your .md files, leave the videoID blank if you want to start from the beginning:

{{< youtubePlaylist id="PLxxxxx" videoId="VIDEO_ID" label="NAME" >}}

Addressing Shrinking Issues in Hugo & Blowfish Theme
#

1. The Problem: Unexpected Video Shrinkage
#

When elements below a lite-youtube-embed are not present or are hidden, the parent container holding the main article content might collapse in width. If the video embed is set to width: 100%, it will only occupy 100% of this now tiny parent container, leading to a dramatically undersized video player.

2. The CSS Solution
#

The fix involves a combination of modifying your lite-youtube-embed shortcode slightly and adding some custom CSS.

a. Modifying the `youtubeLite.html` Shortcode
#

To provide a stable container for the video, modify your existing youtubeLite.html shortcode (typically found in layouts/shortcodes/youtubeLite.html) to wrap the <lite-youtube> custom element in a new div with a specific class.

<!-- layouts/shortcodes/youtubeLite.html -->
<div class="video-embed-wrapper">
    <lite-youtube ...></lite-youtube>
</div>

b. Adding Custom CSS
#

Next, add the following CSS to your site’s custom CSS file (e.g., assets/css/custom.css in the Blowfish theme, or your theme’s equivalent):

/* 1. Style the new video wrapper */
.video-embed-wrapper {
  width: 100%;
  max-width: 720px; /* Or match lite-youtube's default/configured max-width */
  margin: 1.5em auto; /* Center and add some vertical space */
}

/* Ensure lite-youtube element itself fills the wrapper */
.video-embed-wrapper lite-youtube {
  width: 100%;
  display: block; /* Ensures it behaves as a block for width and margin */
}

/* 2. Fix the collapsing ancestor container in Blowfish theme */
/* This targets the problematic div that might use max-w-fit or similar,
   causing the article content area to shrink.
   You may need to adjust this selector if your theme structure differs. */
section.flex.flex-col > div.min-w-0.min-h-0 {
  max-width: none; /* Override the shrinking behavior */
  width: 100%;   /* Ensure it takes up the available width from its parent */
}

Conclusion
#

By implementing the custom youtubePlaylist shortcode, you gain more control over embedding YouTube playlists. Furthermore, by applying the targeted CSS adjustments, you can resolve common layout issues with lite-youtube-embed in themes like Blowfish, ensuring your videos display correctly and maintain a good user experience.