Jekyll::Podcast

jekyll-podcast converts a Jekyll blog into a podcast webpage. It provides you with all the functionality you need to make your podcast fully accessible from your webpage, and it creates a podcast feed which you can submit to Apple Podcasts, Google Podcasts, Spotify or any other podcast directory.

Installation

Add this line to your application's Gemfile:

gem 'jekyll-podcast'

And then execute:

bundle install

Or install it yourself as:

gem install jekyll-podcast

Usage

Providing information about your podcast

Most of the important information about your podcast — the title, the owner, the category, the subcategory and so on should appear in a podcast block in _config.yml.

# _config.yml

podcast:
  title: "Flight Through Entirety: A Doctor Who Podcast"
  subtitle: &subtitle >-
    Flying through the entirety of Doctor Who. Originally with cake,but now with guests.
  # I've made the description and the summary
  # the same as the subtitle, but you can do
  # whatever you like here.
  description: *subtitle
  summary: *subtitle
  email: [email protected]
  language: en-AU
  author: Flight Through Entirety
  owner: Nathan Bottomley
  explicit: false
  category: TV & Film
  subcategory: TV Reviews
  complete: no

Explanations of all of the fields here can be found on Apple's page about podcast feed tags. A list of podcast categories and subcategories can be found here.

You will also need to provide your podcast artwork, which should be a JPEG file 3000 × 3000 pixels in size. jekyll-podcast will expect to find this file at /assets/images/podcast-logo.jpeg.

Providing information about your podcast episodes

Each post in the _posts directory will correspond to an episode of your podcast. So, for example, the publication date of the post will be the publication date of the episode, and the content of the post will be the episode's description or shownotes, which will (normally) be displayed in your listeners' podcast player.

Other information about your podcast episodes should be provided in each post's front matter. Here's an example.

tags: #optional
- Series 6
- The Eleventh Doctor
contributors: #also optional
- Nathan Bottomley
podcast:
  # the episode number
  episode: 217
  # the episode filename, including the extension
  file: >-
    FTE 217, Gaslight Girlboss Ginger (Day of the Moon).mp3
  # optional
  recording_date: 2021-08-01

The episode files

By default, you will store your episodes in /assets/episodes, and they will be served directly from your website.

If you use an analytics service that requires a URL prefix to track your episodes' data, you will need to provide that prefix as part of the podcast block in _config.yml.

# _config.yml

podcast:
  tracking_prefix: https://dts.podtrac.com/redirect.mp3

If you use a CDN or an S3-compatible storage solution to host your podcast episodes, you will need to provide the URL for that sevice. You must also store your episodes in a folder called /_episodes, so that Jekyll doesn't include the episode files in the website it builds.

# _config.yml

podcast:
  remote_episode_host: https://flight-through-entirety.us-east-1.linodeobjects.com

If you store your episodes on some other service, you will have to take care of uploading the episodes to that service yourself. I generally write a build script using rsync or s3cmd sync to do this.

Creating your podcast feed

If you set up your _config.yml file and the front matter of your posts as specified above, jekyll-podcast will have enough information to create your podcast feed.

Your podcast feed will appear in your _site directory at feed/podcast.

Your shownotes

The contents of each episode's post will appear on the website, as usual, but it will also be used as the description or shownotes for your episode and displayed in your listeners' podcast players.

It's easy to make a podcast player show a different description from the post displayed on your site. Just create an include called post-feed-content.html in the _includes folder and use it to define the content that you want to appear in a podcast player. Here's an example.

<!-- post-feed-content.html -->

<p>
  <em>
    {{ post.star_trek.series }}, 
    {{ post.star_trek.episode }}.
    First broadcast on {{ post.star_trek.broadcast | date: "%A, %e %B %Y" }}
  </em>
</p>

{{ post.content }}

Podcast episode permalinks

Unlike a blog, a podcast website should have simple permalinks. Best practice tends to be just the episode number.

https://flightthroughentirety.com/217

To make this possible, jekyll-podcast provides a :podcast_episode placeholder, which you can use in your default permalink definitions in _config.yml.

# _config.yml

- scope:
    path: ""
    type: posts
  values:
    permalink: /:podcast_episode/

You can combine this placeholder with other placeholders if you like. One possibility might be combining the episode number with the slug, like this:

# _config.yml

values:
  permalink: /:podcast_episode-:slug/

Remember to put the / at the end of the permalink pattern, so that you don't end up with the .html suffix at the end of your URLs.

Podcast episode data

When jekyll-podcast builds your site, it analyses the podcast episodes in your assets/episodes folder (or your _episodes folder). As a result, the following information becomes available to your Liquid templates.

{{ post.podcast.duration }} 
→ 0:57:22

{{ post.podcast.size_in_megabytes }}
→ 40.1 MB

You might want to consider adding the recording date to the podcast blog in the front matter of your posts, so that you can display it in your posts as well.

podcast:
  recording_date: 2022-07-13

{{ post.podcast.recording_date | date: "%A, %e %B %Y" }} 
→ Wednesday, 13 July 2022

Including an <audio> tag

You should also create an include for your post so that your listeners can listen to the episodes on your website. The easiest way to do this is using an <audio> tag. jekyll-podcast provides a liquid filter called episode_url, which will add the correct URL to the filename you provide in your front matter.

Here's an example.

<!-- _includes/audio-player.html -->

<audio controls preload="metadata" src="{{ post.podcast.file | episode_url }}"></audio>

Podcast data

While jekyll-podcast is analysing your podcast files, it collects some interesting information about your podcast, and logs it to screen as part of the build process. This information includes the number of episodes, their total size in megabytes and their total duration (to the nearest millisecond).

236 episodes; 15786.9 MB; 9 d 16 h 6 min 25.577 s 

Contributor pages

jekyll-podcasts has a feature which allows you to create bio pages for each of your contributors. These pages can include whatever information you like, including a chronological list of all of the episodes that a contributor has appeared in.

To get this to work, you need to create a Jekyll collection for your contributor pages. To do this, add a block like this to _config.yml.

# _config.yml

collections:
  contributors:
    output: true
    permalink: /contributors/:slug/

Then create a layout for your contributor pages, and specify it as a default in _config.yml.

# _config.yml

defaults:
  - scope:
      path: ""
      type: contributors
    values:
      layout: contributors-page

This layout should include the page content, and then iterate through the contributor's posts, which are all accessible to the layout and the page as {{ page.posts }}. Here's a simple example.

<!-- contributors-page.html -->

<h1>page.title</h1>

{{ content }}

{% for post in page.posts %}
  <article>
    <h1>{{ post.title }}</h1>
    {{ post.content }}
  </article>
{% endfor %}

Now you can create the contributor's pages. Each page can contain a picture, a bio and anything else you want. So long as you set the layout in the front matter to contributors-page, the pages will display all of the episodes that the contributor is involved in.

To indicate which contributors are involved in a particular episode, just add a list of contributors to the front matter of the corresponding post.

contributors:
- Jonathan Archer
- Gabriel Lorca
- Christopher Pike
- James T Kirk

Originally this feature was called Guest pages, and it's still possible to call this feature whatever you want. Just provide an replacement name in plural form to the podcast block in _config.yml as the contributors_alias, like this:

# _config.yml

podcast:
 contributors_alias: guests

If you do this, you should also change the name of the collection and the default type in _config.yml as shown above.

Tag pages

There are plenty of other implementations of tag pages for Jekyll blogs, and so this one just aims to be as simple as possible.

To specify an episode's tags, just list them in the post's front matter.

tags:
- The Tenth Doctor
- Specials
- Christmas

That's it really. By default, the permalink of a tag page will be the slugified version of the tag's text.

If you want to specify permalinks for a tag, you can do that by creating a file in the data directory called tag_permalinks.yaml or tag_permalinks.json. It should be a hash, with the tag as the key and the permalink as the value.

# tag_permalinks.yaml

"Star Trek: The Next Generation": /tng/
"Star Trek: Deep Space Nine": /ds9/
"Star Trek: Voyager": /voy/

To create a list of tag links attached to a post, you can use jekyll-podcast's tag_link filter, like this.

{% for tag in post.tags %}
  {{ tag | tag_link }}
{% endfor %}

The pagetitle tag

The {% pagetitle %} Liquid tag can be placed in the <head> of your HTML layouts, and it will render a <title> tag for your page. This tag will consist of the title of your page (as specified in the front matter), followed by an em-dash, followed by the title of your site (as specified in _config.yml). If your page has no title or if its title is the same as your site's title, the tag will just contain your site's title.

jekyll-podcast in action

I've been using jekyll-podcast to create podcast websites since the middle of 2021, after hosting podcasts with WordPress for a number of years. It has allowed me to take more control of my podcast sites, and to spend my time writing HTML and Sass (and Ruby, I guess) instead of wrestling with WordPress plugins and PHP.

If you would like to see some podcasts powered by jekyll-podcast, here's a list of the podcasts I'm currently running.

• Flight Through Entirety, a Doctor Who podcast flying through the entirety of the show's 60-year history.
• Bondfinger, a James Bond commentary podcast that has run out of James Bond films and now spends its time drinking and watching terrible TV shows from the 1960s mostly.
• Jodie into Terror, a Doctor Who flashcast in which we give our (intermittently) enthusiastic hot takes on the most recent era of Doctor Who mere days after each episode's first broadcast in the UK.
• Untitled Star Trek Project, a Star Trek commentary podcast in which two friends watch Star Trek episodes from any series, chosen (nearly) at random by a page on the podcast website.

License

The gem is available as open source under the terms of the MIT License.