eleventy-plugin-podcaster 2.0.0-alpha.3 → 2.0.0-alpha.5

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "overrides": [
+    {
+      "files": ["*.jsonc"],
+      "options": {
+        "parser": "json",
+        "trailingComma": "none"
+      }
+    }
+  ]
+}

package/README.md

@@ -1,6 +1,9 @@
 # eleventy-plugin-podcaster 🕚⚡️🎈🐀🎤📲
 
-`eleventy-plugin-podcaster` — or **Podcaster**, as we will call it from now on — is an Eleventy plugin which lets you 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.
+`eleventy-plugin-podcaster` — or **Podcaster**, as we will call it from now on — is an Eleventy plugin which lets you create a podcast and its accompanying website.
+
+- **Podcaster** creates the podcast feed that you submit to Apple Podcasts, Spotify or any other podcast directory.
+- **Podcaster** also provides information about your podcast to your Eleventy templates. This means that you can describe the podcast and its episodes on your podcast 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.
 
@@ -44,9 +47,9 @@ Detailed and specific information about how to install and use **Podcaster** can
 
 1. **Podcaster** is an Eleventy plugin. Create an Eleventy site and install the `eleventy-plugin-podcaster` plugin in the usual way.
 2. In the data directory, create a `podcast.json` file. This will contain information about your podcast and its site — at the very least, its title, the URL of the site, a description, its language, and its category.
-3. In the input directory, create a `episodeFiles` directory and put your podcast MP3s in there.
-4. In the input directory, create a `episodePosts` directory. You will have a post for each episode, and that post will include information about the episode in its filename and front matter and will have as its content the episode description or show notes.
-5. Create pages on your site for each of your episodes using the posts in the `episodePosts` directory. You can also create index pages, topic pages, guest pages or anything you like, using the information you have supplied to **Podcaster**.
+3. In the input directory, create an `episode-files` directory and put your podcast MP3s in there.
+4. In the input directory, create an `episode-posts` directory. Here you will create a post for each episode, which will include information about the episode in its filename and front matter and which whill contain the episode description or show notes.
+5. Create pages on your site for each of your episodes using the posts in the `episode-posts` directory. And you can also create index pages, topic pages, guest pages or anything you like — all using the information you have supplied to **Podcaster** in your `podcast.json` file and your episode posts.
 6. Find a host for your site, and a CDN for your podcast episodes.
 
 > [!WARNING]

package/eleventy.config.js

@@ -1,3 +1,5 @@
+import path from 'node:path'
+
 import podcastFeed from './src/podcastFeed.js'
 import podcastData from './src/podcastData.js'
 import episodeData from './src/episodeData.js'
@@ -5,11 +7,17 @@ import calculateEpisodeSizeAndDuration from './src/calculateEpisodeSizeAndDurati
 import calculateEpisodeFilename from './src/calculateEpisodeFilename.js'
 
 import readableFilters from './src/readableFilters.js'
+import chapters from './src/chapters.js'
 import excerpts from './src/excerpts.js'
 import drafts from './src/drafts.js'
 import pageTitle from './src/pageTitle.js'
 
 export default function (eleventyConfig, options = {}) {
+  const episodePostsDirectory = options.episodePostsDirectory ?? 'episode-posts'
+  options.episodePostsDirectory = path.join(eleventyConfig.directories.input, episodePostsDirectory)
+  const episodeFilesDirectory = options.episodeFilesDirectory ?? 'episode-files'
+  options.episodeFilesDirectory = path.join(eleventyConfig.directories.input, episodeFilesDirectory)
+
   eleventyConfig.addPlugin(podcastFeed, options)
   eleventyConfig.addPlugin(podcastData, options)
   eleventyConfig.addPlugin(episodeData, options)
@@ -19,6 +27,7 @@ export default function (eleventyConfig, options = {}) {
   // Filters
 
   eleventyConfig.addPlugin(readableFilters, options)
+  eleventyConfig.addPlugin(chapters, options)
 
   // Optional features
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-podcaster",
-  "version": "2.0.0-alpha.3",
+  "version": "2.0.0-alpha.5",
   "description": "An Eleventy plugin that allows you to create a podcast and its accompanying website",
   "main": "eleventy.config.js",
   "exports": {
@@ -32,7 +32,6 @@
     "@11ty/eleventy-plugin-rss": "^2.0.1",
     "@aws-sdk/client-s3": "^3.862.0",
     "@tsmx/human-readable": "^2.0.3",
-    "chalk": "^5.3.0",
     "dom-serializer": "^2.0.0",
     "htmlparser2": "^9.1.0",
     "luxon": "^3.4.4",

package/src/calculateEpisodeFilename.js

@@ -1,7 +1,9 @@
+import isEpisodePost from './isEpisodePost.js'
+
 function findMatchingFilename (episodeData, thisEpisode) {
   const filenameSeasonAndEpisodePattern =
-    /^.*?\b[sS](?<seasonNumber>\d+)\s*[eE](?<episodeNumber>\d+)\b.*\.mp3$/
-  const filenameEpisodePattern = /^.*?\b(?<episodeNumber>\d+)\b.*\.mp3$/
+    /^.*?\b[sS](?<seasonNumber>\d+)\s*[eE](?<episodeNumber>\d+)\b.*\.(mp3|m4a)$/
+  const filenameEpisodePattern = /^.*?\b(?<episodeNumber>\d+)\b.*\.(mp3|m4a)$/
   const { seasonNumber, episodeNumber } = thisEpisode
 
   for (const file of Object.keys(episodeData)) {
@@ -27,11 +29,11 @@ function findMatchingFilename (episodeData, thisEpisode) {
   }
 }
 
-export default function (eleventyConfig, _options) {
+export default function (eleventyConfig, options) {
   eleventyConfig.addGlobalData('eleventyComputed.episode.filename', () => {
     return data => {
       if (data.episode.filename) return data.episode.filename
-      if (!data.page.inputPath.includes('/episodePosts/')) return
+      if (!isEpisodePost(data, options)) return
 
       return findMatchingFilename(data.episodeData, data.episode)
     }

package/src/calculateEpisodeSizeAndDuration.js

@@ -1,4 +1,5 @@
-import { Duration, DateTime } from 'luxon'
+import { DateTime } from 'luxon'
+import readableDuration from './readableDuration.js'
 import path from 'node:path'
 import { existsSync } from 'node:fs'
 import { readdir, stat, writeFile } from 'node:fs/promises'
@@ -6,36 +7,16 @@ import { Writable } from 'node:stream'
 import { S3Client, ListObjectsCommand, GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3'
 import { parseFile as parseFileMetadata, parseBuffer as parseBufferMetadata } from 'music-metadata'
 import hr from '@tsmx/human-readable'
-import chalk from 'chalk'
+import isEpisodePost from './isEpisodePost.js'
 
-const convertSecondsToReadableDuration = seconds =>
-  Duration.fromMillis(seconds * 1000)
-    .shiftTo('days', 'hours', 'minutes', 'seconds')
-    .toHuman()
-
-const convertReadableDurationToSeconds = duration => {
-  const durationPattern = /^(?:(?<hours>\d+):)?(?<minutes>\d{1,2}):(?<seconds>\d{2}(?:\.\d+)?)$/
-
-  let match
-  if (duration?.match) {
-    match = duration.match(durationPattern)
-  }
-
-  if (match) {
-    const hours = isNaN(parseInt(match.groups.hours))
-      ? 0
-      : parseInt(match.groups.hours)
-    const minutes = parseInt(match.groups.minutes)
-    const seconds = parseFloat(match.groups.seconds)
-    return hours * 3600 + minutes * 60 + seconds
-  }
-}
+const isAudioFile = episodeFilename => episodeFilename.endsWith('.mp3') ||
+                    episodeFilename.endsWith('.m4a')
 
 async function readEpisodeDataLocally (episodeFilesDirectory) {
   const episodes = await readdir(episodeFilesDirectory)
   const episodeData = {}
   for (const episode of episodes) {
-    if (!episode.endsWith('.mp3')) continue
+    if (!isAudioFile(episode)) continue
 
     const episodePath = path.join(episodeFilesDirectory, episode)
     const episodeSize = (await stat(episodePath)).size
@@ -59,7 +40,7 @@ function calculatePodcastData (episodeData) {
 
 function reportPodcastData (podcastData) {
   const { numberOfEpisodes, totalSize, totalDuration } = podcastData
-  console.log(chalk.yellow(`${numberOfEpisodes} episodes; ${hr.fromBytes(totalSize)}; ${convertSecondsToReadableDuration(totalDuration)}.`))
+  console.log(`\u001b[33m${numberOfEpisodes} episodes; ${hr.fromBytes(totalSize)}; ${readableDuration.convertFromSeconds(totalDuration)}.\u001b[0m`)
 }
 
 async function writePodcastDataLocally (episodeData, podcastData, directories) {
@@ -130,7 +111,7 @@ async function updateEpisodeDataFromS3Bucket (s3Client, s3Bucket) {
   const list = await s3Client.send(new ListObjectsCommand({ Bucket: s3Bucket }))
   const result = { ...storedEpisodeData.episodeData }
   for (const item of list.Contents ?? []) {
-    if (!item.Key.endsWith('.mp3')) continue
+    if (!isAudioFile(item.Key)) continue
 
     const { Key: filename, Size: size, LastModified: lastModified } = item
 
@@ -161,9 +142,10 @@ export default function (eleventyConfig, options = {}) {
   let firstRun = true
   eleventyConfig.on('eleventy.before', async ({ directories }) => {
     if (!firstRun || process.env.SKIP_EPISODE_CALCULATIONS === 'true') return
+
     firstRun = false
 
-    const episodeFilesDirectory = path.join(directories.input, 'episodeFiles')
+    const episodeFilesDirectory = options.episodeFilesDirectory
     let episodeData
     if (existsSync(episodeFilesDirectory)) {
       episodeData = await readEpisodeDataLocally(episodeFilesDirectory)
@@ -183,7 +165,7 @@ export default function (eleventyConfig, options = {}) {
   eleventyConfig.addGlobalData('eleventyComputed.episode.size', () => {
     return data => {
       if (data.episode.size) return data.episode.size
-      if (data.page.inputPath.includes('/episodePosts/') && data.episodeData) {
+      if (isEpisodePost(data, options) && data.episodeData) {
         return data.episodeData[data.episode.filename]?.size
       }
     }
@@ -192,11 +174,11 @@ export default function (eleventyConfig, options = {}) {
   eleventyConfig.addGlobalData('eleventyComputed.episode.duration', () => {
     return data => {
       if (data.episode.duration) {
-        const convertedReadableDuration = convertReadableDurationToSeconds(data.episode.duration)
+        const convertedReadableDuration = readableDuration.convertToSeconds(data.episode.duration)
         return convertedReadableDuration ?? data.episode.duration
       }
 
-      if (data.page.inputPath.includes('/episodePosts/') && data.episodeData) {
+      if (isEpisodePost(data, options) && data.episodeData) {
         return data.episodeData[data.episode.filename]?.duration
       }
     }

package/src/chapters.js

@@ -0,0 +1,13 @@
+import readableDuration from './readableDuration.js'
+
+export default (eleventyConfig, options = {}) => {
+  eleventyConfig.addFilter('normalizeChaptersData', (data) => {
+    const result = data.map(x => {
+      if (x.startTime) {
+        x.startTime = readableDuration.convertToSeconds(x.startTime) ?? x.startTime
+      }
+      return x
+    })
+    return JSON.stringify(result, null, 2)
+  })
+}

package/src/chapters.njk

@@ -0,0 +1,9 @@
+---
+pagination:
+  data: collections.episodePostWithChapters
+  size: 1
+  alias: episodePost
+permalink: "{{ episodePost.page.url }}/chapters.json"
+---
+
+{{ episodePost.data.episode.chapters | normalizeChaptersData | safe }}

package/src/episodeData.js

@@ -1,3 +1,5 @@
+import isEpisodePost from './isEpisodePost.js'
+
 export default function (eleventyConfig, options = {}) {
   const postFilenameSeasonAndEpisodePattern =
     /^[sS](?<seasonNumber>\d+)[eE](?<episodeNumber>\d+)/i
@@ -7,7 +9,7 @@ export default function (eleventyConfig, options = {}) {
     return data => {
       if (data.episode?.seasonNumber) return data.episode.seasonNumber
 
-      if (!data.page.inputPath.includes('/episodePosts/')) return
+      if (!isEpisodePost(data, options)) return
 
       const seasonAndEpisodeMatch = data.page.fileSlug.match(postFilenameSeasonAndEpisodePattern)
       if (seasonAndEpisodeMatch) {
@@ -20,7 +22,7 @@ export default function (eleventyConfig, options = {}) {
     return data => {
       if (data.episode?.episodeNumber) return data.episode.episodeNumber
 
-      if (!data.page.inputPath.includes('/episodePosts/')) return
+      if (!isEpisodePost(data, options)) return
 
       const seasonAndEpisodeMatch = data.page.fileSlug.match(postFilenameSeasonAndEpisodePattern)
       if (seasonAndEpisodeMatch) {
@@ -49,7 +51,7 @@ export default function (eleventyConfig, options = {}) {
 
   eleventyConfig.addGlobalData('eleventyComputed.episode.url', () => {
     return data => {
-      if (!data.page.inputPath.includes('/episodePosts/')) return
+      if (!isEpisodePost(data, options)) return
 
       const episodeUrlBase = data.podcast.episodeUrlBase
       const filename = data.episode.filename

package/src/excerpts.js

@@ -1,11 +1,12 @@
 import * as htmlparser2 from 'htmlparser2'
 import render from 'dom-serializer'
 import markdownIt from 'markdown-it'
+import isEpisodePost from './isEpisodePost.js'
 
 export default function (eleventyConfig, options = {}) {
   eleventyConfig.addGlobalData('eleventyComputed.excerpt', () => {
     return (data) => {
-      if (!data.page.inputPath.includes('/episodePosts/')) return
+      if (!isEpisodePost(data, options)) return
 
       const md = markdownIt({
         html: true,

package/src/isEpisodePost.js

@@ -0,0 +1,10 @@
+import path from 'node:path'
+
+export default function isEpisodePost (data, options) {
+  if (data.page?.inputPath) {
+    const importPath = path.normalize(data.page.inputPath)
+    return importPath.startsWith(options.episodePostsDirectory)
+  } else {
+    return false
+  }
+}

package/src/podcastFeed.js

@@ -1,6 +1,7 @@
 import rssPlugin from '@11ty/eleventy-plugin-rss'
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
+import isEpisodePost from './isEpisodePost.js'
 
 export default function (eleventyConfig, options = {}) {
   if (!('addTemplate' in eleventyConfig)) {
@@ -8,11 +9,18 @@ export default function (eleventyConfig, options = {}) {
   }
 
   const podcastFeedPath = path.join(import.meta.dirname, './podcastFeed.njk')
-
   eleventyConfig.addTemplate('feed.njk', readFileSync(podcastFeedPath), {
     eleventyExcludeFromCollections: true,
     eleventyImport: {
-      collections: ['podcastEpisode']
+      collections: ['episodePost']
+    }
+  })
+
+  const chaptersPath = path.join(import.meta.dirname, './chapters.njk')
+  eleventyConfig.addTemplate('chapters.njk', readFileSync(chaptersPath), {
+    eleventyExcludeFromCollections: true,
+    eleventyImport: {
+      collections: ['episodePostWithChapters']
     }
   })
 
@@ -22,7 +30,23 @@ export default function (eleventyConfig, options = {}) {
     }
   })
 
+  eleventyConfig.addCollection('episodePost', (collectionApi) => {
+    return collectionApi
+      .getAll()
+      .filter(item => isEpisodePost(item.data, options))
+      // sort order explicit: presence of template data files disrupts it otherwise
+      .sort((a, b) => a.date - b.date)
+  })
+
+  // included for backward compatibility, will be deprecated in 3.0
   eleventyConfig.addCollection('podcastEpisode', (collectionApi) => {
-    return collectionApi.getFilteredByGlob('**/episodePosts/*')
+    return collectionApi
+      .getAll()
+      .filter(item => isEpisodePost(item.data, options))
+      .sort((a, b) => a.date - b.date)
+  })
+
+  eleventyConfig.addCollection('episodePostWithChapters', (collectionApi) => {
+    return collectionApi.getAll().filter(item => isEpisodePost(item.data, options) && item.data.episode?.chapters)
   })
 }

package/src/podcastFeed.njk

@@ -17,7 +17,7 @@ eleventyAllowMissingExtension: true
     <description>{{ podcast.description }}</description>
     <language>{{ podcast.language }}</language>
     <copyright>{{ podcast.copyrightNotice }}</copyright>
-    <pubDate>{{ collections.podcastEpisode | getNewestCollectionItemDate | dateToRfc3339 }}</pubDate>
+    <pubDate>{{ collections.episodePost | getNewestCollectionItemDate | dateToRfc3339 }}</pubDate>
     <lastBuildDate>{{ podcast.feedLastBuildDate }}</lastBuildDate>
     <itunes:image href="{{ podcast.imagePath | htmlBaseUrl(siteUrl) }}"></itunes:image>
     {%- if podcast.subcategory %}
@@ -47,7 +47,7 @@ eleventyAllowMissingExtension: true
     </itunes:owner>
     {%- endif %}
 
-    {% for post in collections.podcastEpisode | reverse %}
+    {% for post in collections.episodePost | reverse %}
     <item>
       <title>{{ post.data.episode.title or post.data.title }}</title>
       {% if post.data.episode.itunesTitle %}
@@ -60,6 +60,10 @@ eleventyAllowMissingExtension: true
       <guid isPermaLink="true">{{ post.url | htmlBaseUrl(siteUrl) }}</guid>
       {% endif -%}
       <pubDate>{{ post.date | dateToRfc3339 }}</pubDate>
+      {%- if post.data.episode.chapters %}
+      <podcast:chapters url="{{ [post.url, 'chapters.json'] | join('/') | htmlBaseUrl(siteUrl) }}"
+        type="application/json+chapters" />
+      {% endif -%}
       {% if podcast.episodeDescriptionTemplate %}
       {%- set episodeDescription -%}
       {% include podcast.episodeDescriptionTemplate %}

package/src/readableDuration.js

@@ -0,0 +1,26 @@
+import { Duration } from 'luxon'
+
+export default {
+  convertFromSeconds (seconds) {
+    return Duration.fromMillis(seconds * 1000)
+      .shiftTo('days', 'hours', 'minutes', 'seconds')
+      .toHuman()
+  },
+  convertToSeconds (duration) {
+    const durationPattern = /^(?:(?<hours>\d+):)?(?<minutes>\d{1,2}):(?<seconds>\d{2}(?:\.\d+)?)$/
+
+    let match
+    if (duration?.match) {
+      match = duration.match(durationPattern)
+    }
+
+    if (match) {
+      const hours = isNaN(parseInt(match.groups.hours))
+        ? 0
+        : parseInt(match.groups.hours)
+      const minutes = parseInt(match.groups.minutes)
+      const seconds = parseFloat(match.groups.seconds)
+      return hours * 3600 + minutes * 60 + seconds
+    }
+  }
+}