eleventy-plugin-podcaster 0.9.3 → 0.9.5

package/README.md

@@ -15,12 +15,12 @@ And then include the plugin in your Eleventy configuration file.
 ```js
 // eleventy.config.js
 
-import podcaster from 'eleventy-plugin-podcaster'
+import Podcaster from 'eleventy-plugin-podcaster'
 
 export default function (eleventyConfig) {
   .
   .
-  eleventyConfig.addPlugin(podcaster)
+  eleventyConfig.addPlugin(Podcaster)
   .
   .
 }

package/docs/README.md

@@ -25,12 +25,12 @@ And then include the plugin in your Eleventy configuration file.
 ```js
 // eleventy.config.js
 
-import podcaster from 'eleventy-plugin-podcaster'
+import Podcaster from 'eleventy-plugin-podcaster'
 
 export default function (eleventyConfig) {
   .
   .
-  eleventyConfig.addPlugin(podcaster)
+  eleventyConfig.addPlugin(Podcaster)
   .
   .
 }
@@ -57,7 +57,7 @@ Here's an example.
 
 ## Episode information
 
-For each podcast episode you create, you will also create a Eleventy template containing the information about it — the title, the release date, the episode number, the filename and so on. This template will have the tag `podcastEpisode`; its front matter will contain all of the information about the episode — title, release date, episode number and so on — and its content will contain the episode's show notes.
+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.
 

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

@@ -1,16 +1,16 @@
 # Optional features
 
-**Podcaster** includes some optional features which you might find useful for your podcasting website. These features are turned off by default, in case you want to implement them some other way. You can enable one or both of them when you include the plugin in your eleventy configuration file, like this:
+**Podcaster** includes some optional features which you might find useful for your podcasting website. These features are turned off by default, in case you want to implement them some other way. You can enable some or all of them when you include the plugin in your eleventy configuration file, like this:
 
 ```js
 // eleventy.config.js
 
-import podcasterPlugin from 'eleventy-plugin-podcaster'
+import Podcaster from 'eleventy-plugin-podcaster'
 
 export default function (eleventyConfig) {
   .
   .
-  eleventyConfig.addPlugin(podcasterPlugin, {
+  eleventyConfig.addPlugin(Podcaster, {
     handleDrafts: true,
     handleExcerpts: true,
     readableDateLocale: 'en-GB'
@@ -22,7 +22,7 @@ export default function (eleventyConfig) {
 
 ## Drafts
 
-If `handleDrafts` is set to `true`, the plugin will allow you to designate posts as drafts by including `draft: true` in their front matter (or elsewhere in the data cascade). By default, drafts will be included in the build when Eleventy is running in `serve` or `watch` mode, but will be excluded in `build` mode. You can override this default behaviour by setting the `BUILD_DRAFTS` environment variable to `true` or `false`.
+If `handleDrafts` is set to `true`, the plugin will allow you to designate posts as drafts by including `draft: true` in their front matter (or elsewhere in the data cascade). By default, drafts will be included in the build when Eleventy is running in `serve` or `watch` mode, but will be excluded in `build` mode. You can override this default behaviour by setting the `INCLUDE_DRAFTS` environment variable to `true` or `false`.
 
 ## Excerpts
 

package/docs/podcast-information.md

@@ -42,6 +42,8 @@ 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"
+  "feedEpisodeTitleTemplate": "feed-episode-title.njk"
 }
 ```
 
@@ -67,8 +69,29 @@ 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 |
+| `feedEpisodeTitleTemplate` | The name of an title template that will be used to create the title of each episode. The content of this template should be plain text. If it's omitted, the `title` of the episode's post will be used. | 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/docs/size-and-duration.md

@@ -26,12 +26,12 @@ During the build, **Podcaster** will use this JSON file behind the scenes to ret
 You can specify another folder for **Podcaster** to use when you include **Podcaster** in your configuration file by specifying a relative or absolute path like this.
 
 ```js
-import podcasterPlugin from 'eleventy-plugin-podcaster'
+import Podcaster from 'eleventy-plugin-podcaster'
 
 export default function (eleventyConfig) {
   .
   .
-  eleventyConfig.addPlugin(podcasterPlugin, {
+  eleventyConfig.addPlugin(Podcaster, {
     episodesDir: '~/episodes'
   })
   .
@@ -45,13 +45,13 @@ When you're building your site locally, you can easily point **Podcaster** at a
 
 But if you host your site on a Jamstack provider and it's building your site for you, it won't have access to a directory like that. (Your podcast files are too big to store in your repository.)
 
-So you can run your build locally first, and then commit the resulting `episodesData.json` file to your repository. If you do that, the build process on your host will use the information there to work our your episodes' size and duration.
+And so with **Podcaster** you can run your build locally first and then commit the resulting `episodesData.json` file to your repository. If you do that, the build process on your host will use the information in that file to work our the size and duration of your episodes.
 
 ## Skipping the process
 
-**Podcaster** will analyse your MP3 files only once during a `--serve` session. To get it to run the analysis again, you need to restart the web server.
+When Eleventy is running in `--serve` mode,**Podcaster** will analyse your MP3 files only once during a session. To get it to run the analysis again, you need to restart the web server.
 
-If you don't want to run the analysis process during a build, you can just set the environment variable `SKIP_EPISODE_CALCULATIONS` to `true`.
+If you don't want to run the analysis during a build, you can just set the environment variable `SKIP_EPISODE_CALCULATIONS` to `true`.
 
 ```sh
 SKIP_EPISODE_CALCULATIONS=true npx @11ty/eleventy --serve

package/package.json

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

package/src/drafts.js

@@ -4,9 +4,9 @@ export default (eleventyConfig, options = {}) => {
   let hasLoggedAboutDrafts = false
   eleventyConfig.addPreprocessor('drafts', 'md', (data, _content) => {
     let shouldIncludeDrafts = false
-    if (process.env.BUILD_DRAFTS === 'true') {
+    if (process.env.INCLUDE_DRAFTS === 'true') {
       shouldIncludeDrafts = true
-    } else if (process.env.BUILD_DRAFTS === 'false') {
+    } else if (process.env.INCLUDE_DRAFTS === 'false') {
       shouldIncludeDrafts = false
     } else {
       shouldIncludeDrafts = (process.env.ELEVENTY_RUN_MODE !== 'build')

package/src/podcastFeed.njk

@@ -45,13 +45,28 @@ eleventyAllowMissingExtension: true
     <generator>{{ eleventy.generator }}</generator>
     {% for post in collections.podcastEpisode | reverse %}
     <item>
-      <title>{{ post.data.title }}</title>
+      {% if podcast.feedEpisodeTitleTemplate %}
+      {%- set episodeTitle -%}
+      {% include podcast.feedEpisodeTitleTemplate %}
+      {%- endset -%}
+      {% else %}
+      {%- set episodeTitle = post.data.title -%}
+      {%- endif %}
+      <title>{{ episodeTitle }}</title>
       <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>
+      {% 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 %}
@@ -59,7 +74,6 @@ eleventyAllowMissingExtension: true
       {% else %}
       {%- set episodeDescription = post.content | striptags(true) | truncate(800) -%}
       {%- endif %}
-      <itunes:summary>{{ episodeDescription }}</itunes:summary>
       <description>{{ episodeDescription }}</description>
       {% if podcast.feedEpisodeContentTemplate %}
       {%- set episodeContent -%}
@@ -68,19 +82,13 @@ eleventyAllowMissingExtension: true
       {% else %}
       {%- set episodeContent = post.content -%}
       {% endif %}
-      {%- if post.data.page -%}
       <content:encoded>
         <![CDATA[{{ episodeContent | renderTransforms(post.data.page, siteUrl) | safe | trim }}]]>
       </content:encoded>
-      {%- else -%}
-      <content:encoded>
-        <![CDATA[{{ post.content | 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(siteUrl) }}</guid>
       {% endif -%}