Podcaster

Hosting a podcast and creating its website with Eleventy.

eleventy-plugin-podcaster

Installation

To install the npm package, type this at the command line:

npm install eleventy-plugin-podcaster

And then include the plugin in your Eleventy configuration file.

// eleventy.config.js

import Podcaster from 'eleventy-plugin-podcaster'

export default function (eleventyConfig) {
  .
  .
  eleventyConfig.addPlugin(Podcaster)
  .
  .
}

Podcast information

Once you’ve installed Podcaster in your Eleventy project, the next step is to provide it with information about your podcast — the title, the owner, the category, the subcategory and so on. The easiest way to do this is to put the information in your data directory in a podcast.json file.

Here’s an example.

{
  "title": "Flight Through Entirety: A Doctor Who Podcast",
  "description": "Flying through the entirety of Doctor Who. Originally with cake, but now with guests.",
  "siteUrl": "https://flightthroughentirety.com",
  "author": "Flight Through Entirety",
  "category": "TV & Film",
  "language": "en-AU",
}

Read more about podcast information.

Episode information

For each podcast episode you create, you will also create a corresponding Eleventy template. This template will have the tag podcastEpisode; its front matter will contain the information about the episode — the title, the release date, the episode number, the filename and so on — and its content will contain the episode’s show notes.

Here’s an example.

---
title: Entering a new Phase
date: 2024-04-14
tags:
  - podcastEpisode
episode:
  filename: 500YD S1E1, Entering a New Phase.mp3
  seasonNumber: 1
  episodeNumber: 1
  size: 61231442 # bytes
  duration: 3778.482 # seconds
---
A big week for beginnings this week, with a new Doctor, a new origin story
for the Daleks, and a whole new approach to defeating the bad guys. Oh, and
a new podcast to discuss them all on. So let's welcome Patrick Troughton 
to the studio floor, as we discuss _The Power of the Daleks_.

Read more about episode information.

The podcast feed

Podcaster uses the information you’ve provided about your podcast and about its individual episodes to create the podcast feed.

By default, your podcast feed will be located at /feed/podcast.xml, which means that the URL you submit to Apple Podcasts or Spotify (or wherever) will be {{ podcast.siteUrl }}/feed/podcast.xml

Using podcast information and episode information in templates

All the podcast and episode information you provide is made available to your templates through the data cascade, including title and date, as well as fields in the podcast and episode objects.

Here’s how you might use this information to describe a single podcast episode in a Liquid template.

<article>
  <h1>{{ title }}</h1>
  <p class="episode-number">Episode {{ episode.episodeNumber }}</p>
  <p class="release-date">{{ date | date: "%A %-e %B %Y" }}</p>
  <section class="content">
    {{ content }}
  </section>
  <audio controls src="{{ episode.url }}" preload="none">
  <p class="audio-details">
    Episode {{ episode.episodeNumber }}: {{ title }}
    | Recorded on {{ recordingDate | date: "%A %-e %B %Y" }}
    | {{ episode.size | readableSize }}
    | Duration {{ episode.duration | readableDuration }}
    | <a download href="{{ episode.url }}">Download</a>
  </p>
</article>

All podcast episode templates belong to the collections.podcastEpisode collection, which means you can list several episodes on a single page using Eleventy’s pagination feature. In that case, each episode’s information will be available in its collection item data structure.

Tip

episode.size gives you the podcast’s size in bytes and episode.duration gives you the duration in seconds. To include size and duration in your templates in a human-readable format, use Podcaster’s filters readableSize and readableDuration, as in the example above.

Hosting

You can host your podcast site — along with its feed — the same way you would host any Eleventy site, using a Jamstack provider linked to your source control repository or using a classic web host which will allow you to upload the contents of your output directory.

However, your podcast episode files should be hosted somewhere else, preferably on a Content Delivery Network (CDN), which will let your listeners download your episodes promptly and quickly.

To find out how to set this up and how to make this work with Podcaster, read more about hosting your podcast episode files.

Optional features

Podcaster also implements some optional features which are useful for creating podcast websites — drafts, excerpts, a readableDate filter, and a pageTitle attribute.

These are not fundamental features of a podcast website, which is why they are opt-in. You can activate them by passing options to the addPlugin method in your configuration file.

    eleventyConfig.addPlugin(podcaster, {
      handleDrafts: true,
      handleExcerpts: true,
      readableDateLocale: 'en-GB',
      calculatePageTitle: true
    })

Read more about optional features.

Podcaster in action

I started podcasting and creating podcasting websites in 2014. At first I used Squarespace, then WordPress, and then Jekyll, before finally settling on Eleventy late in 2022.

I now have seven podcast websites powered by Eleventy, and Podcaster was derived from the code I used to create them.

Here’s the list:

Licence

This plugin is available as open source under the terms of the ISC License.