eleventy-plugin-podcaster 0.9.0

package/LICENCE.txt

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright 2024 Nathan Bottomley
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+# eleventy-plugin-podcaster 🕚⚡️🎈🐀🎤📲
+
+`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.
+
+Plenty of services exist that will host your podcast online — [Spotify][], [Acast][], [Podbean][], [Buzzsprout][], [Blubrry][]. But none of these will allow you to own your podcast's presence on the web, and none of them will give you the freedom to create a site that presents your podcast in a way that reflects its premise, tone and style.
+
+But **Podcaster** will.
+
+[Spotify]: https://podcasters.spotify.com
+[Acast]: https://www.acast.com
+[Podbean]: https://www.podbean.com
+[Buzzsprout]: https://www.buzzsprout.com
+[Blubrry]: https://blubrry.com
+
+## Installation
+
+To install the npm package, type this at the command line:
+
+```shell
+npm install eleventy-plugin-podcaster
+```
+
+And then include the plugin in your Eleventy configuration file.
+
+```js
+// 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 all the information in your data directory in a `podcast.json` file.
+
+Here's an example.
+
+```json
+{
+  "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.](docs/podcast-information.md)
+
+## 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.
+
+Here's an example.
+
+```yaml
+---
+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.](docs/episode-information.md)
+
+## The podcast feed
+
+To create your podcast feed, **Podcaster** needs both the information you've provided about your podcast and the information you've provided about your individual episodes.
+
+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 are 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 could use this information to describe a single podcast episode in a Liquid template.
+
+```liquid
+<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][pagination]. In that case, each episode's  information will be available in its [collection item data structure][item].
+
+[pagination]: https://www.11ty.dev/docs/pagination/
+[item]: https://www.11ty.dev/docs/collections/#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`.
+
+## Hosting
+
+You can host your podcast site — along with its feed — [the same way you would host any Eleventy site][hosting], 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.
+
+[hosting]: https://www.11ty.dev/docs/deployment/
+[a Jamstack provider]: https://www.11ty.dev/docs/deployment/#jamstack-providers
+[a classic web host]: https://www.11ty.dev/docs/deployment/#classic-web-hosts
+
+However, your podcast episode files should probably be hosted somewhere else, preferably on a Content Delivery Network (CDN), which will let your listeners download your episodes promptly and quickly.
+
+There are many options available, including [Digital Ocean Spaces][], [Linode Object Storage][], [Backblaze B2 Cloud Storage][] and [Cloudflare R2][].
+
+[Digital Ocean Spaces]: https://www.digitalocean.com/products/spaces
+[Linode Object Storage]: https://www.linode.com/products/object-storage/
+[Backblaze B2 Cloud Storage]: https://www.backblaze.com/cloud-storage
+[Cloudflare R2]: https://developers.cloudflare.com/r2/
+
+To find out how to set this up and how to make this work with **Podcaster**, [read more about hosting your podcast episode files][episode-file-hosting].
+
+[episode-file-hosting]: docs/hosting.md
+
+## Optional features
+
+**Podcaster** also implements some optional features which are useful for creating podcast websites — **drafts** and **excerpts**.
+
+These are not fundamental features of a podcast website, which is why they are opt-in. You activate them by passing options to the `addPlugin` method in your configuration file.
+
+```js
+    eleventyConfig.addPlugin(podcaster, {
+      handleDrafts: true,
+      handleExcerpts: true
+    })
+```
+
+[Read more about optional features.](docs/optional-features.md)
+
+## 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 a list:
+
+- [Flight Through Entirety](https://flightthroughentirety.com), a _Doctor Who_ podcast flying through the entirety of the show's 60-something-year history.
+- [Untitled Star Trek Project](https://untitledstartrekproject.com), a _Star Trek_ commentary podcast, where two friends watch _Star Trek_ episodes from across the franchise, chosen (nearly) at random using [a page on the podcast website](https://untitledstartrekproject.com/randomiser).
+- [500 Year Diary](https://500yeardiary), another _Doctor Who_ podcast, where we look at the show's themes and ideas and some of the people involved in its creation.
+- [The Second Great and Bountiful Human Empire](https://thesecondgreatandbountifulhumanempire.com), a _Doctor Who_ flashcast, where we give our initial reactions to each episode of the post-2023 era of the show.
+- [Startling Barbara Bain](https://startlingbarbarabain), a commentary podcast on _Space: 1999_, a lavish and generally ridiculous British scifi show from the 1970s.
+- [Maximum Power](https://maximumpowerpodcast.com), a podcast about _Blakes 7_, a less lavish but more ridiculous British scifi show from the 1970s.
+- [Bondfinger](https://bondfinger.com), a James Bond commentary podcast that soon ran out of James Bond films and ended up spending its time drinking and watching terrible TV shows from the 1960s.
+
+## Licence
+
+This plugin is available as open source under the terms of the [ISC License](https://opensource.org/licenses/ISC).

package/docs/episode-information.md

@@ -0,0 +1,54 @@
+# Episode information
+
+Each episode of your podcast should have an associated Eleventy template, with a `podcastEpisode` tag. The front matter of this template will contain the necessary information about the episode, and the content of the template will be the show notes.
+
+## Front matter
+
+The important information about each of your podcast episodes — the title, the date, the filename, the episode number, the size, the duration — should be made available in an `episode` object in the front matter of a post with an `podcastEpisode` tag, like this:
+
+```yaml
+---
+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
+  duration: 3283
+  explicit: no
+  episodeType: full
+excerpt: >-
+  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_.
+---
+```
+
+Here's a detailed description of the data you need to provide here.
+
+| field | value | required? |
+| ----- | ----- | ----- |
+| `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 |
+| `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 |
+| `episode.size` | The size of the episode's audio file in bytes. | yes |
+| `episode.duration` | The duration of the episode as a number of seconds. You can convert this to `h:mm:ss` format using Podcaster's `readableDuration` filter. | yes |
+| `episode.explicit` | Warns listeners that this episode contains explicit language. Should be used for a single episode in a podcast that isn't itself marked as explicit. | no |
+| `episode.type` | The type of episode. Defaults to `full`, meaning a full episode of the podcast. Other valid types are `trailer` and `bonus`. | no |
+| `excerpt` | A shorter version of the content of the post, written in Markdown. For use in lists of episodes where the show notes are long. For other ways of providing excerpts to **Podcaster**, check out its [optional excerpts feature][excerpts]. | no |
+
+[excerpts]: /docs/optional-features.md#excerpts
+
+> [!TIP]
+> It's possible for **Podcaster** to calculate the size and duration for each episode if it has access to your episode audio files. [Read more to find out how](docs/size-and-duration.md).
+
+> [!TIP]
+> It's also possible for **Podcaster** to automatically create an `excerpt` for each episode. [Read more to find out how](/docs/optional-features.md#excerpts).

package/docs/hosting.md

@@ -0,0 +1,20 @@
+# Hosting your podcast episode files
+
+As it says in [README.md](README.md), you should probably host your podcast files separately from your website. I host my podcast episode files in [Digital Ocean Spaces][], which is inexpensive and not particularly difficult to set up. But there are many other options available, including [Linode Object Storage][], [Backblaze B2 Cloud Storage][] and [Cloudflare R2][].
+
+[Digital Ocean Spaces]: https://www.digitalocean.com/products/spaces
+[Linode Object Storage]: https://www.linode.com/products/object-storage/
+[Backblaze B2 Cloud Storage]: https://www.backblaze.com/cloud-storage
+[Cloudflare R2]: https://developers.cloudflare.com/r2/
+
+Your CDN host will assign URLs to each of your podcast episodes: you will tell  **Podcaster** about these URLs by defining `podcast.episodeUrlBase` as the base URL for all of your podcast episodes, like this: `https://example-podcast.sfo3.digitaloceanspaces.com`. You will provide the filename for each episode as `episode.filename`.
+
+To deploy your episodes to your CDN host, you can write an NPM script using [`rclone`][rclone], `rsync` or `s3cmd`, depending on your setup.
+
+[rclone]: https://rclone.org
+
+Here's the script that I use to deploy the episodes for one of my sites to a DigitalOcean Space.
+
+```sh
+rclone sync episodes/ digitalocean:startlingbarbarabain -P --exclude .DS_Store
+```

package/docs/optional-features.md

@@ -0,0 +1,36 @@
+# 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:
+
+```js
+// eleventy.config.js
+
+import podcasterPlugin from 'eleventy-plugin-podcaster'
+
+export default function (eleventyConfig) {
+  .
+  .
+  eleventyConfig.addPlugin(podcasterPlugin, {
+    handleDrafts: true,
+    handleExcerpts: true
+  })
+  .
+  .
+}
+```
+
+## 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`.
+
+## Excerpts
+
+If `handleExcerpts` is set to `true`, the plugin will create excerpts for your podcast episode posts. Excerpts are shortened versions of your final content, which you can use on index pages or topic pages or guest pages instead of your complete post.
+
+Excerpts are available in a template as `{{ excerpt }}`, but you will probably access them from a collection item, where they are available as `{{ item.data.excerpt }}`. Excerpts are HTML fragments.
+
+**Podcaster** defines the excerpt in one of three ways, in order of priority.
+
+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.)

package/docs/podcast-information.md

@@ -0,0 +1,74 @@
+# Podcast information
+
+The important information about your podcast — the title, the owner, the category, the subcategory and so on — should be made available as fields in a `podcast` object in the data cascade. The easiest way to do this is to put all the required information in your data directory in a `podcast.json` file, like this:
+
+```json
+{
+  "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",
+}
+```
+
+---
+
+However, `eleventy-plugin-podcast` is quite customisable. He's another `podcast.json` file, with all of the valid fields included.
+
+```json
+{
+  "feedPath": "/podcast.xml",
+  "title": "Flight Through Entirety: A Doctor Who Podcast",
+  "subtitle": "Flying through the entirety of Doctor Who",
+  "summary": "Flying through the entirety of Doctor Who. Originally with cake,but now with guests.",
+  "description": "Flying through the entirety of Doctor Who. Originally with cake, but now with guests.",
+  "siteUrl": "https://flightthroughentirety.com",
+  "owner": {
+    "name": "Nathan Bottomley",
+    "email": "nathan@example.com"
+  },
+  "author": "Flight Through Entirety",
+  "category": "TV & Film",
+  "subcategory": "TV Reviews",
+  "imagePath": "/assets/images/podcast-logo.jpg",
+  "explicit": false,
+  "type": "episodic",
+  "complete": "no",
+  "language": "en-AU",
+  "copyright": "Flight Through Entirety",
+  "startingYear": 2014,
+  "episodeUrlBase": "https://example.fte-cdn.com/",
+  "feedEpisodeContentTemplate": "feed-episode-content.njk",
+  "feedEpisodeDescriptionTemplate": "feed-episode-description.njk"
+}
+```
+
+And here's a detailed description of all of this information.
+
+| field | value | required? |
+| ----- | ----- | --------- |
+| `feedPath` | The path where the podcast feed will be located. Defaults to `/feed/podcast.xml`. | no |
+| `title` | The title of your podcast. | yes |
+| `subtitle` | A short description of your podcast. If you omit this the `description` field will be used instead. | no |
+| `summary` | A description of your podcast. If you omit this the `description` field will be used instead. | no |
+| `description` | A short description of your podcast. The most popular podcast applications prominently display this information. | yes |
+| `siteUrl` | The URL of your podcast website. The most popular podcast applications use this to provide a link to your website. It's also used by this plugin to convert relative links to absolute links in your feed. (If `podcast.siteUrl` isn't provided, the feed template will use `site.url` instead.) | yes |
+| `owner` | An optional object in the form `{ name, email }` You might want to omit this: Apple Podcasts has deprecated it, and an email in a podcast feed will attract some spam. However, some podcast directories, like Castbox, will use the email address to identify you when you try to claim ownership of a podcast in their directory. | no |
+| `author` | The creator or creators of the podcast. The most popular podcast applications prominently display this information. | yes |
+| `category` | The category for the podcast. Describes he kind of show it is. Valid categories are listed in [this Apple support document][categories]. Used by podcast directories to help listeners find the podcast. | yes |
+| `subcategory` | The subcategory for the podcast. Valid subcategories are also listed in [the Apple support document][categories]. | no |
+| `imagePath` | The path to your podcast logo, which should be a JPEG or PNG file 3000 × 3000 pixels in size. (You can find more detailed specifications in [this Apple support document](https://podcasters.apple.com/support/896-artwork-requirements#shows)). Defaults to `/img/podcast-logo.jpg`. | yes |
+| `explicit` | Warns listeners that your podcast contains explicit language. In Apple Podcasts, if you include this with the value `true`, your podcast and its episodes will be badged with an 🄴 to indicate that they use explicit language. Some of the most popular podcast applications ignore this field. | no |
+| `type` | Two possible values: `episodic` and `serial`. Defaults to `episodic`, which means that the podcast can be listened to in no particular order. Narrative podcasts (like _Serial_) should be marked as `serial`. | no |
+| `complete` | Indicates that a podcast is complete and that no new episodes should be expected, in which case it should have the value `true`. Should be omitted otherwise. | no |
+| `language` | A code that specifies the language of the feed (rather than the podcast). You can find [a list of permissible codes][lang] at the RSS Advisory Board's website. | yes |
+| `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

package/docs/size-and-duration.md

@@ -0,0 +1,58 @@
+# Size and duration
+
+The simplest way of telling **Podcaster** the size and duration of your podcast episode files is by including that information in the front matter of each episode's post, like this:
+
+```yaml
+episode:
+  size: 61231442 # bytes
+  duration: 3778.482 # seconds
+```
+
+However, you can also get **Podcaster** to analyses your podcast's episode files and find that information for you.
+
+To do this, you need a directory which contains all of your podcast's episode files. **Podcaster** assumes that this is an `episodes` folder at the top level of your project. If it finds the folder, it will analyse all of its `.mp3` files, find their size and duration, and save that information in a JSON file called `episodesData.json` in your project's data directory.
+
+```json
+{
+  "500YD S1E1, Entering a New Phase (The Power of the Daleks).mp3": {
+    "size": 61231442,
+    "duration": 3778.482
+  }
+}
+```
+
+During the build, **Podcaster** will use this JSON file behind the scenes to retrieve `episode.size` and `episode.duration`, both in the podcast feed and in your templates, using the filename you have provided as `episode.filename`.
+
+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'
+
+export default function (eleventyConfig) {
+  .
+  .
+  eleventyConfig.addPlugin(podcasterPlugin, {
+    episodesDir: '~/episodes'
+  })
+  .
+  .
+}
+```
+
+## Why `episodesData.json`?
+
+When you're building your site locally, you can easily point **Podcaster** at a local directory full of your podcast's episode files and then run your build.
+
+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.
+
+## 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.
+
+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`.
+
+```sh
+SKIP_EPISODE_CALCULATIONS=true npx @11ty/eleventy --serve
+```

package/eleventy.config.js

@@ -0,0 +1,91 @@
+import { DateTime, Duration } from 'luxon'
+import hr from '@tsmx/human-readable'
+import rssPlugin from '@11ty/eleventy-plugin-rss'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import calculateSizeAndDuration from './src/calculateSizeAndDuration.js'
+import excerpts from './src/excerpts.js'
+import drafts from './src/drafts.js'
+
+export default function (eleventyConfig, options = {}) {
+  if (!('addTemplate' in eleventyConfig)) {
+    console.log('[eleventy-plugin-podcasting] WARN Eleventy plugin compatibility: Virtual Templates are required for this plugin — please use Eleventy v3.0 or newer.')
+  }
+
+  eleventyConfig.addPlugin(rssPlugin, {
+    posthtmlRenderOptions: {
+      closingSingleTag: 'default' // opt-out of <img/>-style XHTML single tags
+    }
+  })
+
+  eleventyConfig.addGlobalData('eleventyComputed.podcast.feedPath', () => {
+    return data => data.podcast.feedPath || '/feed/podcast.xml'
+  })
+
+  eleventyConfig.addGlobalData('eleventyComputed.podcast.imagePath', () => {
+    return data => data.podcast.imagePath || '/img/podcast-logo.jpg'
+  })
+
+  eleventyConfig.addGlobalData('eleventyComputed.podcast.copyrightNotice', () => {
+    return data => {
+      const thisYear = DateTime.now().year
+      let yearRange
+      if (!data.podcast.startingYear || data.podcast.startingYear === thisYear) {
+        yearRange = thisYear
+      } else {
+        yearRange = `${data.podcast.startingYear}–${thisYear}`
+      }
+      return `© ${yearRange} ${data.podcast.copyright || data.podcast.author}`
+    }
+  })
+
+  eleventyConfig.addGlobalData(
+    'podcast.feedLastBuildDate',
+    DateTime.now().toRFC2822()
+  )
+
+  eleventyConfig.addGlobalData('eleventyComputed.episode.url', () => {
+    return data => {
+      if (!data.tags?.includes('podcastEpisode')) return
+
+      const episodeUrlBase = data.podcast.episodeUrlBase
+      const filename = data.episode.filename
+      return new URL(filename, episodeUrlBase).toString()
+    }
+  })
+
+  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'
+    })
+    return result.setLocale('en-GB').toLocaleString(DateTime.DATE_HUGE)
+  })
+
+  eleventyConfig.addFilter('readableDuration', function (seconds) {
+    if (!seconds) return '0:00:00'
+
+    return Duration.fromMillis(seconds * 1000).toFormat('h:mm:ss')
+  })
+
+  eleventyConfig.addFilter('readableSize', bytes =>
+    hr.fromBytes(bytes)
+  )
+
+  const podcastFeedPath = path.join(import.meta.dirname, './src/podcastFeed.njk')
+
+  eleventyConfig.addTemplate('feed.njk', readFileSync(podcastFeedPath), {
+    eleventyExcludeFromCollections: true,
+    eleventyImport: {
+      collections: ['podcastEpisode']
+    }
+  })
+
+  eleventyConfig.addPlugin(calculateSizeAndDuration, options)
+  eleventyConfig.addPlugin(excerpts, options)
+  eleventyConfig.addPlugin(drafts, options)
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "eleventy-plugin-podcaster",
+  "version": "0.9.0",
+  "description": "An Eleventy plugin that allows you to create a podcast and its accompanying website",
+  "main": "eleventy.config.js",
+  "exports": {
+    ".": "./eleventy.config.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "ava"
+  },
+  "keywords": [
+    "eleventy",
+    "eleventy-plugin",
+    "podcast",
+    "podcasting",
+    "rss"
+  ],
+  "author": "Nathan Bottomley",
+  "license": "ISC",
+  "dependencies": {
+    "@11ty/eleventy": "^3.0.0",
+    "@11ty/eleventy-plugin-rss": "^2.0.1",
+    "@tsmx/human-readable": "^2.0.3",
+    "chalk": "^5.3.0",
+    "dom-serializer": "^2.0.0",
+    "htmlparser2": "^9.1.0",
+    "luxon": "^3.4.4",
+    "markdown-it": "^14.1.0",
+    "mp3-duration": "^1.1.0"
+  },
+  "devDependencies": {
+    "ava": "^6.1.3",
+    "fast-xml-parser": "^4.4.0",
+    "neostandard": "^0.11.4"
+  }
+}

package/src/calculateSizeAndDuration.js

@@ -0,0 +1,70 @@
+import { Duration } from 'luxon'
+import path from 'node:path'
+import { existsSync } from 'node:fs'
+import { readdir, stat, readFile, writeFile } from 'node:fs/promises'
+import mp3Duration from 'mp3-duration'
+import hr from '@tsmx/human-readable'
+import chalk from 'chalk'
+
+const convertSecondsToReadableDuration = seconds =>
+  Duration.fromMillis(seconds * 1000)
+    .toFormat("d 'd' h 'h' m 'm' s.SSS 's'")
+
+export default function (eleventyConfig, options = {}) {
+  let firstRun = true
+  eleventyConfig.on('eleventy.before', async ({ dir, directories }) => {
+    // don't keep recalculating episode data in serve mode
+    if (!firstRun || process.env.SKIP_EPISODE_CALCULATIONS === 'true') return
+    firstRun = false
+
+    const episodesDir = path.join(process.cwd(), options.episodesDir || 'episodes')
+    if (!existsSync(episodesDir)) return
+
+    const episodes = await readdir(episodesDir)
+    const episodesData = {}
+    let totalEpisodes = 0
+    let totalSize = 0
+    let totalDuration = 0
+
+    for (const episode of episodes) {
+      if (!episode.endsWith('.mp3')) continue
+
+      totalEpisodes++
+      const episodePath = path.join(episodesDir, episode)
+      const episodeSize = (await stat(episodePath)).size
+      totalSize += episodeSize
+      const buffer = await readFile(episodePath)
+      const episodeDuration = await mp3Duration(buffer)
+      totalDuration += episodeDuration
+      episodesData[episode] = {
+        size: episodeSize,
+        duration: episodeDuration
+      }
+    }
+
+    const dataDir = path.join(process.cwd(), directories.data)
+    await writeFile(path.join(dataDir, 'episodesData.json'), JSON.stringify(episodesData, null, 2))
+
+    console.log(chalk.yellow(`${totalEpisodes} episodes; ${hr.fromBytes(totalSize)}; ${convertSecondsToReadableDuration(totalDuration)}.`))
+  })
+
+  eleventyConfig.addGlobalData('eleventyComputed.episode.size', () => {
+    return data => {
+      if (data.episode.size) return data.episode.size
+
+      if (data.tags?.includes('podcastEpisode') && data.episodesData) {
+        return data.episodesData[data.episode.filename]?.size
+      }
+    }
+  })
+
+  eleventyConfig.addGlobalData('eleventyComputed.episode.duration', () => {
+    return data => {
+      if (data.episode.duration) return data.episode.duration
+
+      if (data.tags?.includes('podcastEpisode') && data.episodesData) {
+        return data.episodesData[data.episode.filename]?.duration
+      }
+    }
+  })
+}

package/src/drafts.js

@@ -0,0 +1,26 @@
+export default (eleventyConfig, options = {}) => {
+  if (!options.handleDrafts) return
+
+  let hasLoggedAboutDrafts = false
+  eleventyConfig.addPreprocessor('drafts', 'md', (data, _content) => {
+    let shouldIncludeDrafts = false
+    if (process.env.BUILD_DRAFTS === 'true') {
+      shouldIncludeDrafts = true
+    } else if (process.env.BUILD_DRAFTS === 'false') {
+      shouldIncludeDrafts = false
+    } else {
+      shouldIncludeDrafts = (process.env.ELEVENTY_RUN_MODE !== 'build')
+    }
+    if (!hasLoggedAboutDrafts) {
+      if (shouldIncludeDrafts) {
+        console.log('Including drafts.')
+      } else {
+        console.log('Excluding drafts.')
+      }
+      hasLoggedAboutDrafts = true
+    }
+    if (data.draft && !shouldIncludeDrafts) {
+      return false
+    }
+  })
+}

package/src/excerpts.js

@@ -0,0 +1,43 @@
+import * as htmlparser2 from 'htmlparser2'
+import render from 'dom-serializer'
+import markdownIt from 'markdown-it'
+
+export default function (eleventyConfig, options = {}) {
+  eleventyConfig.addGlobalData('eleventyComputed.excerpt', () => {
+    if (!options.handleExcerpts) return
+
+    return (data) => {
+      if (!data.tags?.includes('podcastEpisode')) return
+
+      const md = markdownIt()
+
+      // If an excerpt is set in front matter, use it
+      if (data.excerpt) {
+        return md.render(data.excerpt)
+      }
+
+      const content = data.page.rawInput
+      const contentIsMarkdown = data.page.templateSyntax.includes('md')
+
+      // If an excerpt is set using comment delimiters, use it
+      const excerptPattern = /<!---excerpt-->\s*(.*?)\s*<!---endexcerpt-->/
+      const match = excerptPattern.exec(content)
+      if (match && contentIsMarkdown) {
+        return md.render(match[1])
+      } else if (match) {
+        return match[1]
+      }
+
+      // If an excerpt is not set, use the first paragraph not in a blockquote
+      let htmlContent
+      if (data.page.templateSyntax.includes('md')) {
+        htmlContent = md.render(content)
+      } // otherwise it's already HTML
+      const dom = htmlparser2.parseDocument(htmlContent)
+      const paragraph = dom.children.find(item => item.type === 'tag' && item.name === 'p')
+      if (paragraph) {
+        return render(paragraph)
+      }
+    }
+  })
+}

package/src/podcastFeed.njk

@@ -0,0 +1,85 @@
+---
+permalink: "{{ podcast.feedPath or '/feed/podcast.xml' }}"
+eleventyAllowMissingExtension: true
+---
+{%- set siteUrl %}{{ podcast.siteUrl or site.url }}{% endset -%}
+<?xml version="1.0" encoding="utf-8"?>
+<rss version="2.0"
+  xmlns:atom="http://www.w3.org/2005/Atom"
+  xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd"
+  xmlns:content="http://purl.org/rss/1.0/modules/content/"
+  >
+  <channel>
+    <title>{{ podcast.title }}</title>
+    <itunes:subtitle>{{ podcast.subtitle or podcast.description }}</itunes:subtitle>
+    <description>{{ podcast.description }}</description>
+    <link>{{ siteUrl }}</link>
+    <atom:link href="{{ podcast.feedPath | htmlBaseUrl(siteUrl) }}" rel="self" type="application/rss+xml" />
+    {%- if podcast.owner %}
+    <itunes:owner>
+      <itunes:name>{{ podcast.owner.name }}</itunes:name>
+      <itunes:email>{{ podcast.owner.email }}</itunes:email>
+    </itunes:owner>
+    {%- endif %}
+    <itunes:author>{{ podcast.author }}</itunes:author>
+    {%- if podcast.subcategory %}
+    <itunes:category text="{{ podcast.category }}">
+      <itunes:category text="{{ podcast.subcategory }}" />
+    </itunes:category>
+    {%- else %}
+    <itunes:category text="{{ podcast.category }}" />
+    {%- endif %}
+    <itunes:image href="{{ podcast.imagePath | htmlBaseUrl(podcast.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 %}
+    <itunes:type>{{ podcast.type }}</itunes:type>
+    {%- endif %}
+    {%- if podcast.complete %}
+    <itunes:complete>yes</itunes:complete>
+    {%- endif %}
+    <language>{{ podcast.language }}</language>
+    <copyright>{{ podcast.copyrightNotice }}</copyright>
+    <pubDate>{{ collections.podcastEpisode | getNewestCollectionItemDate | dateToRfc3339 }}</pubDate>
+    <lastBuildDate>{{ podcast.feedLastBuildDate }}</lastBuildDate>
+    <generator>{{ eleventy.generator }}</generator>
+    {% for post in collections.podcastEpisode | reverse %}
+    <item>
+      <title>{{ post.data.title }}</title>
+      <link>{{ post.url | htmlBaseUrl(podcast.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.feedEpisodeContentTemplate %}
+      {%- set episodeContent -%}
+      {% include podcast.feedEpisodeContentTemplate %}
+      {%- endset -%}
+      <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 }}]]>
+      </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>
+      {% else %}
+      <guid isPermalink="true">{{ post.url | htmlBaseUrl(podcast.siteUrl) }}</guid>
+      {% endif -%}
+      {%- if post.data.explicit != undefined %}
+      <itunes:explicit>{{ post.data.explicit }}</itunes:explicit>
+      {% endif -%}
+      {%- if post.data.type != undefined %}
+      <itunes:episodeType>{{ post.data.episodeType }}</itunes:episodeType>
+      {% endif -%}
+    </item>
+    {% endfor -%}
+  </channel>
+</rss>