eleventy-plugin-podcaster 0.9.2 → 0.9.4

package/README.md

@@ -2,7 +2,6 @@
 
 `eleventy-plugin-podcaster` — or **Podcaster**, as we will call it from now on — lets you use Eleventy to create a podcast and its accompanying website. **Podcaster** creates the podcast feed that you submit to Apple Podcasts, Spotify or any other podcast directory. And it provides information about your podcast to your Eleventy templates. This means that you can include information about the podcast and its episodes on your podcast's website, creating pages for individual episodes, guests, topics, seasons or anything else at all.
 
-
 ## Installation
 
 To install the npm package, type this at the command line:

package/docs/episode-information.md

@@ -36,6 +36,7 @@ Here's a detailed description of the data you need to provide here.
 | `title` | The title of the episode; this will also be the title of the post on the website. | yes |
 | `date` | The release date of the episode; this will also be the date of the post on the website | yes |
 | `tags` | Every episode post must have the tag `podcastEpisode` included in the `tags` array. Other tags are also permitted. | yes |
+| `guid` | A unique ID for the post. Normally this will be the post's URL, in which case there is no need to provide it here. It's should really only be necessary to provide it if you're importing the podcast from some other system that has assigned a guid to each post.  | no |
 | `episode.filename` | The filename of the episode's audio file. | yes |
 | `episode.seasonNumber` | The  season number. (Most podcasts don't group their episodes into seasons.) | no |
 | `episode.episodeNumber` | The episode number. Needn't be unique, but the combination of `seasonNumber` and `episodeNumber` must be unique. | yes |

package/docs/optional-features.md

@@ -12,7 +12,8 @@ export default function (eleventyConfig) {
   .
   eleventyConfig.addPlugin(podcasterPlugin, {
     handleDrafts: true,
-    handleExcerpts: true
+    handleExcerpts: true,
+    readableDateLocale: 'en-GB'
   })
   .
   .
@@ -34,3 +35,9 @@ Excerpts are available in a template as `{{ excerpt }}`, but you will probably a
 1. As an `excerpt` field in the post's front matter. This should be written in Markdown.
 2. The part of the post between the excerpt delimiters `<!---excerpt-->` and `<!---endexcerpt-->` .
 3. The first paragraph in the post which is not nested inside another tag. (This is so that a blockquote at the beginning of a post isn't included in the excerpt.)
+
+## `readableDate` filter
+
+**Podcaster** optionally provides a `readableDate` filter, to match `readableDuration` and `readableSize`. It transforms a date into a localised string, which usually includes weekday, day of month, month and year.
+
+To make **Podcaster** provide this filter, pass a locale string as one of the options when you're adding the plugin to your config file. In English, the two most common locale strings are `'en-GB'` and `'en-US'`.

package/docs/podcast-information.md

@@ -42,6 +42,7 @@ However, `eleventy-plugin-podcast` is quite customisable. He's another `podcast.
   "episodeUrlBase": "https://example.fte-cdn.com/",
   "feedEpisodeContentTemplate": "feed-episode-content.njk",
   "feedEpisodeDescriptionTemplate": "feed-episode-description.njk"
+  "feedEpisodeSummaryTemplate": "feed-episode-summary.njk"
 }
 ```
 
@@ -67,8 +68,28 @@ And here's a detailed description of all of this information.
 | `copyright` | The copyright owner of the podcast. If omitted, the value supplied for `author` is used instead. | no |
 | `startingYear` | The year your podcast started. Used to express the copyright date as a range (_"© 2014–2024 Flight Through Entirety"_). If this is omitted, the copyright date will just be the current year. | no |
 | `episodeUrlBase` | If you store your podcast episodes on a CDN, or if you use a podcast analytics service, this is where you specify the base URL for them. If you don't specify this, it defaults to `https://{{ podcast.siteUrl }}/episodes/` | no |
-| `feedEpisodeContentTemplate` | The name of an include template that will be used to create the show notes of each episode, as displayed in your listeners' podcast players. The content of this template should be HTML. You only need to include this if you want the show notes in podcast players to be different from the show notes on the website. | no |
-| `feedEpisodeDescriptionTemplate` | The name of an include template that will be used to create the description of each episode. The content of this template should be plain text. If it's omitted, the description will just be an abbreviated text version of the `content` of the episode's post. | no |
 
 [categories]: https://podcasters.apple.com/support/1691-apple-podcasts-categories
 [lang]: https://www.rssboard.org/rss-language-codes
+
+## Feed episode templates
+
+For each episode of the podcast, the feed can contain three textual descriptions — `content`, `description` and `summary`. `content` is HTML and will contain the show notes of an episode. `description` and `summary` are short plain text descriptions of the episode.
+
+By default, **Podcaster** will set the `content` of the feed to the `content` of an episode's post, and will set `summary` and `description` to an abbreviated version of the content (roughly the first 500 characters of the `content`). And this will be perfectly fine for most podcast feeds.
+
+However, if you want to, you can override any or all of these three textual descriptions by providing special templates in the includes directory and adding their names to the `podcast` object.
+
+| field | value | required? |
+| ----- | ----- | --------- |
+| `feedEpisodeContentTemplate` | The name of an include template that will be used to create the show notes of each episode, as displayed in your listeners' podcast players. The content of this template should be HTML. You only need to include this if you want the show notes in podcast players to be different from the show notes on the website. | no |
+| `feedEpisodeDescriptionTemplate` | The name of an include template that will be used to create the description of each episode. The content of this template should be plain text. If it's omitted, the description will just be an abbreviated text version of the `content` of the episode's post. | no |
+| `feedEpisodeSummaryTemplate` | The name of an include template that will be used to create the summary of each episode. The content of this template should be plain text. If it's omitted, the description will just be an abbreviated text version of the `content` of the episode's post. | no |
+
+These templates must be Nunjucks templates, and the post for the episode must be referred to by the variable `post`. Here's a sample content template from one of my podcast websites.
+
+```njk
+<p class="diary-date">{{ post.data.diaryDate | readableDate }}</p>
+<p class="topic">{{ post.data.topic }}</p>
+{{ post.content | safe }}
+```

package/eleventy.config.js

@@ -56,15 +56,17 @@ export default function (eleventyConfig, options = {}) {
 
   eleventyConfig.addShortcode('year', () => DateTime.now().year)
 
-  eleventyConfig.addFilter('readableDate', function (date) {
-    if (date instanceof Date) {
-      date = date.toISOString()
-    }
-    const result = DateTime.fromISO(date, {
-      zone: 'UTC'
+  if (options.readableDateLocale) {
+    eleventyConfig.addFilter('readableDate', function (date) {
+      if (date instanceof Date) {
+        date = date.toISOString()
+      }
+      const result = DateTime.fromISO(date, {
+        zone: 'UTC'
+      })
+      return result.setLocale(options.readableDateLocale).toLocaleString(DateTime.DATE_HUGE)
     })
-    return result.setLocale('en-GB').toLocaleString(DateTime.DATE_HUGE)
-  })
+  }
 
   eleventyConfig.addFilter('readableDuration', function (seconds) {
     if (!seconds) return '0:00:00'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-podcaster",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "An Eleventy plugin that allows you to create a podcast and its accompanying website",
   "main": "eleventy.config.js",
   "exports": {

package/src/podcastFeed.njk

@@ -29,7 +29,7 @@ eleventyAllowMissingExtension: true
     {%- else %}
     <itunes:category text="{{ podcast.category }}" />
     {%- endif %}
-    <itunes:image href="{{ podcast.imagePath | htmlBaseUrl(podcast.siteUrl) }}"></itunes:image>
+    <itunes:image href="{{ podcast.imagePath | htmlBaseUrl(siteUrl) }}"></itunes:image>
     <itunes:summary>{{ podcast.summary or podcast.description }}</itunes:summary>
     {% if podcast.explicit !== undefined %}<itunes:explicit>{{ podcast.explicit or "false" }}</itunes:explicit>{% endif -%}
     {%- if podcast.type %}
@@ -46,32 +46,44 @@ eleventyAllowMissingExtension: true
     {% for post in collections.podcastEpisode | reverse %}
     <item>
       <title>{{ post.data.title }}</title>
-      <link>{{ post.url | htmlBaseUrl(podcast.siteUrl) }}</link>
+      <link>{{ post.url | htmlBaseUrl(siteUrl) }}</link>
       <pubDate>{{ post.date | dateToRfc3339 }}</pubDate>
       {% if post.data.episode.seasonNumber -%}
       <itunes:season>{{ post.data.episode.seasonNumber }}</itunes:season>
       {%- endif %}
       <itunes:episode>{{ post.data.episode.episodeNumber }}</itunes:episode>
-      <itunes:summary>{{ post.content | striptags(true) | truncate(800) }}</itunes:summary>
-      <description>{{ post.content | striptags(true) | truncate(800) }}</description>
+      {% if podcast.feedEpisodeSummaryTemplate %}
+      {%- set episodeSummary -%}
+      {% include podcast.feedEpisodeSummaryTemplate %}
+      {%- endset -%}
+      {% else %}
+      {%- set episodeSummary = post.content | striptags(true) | truncate(500) -%}
+      {%- endif %}
+      <itunes:summary>{{ episodeSummary }}</itunes:summary>
+      {% if podcast.feedEpisodeDescriptionTemplate %}
+      {%- set episodeDescription -%}
+      {% include podcast.feedEpisodeDescriptionTemplate %}
+      {%- endset -%}
+      {% else %}
+      {%- set episodeDescription = post.content | striptags(true) | truncate(800) -%}
+      {%- endif %}
+      <description>{{ episodeDescription }}</description>
       {% if podcast.feedEpisodeContentTemplate %}
       {%- set episodeContent -%}
       {% include podcast.feedEpisodeContentTemplate %}
       {%- endset -%}
+      {% else %}
+      {%- set episodeContent = post.content -%}
+      {% endif %}
       <content:encoded>
-        <![CDATA[{{ episodeContent | renderTransforms(post.data.page, podcast.siteUrl) | safe | trim }}]]>
-      </content:encoded>
-      {%- else -%}
-      <content:encoded>
-        <![CDATA[{{ post.content | renderTransforms(post.data.page, podcast.siteUrl) | safe | trim }}]]>
+        <![CDATA[{{ episodeContent | renderTransforms(post.data.page, siteUrl) | safe | trim }}]]>
       </content:encoded>
-      {% endif %}
       <enclosure url="{{ post.data.episode.url }}" length="{{ post.data.episode.size }}" type="audio/mp3"></enclosure>
       <itunes:duration>{{ post.data.episode.duration | readableDuration }}</itunes:duration>
       {%- if post.data.guid != undefined %}
-      <guid isPermalink="false">{{ post.data.episode.guid }}</guid>
+      <guid isPermalink="false">{{ post.data.guid }}</guid>
       {% else %}
-      <guid isPermalink="true">{{ post.url | htmlBaseUrl(podcast.siteUrl) }}</guid>
+      <guid isPermalink="true">{{ post.url | htmlBaseUrl(siteUrl) }}</guid>
       {% endif -%}
       {%- if post.data.explicit != undefined %}
       <itunes:explicit>{{ post.data.explicit }}</itunes:explicit>