Subscribe by email, free
Your daily briefing for podcasting and on-demand

How to do HTML episode notes in your RSS feed

December 7, 2019 · Updated April 17, 2020 · By · 5.7 minutes to read

Some people like putting HTML into their episode notes. Others leave it as unformatted text. Which is right? Both of them.

tl;dr: Under the <item> tag, use <description> for unformatted text; and then use <content:encoded> for a fancy HTML version. Apps will - almost always - display the right one.

What is the right way to do HTML episode notes?

(“Episode notes” here are the notes for individual episodes under <item>. They differ from “show notes”, which could be a description for the show itself, i.e. the bit directly under <channel>.)

Some apps don’t show full HTML in episode notes. Some do. And some do different things in different places. We really wanted to get our show notes working in as many different places as possible, so we’ve spent the last year experimenting. Here’s the actual answer - one that works in all of the biggest apps.

The RSS documentation says that when you have both <content:encoded> and <description> present in an <item>, the <description> field is used as a summary for the <content:encoded>. Further, <content:encoded> must be HTML encoded: so links and other things are all good. Most podcast hosts just duplicate the content in both: but that’s actually not what the specification says.

As an additional excitement: we produce individual episode images, in our RSS only (and not embedded in the audio), linked with <itunes:image>. So let’s test which of the big podcast apps support that, too. (You get better support if you embed the image in your audio as well - we don’t do that,)

Here’s the RSS code for the <item> we chose as a test. I’ve added linebreaks in this reproduction, so we can see what’s going on: the only “real” linebreak is in the <description> field.

...
<item>
<title>Podcasts are getting shorter</title>
<link>https://podnews.net/update/podcasts-getting-shorter</link>
<pubDate>Fri, 06 Dec 2019 08:27:45 +0000</pubDate>
<description>Robert Krulwich is retiring

Visit https://podnews.net/update/podcasts-getting-shorter for all the links,
and to subscribe.</description>
<content:encoded>
<![CDATA[<P><small>Visit <a href="https://podnews.net/update/podcasts-getting-shorter">
https://podnews.net/update/podcasts-getting-shorter</a> for all the links, and
to subscribe.</small></p> 

 ... and lots more HTML with images and stuff, ending with ...

<P><a rel="payment" href="https://podnews.net/patreon">Support us</a></P>]]>
</content:encoded>
<author>james@crid.land (James Cridland)</author>
<guid isPermaLink="true">https://podnews.net/update/podcasts-getting-shorter</guid>
<itunes:explicit>no</itunes:explicit>
<itunes:episodeType>full</itunes:episodeType>
<itunes:title>Podcasts are getting shorter</itunes:title>
<itunes:subtitle>Robert Krulwich is retiring</itunes:subtitle>
<itunes:summary>
Podcasts are getting shorter: Robert Krulwich is retiring
</itunes:summary>
<itunes:episode>659</itunes:episode>
<itunes:author>Podnews LLC</itunes:author>
<itunes:image href="https://podnews.net/audio/podnews191206.jpeg" />
<enclosure url="https://chtbl.com/track/podnews.net/audio/podnews191206.m4a"
type="audio/x-m4a" length="1585328" />
<itunes:duration>160</itunes:duration>
</item>
...

Tip: Of note, the Apple RSS “feed example” in their documentation places <content:encoded> inside the <description> tag. This is wrong. It doesn’t work, it’s not compliant, it’s 100% wrong.

We tested the above code with the apps that get more than 1% of all downloads, according to Libsyn.

Apple Podcasts - iOS

We’re using the version with iOS v13.1.2, on an iPod Touch.

When subscribed: Podnews shows a list of each episodes, using <itunes:title> and <itunes:summary> if there’s space. Click “Details”, to see the <itunes:title> and <itunes:subtitle>. Play it, maximise the player, scroll down, and you’ll see <content:encoded>. The episode artwork is not visible.

When not subscribed: Podnews shows a list of each episodes, using <itunes:title> and <itunes:summary> if there’s space. Click “Details”, to see the <itunes:title> and <itunes:subtitle>. Play it, maximise the player, scroll down, and you’ll see <itunes:summary>. The episode artwork is not visible.

Apple Podcasts - macOS

We’re using version 1.0.0 (1425.5).

When subscribed: Podnews shows a list of each episodes, using <itunes:title> and <itunes:summary> if there’s space. Click the title, to see the <itunes:title> and <itunes:subtitle>. Play it, hit the “i” next to the player, and you’ll see <content:encoded>. The episode artwork is not visible.

When not subscribed: Podnews shows a list of each episodes, using <itunes:title> and <itunes:summary> if there’s space. Click the title, to see the <itunes:title> and <itunes:summary>. Play it, hit the “i” next to the player, and you’ll see <content:encoded>. The episode artwork is not visible.

Apple Podcast - web

Podnews shows a list of episodes, always using <itunes:title> and <itunes:summary>. Click the title, to see the <itunes:title> and <itunes:summary>. The episode artwork is visible in this view.

Spotify - Android

We’re using v8.5.33.831

A search for Podnews shows a list of episodes, using <title>, the first two lines of <description>, and the episode image. Spotify doesn’t support HTML - but clicking on the episode shows the <description> with the link automatically made clickable. This is following the RSS specification.

Google Podcasts - Android

We’re using v1.0.0.266384425 and Google v10.87.13.21.arm64 (beta).

A search for Podnews shows a list of episodes, using <title>. Click the episode title to view the <content:encoded>, with links. Episode artwork is not used.

Google Podcasts - Web

Podnews shows a list of episodes, using <title> and <itunes:subtitle> (or perhaps the first line of <description>). Click an episode to view the <content:encoded>, with links. Episode artwork is not used.

Pocket Casts - iOS

We’re using v7.5.2 (649)

The episode list shows episode numbers and we presume <itunes:title>. Clicking through and scrolling down, you can read the full <content:encoded>, with images and links. It uses episode images.

Overcast - iOS

v2019.11

The episode list shows <itunes:title> and <itunes:subtitle>. Pressing the 'i’ button shows the full <content:encoded>, with images (loaded on request) and links. Pressing play allows you to swipe to see the <itunes:title>, <itunes:subtitle> and the full <content:encoded>. Overcast does not use episode images.

Castbox - Android

The episode list shows episode numbers, superimposed over the episode image, and either the <title> or the <itunes:title>. Clicking through, the full <content:encoded> is visible, with images and links, and the episode image. Playing it also shows the episode image.

Podcast Addict - Android

When subscribed, the episode list shows the <title> and <itunes:subtitle>, and the episode image. Clicking through shows the full <content:encoded> with links and images. Playing it also shows the episode image, and you can swipe to read the <content:encoded> episode notes.

Stitcher - Android

Stitcher takes the content from <content:encoded> and strips it of all HTML and formatting. The episode image is also not shown.

Other apps:

Have you discovered something different? We’d love to hear from you, in the comments below.

James Cridland is the Editor of Podnews, a keynote speaker and consultant. He wrote his first podcast RSS feed in January 2005; and also launched the first live radio streaming app for mobile phones in the same year. He's worked in the audio industry since 1989.

Comments

Our supporters (become one)

Gold supporters

Silver supporters

Get a global view on podcasting and on-demand with our daily news briefing

Subscribe to our daily newsletter by email, free