Embedding audio files in a Hugo site

I was writing a post today and wanted to embed an mp3 file of some text to speech output. Hugo doesn’t support this natively using shortcodes, so I needed a way to add these, ideally without adding any HTML.

To do this, I needed to create my own shortcode implementation. As it turns out, based on the Hugo shortcode guide, these are not to complicated.

Create the shortcode

Shortcodes live in a folder called shortcodes in your layout folder and are implemented as HTML files, named as <shortcode>.html. For example, if you wanted to create a shortcode called audio you would create the file layout/shortcodes/audio.html.

Shortcodes are snippets of HTML that can be passed named parameters. The HTML for an HTML audio player is:

<audio controls preload="auto">
 <source src="file.mp3">
</audio>

Shortcodes can also be parameterized with name parameters that you can get using the {{ .Get "name" }} method, passing the name of the parameter. For the audio shortcode, I need to pass in the audio file, so this can be a parameter. This is set in the src field, so I called this parameter src:

<audio controls preload="auto">
 <source src="{{ .Get "src" }}">
</audio>

Done! This is my entire shortcode.

Use the shortcode

Once my shortcode was written, it was easy to use. I added the mp3 file I want to play to the folder for my blog post, and added the shortcode tag in the markdown file for the post:

{< audio src="intro-to-generative-ai.m4a" >}

Once done, the audio player appears on my page:

Use this yourself

If you want to use this shortcode, you can find it on the GitHub repo for this site.