Shortcodes in Hugo are basically chunks of HTML code that can be used in our content files. We can create our shortcode or use existing built-in shortcodes. For instance, to embed a YouTube video, we can use the built-in shortcode called youtube.

Here is how to use the youtube shortcode:

{{< youtube VIDEO-ID >}}

or

{{< youtube id="VIDEO-ID" >}}

This will embed a responsive video player for the given YouTube video.

Basic example

VIDEO-ID is the last part of the YouTube video’s URL. For instance if the URL is:

youtube.com/watch?v=3jUHOwHkiAI

Then the VIDEO-ID is 3jUHOwHkiAI and the code will look like this:

{{< youtube 3jUHOwHkiAI >}}

Automatically start playback

We can automatically start playback of the embedded video by setting the autoplay parameter of youtube shortcode to true.

{{< youtube id="VIDEO-ID" autoplay="true" >}}

Remember that we can’t use it like this: {{< youtube VIDEO-ID autoplay="true" >}} because we can’t mix named and unnamed parameters.

Embedded YouTube video’s title

We can set the title of the embedded YouTube video using the title parameter. If we do not set this parameter, the title will be “YouTube Video”. Therefore, it is good to set a descriptive title for accessibility reasons.

Here is how to use the title parameter of the youtube shortcode:

{{< youtube id="VIDEO-ID" title="Video title" >}}

Extend YouTube shortcode

We can extend Hugo’s built-in YouTube shortcode by creating our shortcode at /layouts/shortcodes/youtube.html.

The Hugo built-in youtube shortcode looks like this:

{{- $pc := .Page.Site.Config.Privacy.YouTube -}}
{{- if not $pc.Disable -}}
{{- $ytHost := cond $pc.PrivacyEnhanced  "www.youtube-nocookie.com" "www.youtube.com" -}}
{{- $id := .Get "id" | default (.Get 0) -}}
{{- $class := .Get "class" | default (.Get 1) -}}
{{- $title := .Get "title" | default "YouTube Video" }}
<div {{ with $class }}class="{{ . }}"{{ else }}style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;"{{ end }}>
  <iframe src="https://{{ $ytHost }}/embed/{{ $id }}{{ with .Get "autoplay" }}{{ if eq . "true" }}?autoplay=1{{ end }}{{ end }}" {{ if not $class }}style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" {{ end }}allowfullscreen title="{{ $title }}"></iframe>
</div>
{{ end -}}

Let’s say we want to add a new parameter called border, and our code at /layouts/shortcodes/youtube.html would look like this:

{{- $pc := .Page.Site.Config.Privacy.YouTube -}}
{{- if not $pc.Disable -}}
{{- $ytHost := cond $pc.PrivacyEnhanced  "www.youtube-nocookie.com" "www.youtube.com" -}}
{{- $id := .Get "id" | default (.Get 0) -}}
{{- $class := .Get "class" | default (.Get 1) -}}
{{- $title := .Get "title" | default "YouTube Video" }}
{{- $border := .Get "border" | default "0" }}
<div {{ with $class }}class="{{ . }}"{{ else }}style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;"{{ end }}>
  <iframe src="https://{{ $ytHost }}/embed/{{ $id }}{{ with .Get "autoplay" }}{{ if eq . "true" }}?autoplay=1{{ end }}{{ end }}" {{ if not $class }}style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:{{ $border }};" {{ end }}allowfullscreen title="{{ $title }}"></iframe>
</div>
{{ end -}}

Now, we can embed a YouTube video with a border like this:

{{< youtube id="3jUHOwHkiAI" border="5px solid red" >}}

In this case, the player will have a red 5-pixel border.