eleventy-plugin-podcaster 1.4.1 → 2.0.0-alpha.1

package/README.md

@@ -38,13 +38,16 @@ export default function (eleventyConfig) {
 
 ## ➡ [Documentation and usage][Podcaster]
 
-Detailed and specific information about how to install and use **Podcaster** can be found in [the Documentation section](https://eleventy-plugin-podcaster.com/docs) of [the `eleventy-plugin-podcaster` site][Podcaster], but here's a quick summary.
+[Podcaster]: https://eleventy-plugin-podcaster.com/docs
 
-[Podcaster]: https://eleventy-plugin-podcaster.com
+Detailed and specific information about how to install and use **Podcaster** can be found in [the Documentation section](docs/index.md) of the site, but here's a quick summary.
 
-**Podcaster** is an Eleventy plugin. You install it in your config file in the usual way. You usually provide it with information about your podcast — like its title, description and category — by creating a `podcast.json` file in the data directory. For each episode, you create a template with information in the front matter about that episode — its name, release date, filename, duration and so on.
-
-Once you do this, **Podcaster** can create the RSS feed for your podcast. You can also create templates for various pages on your website and include on those pages the information you have provided about the podcast and its episodes.
+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**.
+6. Find a host for your site, and a CDN for your podcast episodes.
 
 > [!WARNING]
-> **Podcaster** only works with Node 20 and later.
+> **Podcaster** requires Node 20 or later.

package/ava.config.js

@@ -0,0 +1,3 @@
+export default {
+  files: ['test/**/*', '!test/v1']
+}

package/eleventy.config.js

@@ -1,138 +1,37 @@
-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 podcastFeed from './src/podcastFeed.js'
+import podcastData from './src/podcastData.js'
+import episodeData from './src/episodeData.js'
 import calculateFilenameSizeAndDuration from './src/calculateFilenameSizeAndDuration.js'
+import readableFilters from './src/readableFilters.js'
 import excerpts from './src/excerpts.js'
 import drafts from './src/drafts.js'
+import pageTitle from './src/pageTitle.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(podcastFeed, options)
+  eleventyConfig.addPlugin(podcastData, options)
+  eleventyConfig.addPlugin(episodeData, options)
+  eleventyConfig.addPlugin(calculateFilenameSizeAndDuration, options)
 
-  eleventyConfig.addPlugin(rssPlugin, {
-    posthtmlRenderOptions: {
-      closingSingleTag: 'default' // opt-out of <img/>-style XHTML single tags
-    }
-  })
+  // Filters
 
-  eleventyConfig.addGlobalData('eleventyComputed.podcast.feedPath', () => {
-    return data => data.podcast.feedPath || '/feed/podcast.xml'
-  })
+  eleventyConfig.addPlugin(readableFilters, options)
 
-  eleventyConfig.addGlobalData('eleventyComputed.podcast.imagePath', () => {
-    return data => data.podcast.imagePath || '/img/podcast-logo.jpg'
-  })
+  // Optional features
 
-  function calculateCopyrightNotice () {
-    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}`
-    }
+  if (options.optionalFeatures) {
+    options.handleDrafts = true
+    options.handleExcerpts = true
+    options.handlePageTitle ??= true // preserve setting for custom separators
   }
 
-  eleventyConfig.addGlobalData(
-    'eleventyComputed.podcast.copyrightNotice',
-    calculateCopyrightNotice
-  )
-
-  eleventyConfig.addGlobalData(
-    'eleventyComputed.copyrightNotice',
-    calculateCopyrightNotice
-  )
-
-  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)
-
-  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)
-    })
+  if (options.handleExcerpts) {
+    eleventyConfig.addPlugin(excerpts, options)
   }
-
-  if (options.calculatePageTitle) {
-    const separator = options.calculatePageTitle === true ? '&middot;' : options.calculatePageTitle
-
-    eleventyConfig.addGlobalData('eleventyComputed.pageTitle', () => {
-      return data => {
-        const siteTitle = data.site?.title || data.podcast.title
-        if (data.title && data.title.length > 0 && data.title !== siteTitle) {
-          return `${data.title} ${separator} ${siteTitle}`
-        } else {
-          return siteTitle
-        }
-      }
-    })
+  if (options.handleDrafts) {
+    eleventyConfig.addPlugin(drafts, options)
   }
-
-  eleventyConfig.addFilter('readableDuration', (seconds, omitLeadingZero) => {
-    if (!seconds) return '0:00:00'
-    if (omitLeadingZero && seconds < 3600) {
-      return Duration.fromMillis(seconds * 1000).toFormat('mm:ss')
-    }
-    return Duration.fromMillis(seconds * 1000).toFormat('h:mm:ss')
-  })
-
-  eleventyConfig.addFilter('readableSize', (bytes, fixedPrecision) =>
-    (fixedPrecision)
-      ? hr.fromBytes(bytes, { fixedPrecision })
-      : hr.fromBytes(bytes)
-  )
-
-  const podcastFeedPath = path.join(import.meta.dirname, './src/podcastFeed.njk')
-
-  eleventyConfig.addTemplate('feed.njk', readFileSync(podcastFeedPath), {
-    eleventyExcludeFromCollections: true,
-    eleventyImport: {
-      collections: ['podcastEpisode']
-    }
-  })
-
-  if (options.handleEpisodePermalinks) {
-    eleventyConfig.addGlobalData('eleventyComputed.permalink', () => {
-      return data => {
-        if (data.permalink) return data.permalink
-
-        if (data.tags?.includes('podcastEpisode')) {
-          if (data.episode?.seasonNumber) {
-            return `/s${data.episode.seasonNumber}/e${data.episode.episodeNumber}/`
-          } else {
-            return `/${data.episode.episodeNumber}/`
-          }
-        }
-      }
-    })
+  if (options.handlePageTitle) {
+    eleventyConfig.addPlugin(pageTitle, options)
   }
-
-  eleventyConfig.addPlugin(calculateFilenameSizeAndDuration, options)
-  eleventyConfig.addPlugin(excerpts, options)
-  eleventyConfig.addPlugin(drafts, options)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-podcaster",
-  "version": "1.4.1",
+  "version": "2.0.0-alpha.1",
   "description": "An Eleventy plugin that allows you to create a podcast and its accompanying website",
   "main": "eleventy.config.js",
   "exports": {
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "git+https://github.com/nathan-bottomley/eleventy-plugin-podcaster.git"
   },
-  "homepage": "https://github.com/nathan-bottomley/eleventy-plugin-podcaster/tree/main/docs",
+  "homepage": "https://eleventy-plugin-podcaster.com",
   "type": "module",
   "scripts": {
     "test": "ava"
@@ -36,7 +36,7 @@
     "htmlparser2": "^9.1.0",
     "luxon": "^3.4.4",
     "markdown-it": "^14.1.0",
-    "mp3-duration": "^1.1.0"
+    "music-metadata": "^11.7.1"
   },
   "devDependencies": {
     "ava": "^6.1.3",

package/src/calculateFilenameSizeAndDuration.js

@@ -1,8 +1,8 @@
 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 { readdir, stat, writeFile } from 'node:fs/promises'
+import { parseFile } from 'music-metadata'
 import hr from '@tsmx/human-readable'
 import chalk from 'chalk'
 
@@ -11,73 +11,85 @@ const convertSecondsToReadableDuration = seconds =>
     .shiftTo('days', 'hours', 'minutes', 'seconds')
     .toHuman()
 
-export default function (eleventyConfig, options = {}) {
+export default function (eleventyConfig) {
   let firstRun = true
-  eleventyConfig.on('eleventy.before', async ({ dir, directories }) => {
+  eleventyConfig.on('eleventy.before', async ({ 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')
+    const episodesDir = path.join(directories.input, 'episodeFiles')
     if (!existsSync(episodesDir)) return
 
     const episodes = await readdir(episodesDir)
-    const episodesData = {}
-    let totalEpisodes = 0
+    const episodeData = {}
+    let numberOfEpisodes = 0
     let totalSize = 0
     let totalDuration = 0
 
     for (const episode of episodes) {
       if (!episode.endsWith('.mp3')) continue
 
-      totalEpisodes++
+      numberOfEpisodes++
       const episodePath = path.join(episodesDir, episode)
       const episodeSize = (await stat(episodePath)).size
       totalSize += episodeSize
-      const buffer = await readFile(episodePath)
-      const episodeDuration = await mp3Duration(buffer)
+      const episodeMetadata = await parseFile(episodePath, { duration: true })
+      const episodeDuration = episodeMetadata.format.duration
       totalDuration += episodeDuration
-      episodesData[episode] = {
+      episodeData[episode] = {
         size: episodeSize,
-        duration: episodeDuration
+        duration: Math.round(episodeDuration * 1000) / 1000
       }
+      totalDuration = Math.round(totalDuration * 1000) / 1000
     }
+    const podcastData = { numberOfEpisodes, totalSize, totalDuration }
 
     const dataDir = path.join(process.cwd(), directories.data)
-    await writeFile(path.join(dataDir, 'episodesData.json'), JSON.stringify(episodesData, null, 2))
+    await writeFile(path.join(dataDir, 'episodeData.json'), JSON.stringify(episodeData, null, 2))
+    await writeFile(path.join(dataDir, 'podcastData.json'), JSON.stringify(podcastData, null, 2))
 
-    console.log(chalk.yellow(`${totalEpisodes} episodes; ${hr.fromBytes(totalSize)}; ${convertSecondsToReadableDuration(totalDuration)}.`))
+    console.log(chalk.yellow(`${numberOfEpisodes} episodes; ${hr.fromBytes(totalSize)}; ${convertSecondsToReadableDuration(totalDuration)}.`))
   })
 
-  if (options.episodeFilenamePattern) {
-    eleventyConfig.addGlobalData('eleventyComputed.episode.filename', () => {
-      return data => {
-        if (data.episode.filename) return data.episode.filename
+  const filenameSeasonAndEpisodePattern =
+    /^.*?\b[sS](?<seasonNumber>\d+)[eE](?<episodeNumber>\d+)\b.*\.mp3$/
+  const filenameEpisodePattern = /^.*?\b(?<episodeNumber>\d+)\b.*\.mp3$/
+
+  eleventyConfig.addGlobalData('eleventyComputed.episode.filename', () => {
+    return data => {
+      if (data.episode.filename) return data.episode.filename
 
-        if (data.tags?.includes('podcastEpisode') && data.episodesData) {
-          for (const file of Object.keys(data.episodesData)) {
-            const match = file.match(options.episodeFilenamePattern)
-            const matchedSeasonNumber = parseInt(match?.groups.seasonNumber)
-            const matchedEpisodeNumber = parseInt(match?.groups.episodeNumber)
-            if (isNaN(matchedSeasonNumber) && matchedEpisodeNumber ===
-                data.episode.episodeNumber) {
+      if (!data.page.inputPath.includes('/episodePosts/')) return
+
+      for (const file of Object.keys(data.episodeData)) {
+        if (data.episode.seasonNumber && data.episode.episodeNumber) {
+          const seasonAndEpisodeMatch = file.match(filenameSeasonAndEpisodePattern)
+          if (seasonAndEpisodeMatch) {
+            const matchedSeasonNumber = parseInt(seasonAndEpisodeMatch.groups.seasonNumber)
+            const matchedEpisodeNumber = parseInt(seasonAndEpisodeMatch.groups.episodeNumber)
+            if (matchedSeasonNumber === data.episode.seasonNumber &&
+                matchedEpisodeNumber === data.episode.episodeNumber) {
               return file
-            } else if (matchedSeasonNumber === data.episode.seasonNumber &&
-                       matchedEpisodeNumber === data.episode.episodeNumber) {
+            }
+          }
+        } else if (data.episode.episodeNumber) {
+          const episodeMatch = file.match(filenameEpisodePattern)
+          if (episodeMatch) {
+            const matchedEpisodeNumber = parseInt(episodeMatch.groups.episodeNumber)
+            if (matchedEpisodeNumber === data.episode.episodeNumber) {
               return file
             }
           }
         }
       }
-    })
-  }
+    }
+  })
 
   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
+      if (data.page.inputPath.includes('/episodePosts/') && data.episodeData) {
+        return data.episodeData[data.episode.filename]?.size
       }
     }
   })
@@ -86,8 +98,8 @@ export default function (eleventyConfig, options = {}) {
     return data => {
       if (data.episode.duration) return data.episode.duration
 
-      if (data.tags?.includes('podcastEpisode') && data.episodesData) {
-        return data.episodesData[data.episode.filename]?.duration
+      if (data.page.inputPath.includes('/episodePosts/') && data.episodeData) {
+        return data.episodeData[data.episode.filename]?.duration
       }
     }
   })

package/src/episodeData.js

@@ -0,0 +1,59 @@
+export default function (eleventyConfig, options = {}) {
+  const postFilenameSeasonAndEpisodePattern =
+    /^[sS](?<seasonNumber>\d+)[eE](?<episodeNumber>\d+)/i
+  const postFilenameEpisodePattern = /^(?:e|ep|episode-)(?<episodeNumber>\d+)/i
+
+  eleventyConfig.addGlobalData('eleventyComputed.episode.seasonNumber', () => {
+    return data => {
+      if (data.episode?.seasonNumber) return data.episode.seasonNumber
+
+      if (!data.page.inputPath.includes('/episodePosts/')) return
+
+      const seasonAndEpisodeMatch = data.page.fileSlug.match(postFilenameSeasonAndEpisodePattern)
+      if (seasonAndEpisodeMatch) {
+        return parseInt(seasonAndEpisodeMatch.groups.seasonNumber, 10)
+      }
+    }
+  })
+
+  eleventyConfig.addGlobalData('eleventyComputed.episode.episodeNumber', () => {
+    return data => {
+      if (data.episode?.episodeNumber) return data.episode.episodeNumber
+
+      if (!data.page.inputPath.includes('/episodePosts/')) return
+
+      const seasonAndEpisodeMatch = data.page.fileSlug.match(postFilenameSeasonAndEpisodePattern)
+      if (seasonAndEpisodeMatch) {
+        return parseInt(seasonAndEpisodeMatch.groups.episodeNumber, 10)
+      }
+      const episodeMatch = data.page.fileSlug.match(postFilenameEpisodePattern)
+      if (episodeMatch) {
+        return parseInt(episodeMatch.groups.episodeNumber, 10)
+      } else {
+        console.error(`[eleventy-plugin-podcaster] Cannot determine episode number for ${data.page.inputPath}. Please ensure the file slug contains a number or set the episodeNumber explicitly in the front matter.`)
+      }
+    }
+  })
+
+  eleventyConfig.addGlobalData('eleventyComputed.permalink', () => {
+    return data => {
+      if (data.permalink) return data.permalink
+
+      if (data.episode?.seasonNumber && data.episode?.episodeNumber) {
+        return `/s${data.episode.seasonNumber}/e${data.episode.episodeNumber}/`
+      } else if (data.episode?.episodeNumber) {
+        return `/${data.episode.episodeNumber}/`
+      }
+    }
+  })
+
+  eleventyConfig.addGlobalData('eleventyComputed.episode.url', () => {
+    return data => {
+      if (!data.page.inputPath.includes('/episodePosts/')) return
+
+      const episodeUrlBase = data.podcast.episodeUrlBase
+      const filename = data.episode.filename
+      return URL.parse(filename, episodeUrlBase)
+    }
+  })
+}

package/src/excerpts.js

@@ -4,10 +4,8 @@ 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
+      if (!data.page.inputPath.includes('/episodePosts/')) return
 
       const md = markdownIt({
         html: true,

package/src/pageTitle.js

@@ -0,0 +1,16 @@
+export default function (eleventyConfig, options = {}) {
+  const separator = (options.handlePageTitle === true)
+    ? '·'
+    : options.handlePageTitle
+
+  eleventyConfig.addGlobalData('eleventyComputed.pageTitle', () => {
+    return data => {
+      const siteTitle = data.site?.title || data.podcast.title
+      if (data.title && data.title.length > 0 && data.title !== siteTitle) {
+        return `${data.title} ${separator} ${siteTitle}`
+      } else {
+        return siteTitle
+      }
+    }
+  })
+}

package/src/podcastData.js

@@ -0,0 +1,39 @@
+import { DateTime } from 'luxon'
+
+export default function (eleventyConfig) {
+  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.episodeUrlBase', () => {
+    return data => {
+      if (data.podcast.episodeUrlBase) return data.podcast.episodeUrlBase
+      let siteUrl
+      try {
+        siteUrl = data.podcast.siteUrl || data.site.url
+      } catch (e) {
+        console.error('[eleventy-plugin-podcaster] No site URL found. Please set `siteUrl` in your podcast data.')
+      }
+      return URL.parse('episodes/', siteUrl)
+    }
+  })
+
+  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())
+}

package/src/podcastFeed.js

@@ -0,0 +1,28 @@
+import rssPlugin from '@11ty/eleventy-plugin-rss'
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+export default function (eleventyConfig, options = {}) {
+  if (!('addTemplate' in eleventyConfig)) {
+    console.error('[eleventy-plugin-podcasting] Eleventy plugin compatibility: Virtual Templates are required for this plugin — please use Eleventy v3.0 or newer.')
+  }
+
+  const podcastFeedPath = path.join(import.meta.dirname, './podcastFeed.njk')
+
+  eleventyConfig.addTemplate('feed.njk', readFileSync(podcastFeedPath), {
+    eleventyExcludeFromCollections: true,
+    eleventyImport: {
+      collections: ['podcastEpisode']
+    }
+  })
+
+  eleventyConfig.addPlugin(rssPlugin, {
+    posthtmlRenderOptions: {
+      closingSingleTag: 'default' // opt-out of <img/>-style XHTML single tags
+    }
+  })
+
+  eleventyConfig.addCollection('podcastEpisode', (collectionApi) => {
+    return collectionApi.getFilteredByGlob('**/episodePosts/*')
+  })
+}

package/src/readableFilters.js

@@ -0,0 +1,27 @@
+import { DateTime, Duration } from 'luxon'
+import hr from '@tsmx/human-readable'
+
+export default function (eleventyConfig, options = {}) {
+  eleventyConfig.addFilter('readableDate', function (date) {
+    const readableDateLocale = options.readableDateLocale ?? 'en-AU'
+    if (date instanceof Date) {
+      date = date.toISOString()
+    }
+    const result = DateTime.fromISO(date, {
+      zone: 'UTC'
+    })
+    return result.setLocale(readableDateLocale).toLocaleString(DateTime.DATE_HUGE)
+  })
+
+  eleventyConfig.addFilter('readableDuration', (seconds) => {
+    if (!seconds) return '0:00:00'
+    if (seconds < 3600) {
+      return Duration.fromMillis(seconds * 1000).toFormat('mm:ss')
+    }
+    return Duration.fromMillis(seconds * 1000).toFormat('h:mm:ss')
+  })
+
+  eleventyConfig.addFilter('readableSize', (bytes, fixedPrecision = 1) =>
+    hr.fromBytes(bytes, { fixedPrecision })
+  )
+}