eleventy-plugin-podcaster 2.0.1 → 2.1.0

package/CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm test          # run all tests (AVA)
+npx ava test/someTestFile.js  # run a single test file
+npx eslint src/   # lint source files
+```
+
+There is no build step — the plugin is used directly from source.
+
+## Architecture
+
+`eleventy.config.js` is the plugin entry point. It registers 8 sub-plugins and 3 optional features:
+
+**Core sub-plugins (always active):**
+
+- `podcastFeed.js` — RSS feed generation; creates `episodePost` and `episodePostWithChapters` collections via virtual templates
+- `podcastData.js` — Computes podcast-level `eleventyComputed` fields: `feedPath`, `imagePath`, `episodeUrlBase`, `copyrightNotice`
+- `episodeData.js` — Parses `seasonNumber`/`episodeNumber` from filenames; constructs episode `url` and `permalink`
+- `calculateEpisodeSizeAndDuration.js` — Reads audio metadata from local files or S3; caches results; uses `music-metadata`
+- `calculateEpisodeFilename.js` — Matches episode posts to audio files by season/episode number
+- `readableFilters.js` — Adds `readableDate`, `readableDuration`, `readableSize` filters
+- `chapters.js` — Filter for normalizing chapter data to JSON-LD; template in `src/chapters.njk`
+
+**Optional features (opt-in via plugin options):**
+
+- `drafts.js` — Filters draft posts; controlled by `INCLUDE_DRAFTS` env var or `ELEVENTY_RUN_MODE`
+- `excerpts.js` — Auto-generates episode excerpts from front matter, HTML comments, or first paragraph
+- `pageTitle.js` — Computes `pageTitle` with configurable separator
+
+**Options:** `handleDrafts`, `handleExcerpts`, `handlePageTitles` (individual flags), or `optionalFeatures: true` (enables all three). `episodePostsDirectory` and `episodeFilesDirectory` override the default directory names.
+
+## Tests
+
+Tests use AVA and are configured in `ava.config.js`. Each test file typically builds a fixture site using Eleventy's programmatic API and asserts on the output.
+
+Fixture sites live in `fixtures/` — each is a minimal Eleventy site with `eleventy.config.js`, `_data/podcast.json`, episode markdown files in `episode-posts/`, and audio files in `episode-files/`.
+
+Key environment variables used in tests:
+
+- `SKIP_EPISODE_CALCULATIONS` — skip audio metadata calculation (speeds up tests that don't need it)
+- `INCLUDE_DRAFTS` — controls draft inclusion
+- `ELEVENTY_RUN_MODE` — `'build'` or `'serve'`
+
+## Conventions
+
+- All source files are ES modules (`"type": "module"` in package.json)
+- Computed episode/podcast fields are set via Eleventy's `eleventyComputed` pattern
+- No Luxon — duration logic uses native `Intl` / `Date`; see `src/readableDuration.js`
+- Commit messages: short past-tense verb phrases, no body, no co-author lines (e.g. `Removed Luxon dependency`)

package/TODO.md

@@ -0,0 +1,24 @@
+# TODO
+
+## Warnings and errors for missing data
+
+Add consistent warnings and errors when required data is missing. This should be opt-in via a plugin option to avoid a breaking change.
+
+Behaviour:
+
+- In development (`ELEVENTY_RUN_MODE === 'serve'`): log warnings but continue the build
+- In production: throw errors and stop the build
+
+Cases to handle:
+
+- Missing `podcast.json` or required fields within it
+- Episode post without a matching audio file
+- Malformed episode numbering in filenames
+- Incomplete S3 configuration (some keys but not others)
+- Missing audio file when calculating duration/size
+
+Implementation notes:
+
+- Use a consistent prefix like `[podcaster]` so messages are identifiable
+- New plugin option (e.g., `strictMode` or `validateData`) to enable this
+- The draft system may already cover some cases (e.g., incomplete episodes marked as drafts)

package/jsconfig.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "checkJs": false
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-podcaster",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "An Eleventy plugin that allows you to create a podcast and its accompanying website",
   "main": "eleventy.config.js",
   "exports": {
@@ -29,20 +29,19 @@
   "license": "ISC",
   "dependencies": {
     "@11ty/eleventy": "^3.0.0",
-    "@11ty/eleventy-plugin-rss": "^2.0.1",
+    "@11ty/eleventy-plugin-rss": "^3.0.0",
     "@aws-sdk/client-s3": "^3.862.0",
     "@tsmx/human-readable": "^2.0.3",
     "dom-serializer": "^2.0.0",
     "htmlparser2": "^9.1.0",
-    "luxon": "^3.4.4",
     "markdown-it": "^14.1.0",
     "music-metadata": "^11.7.1"
   },
   "devDependencies": {
     "ava": "^6.1.3",
     "dotenv": "^17.2.1",
-    "fast-xml-parser": "^4.4.0",
-    "mock-aws-s3-v3": "^6.0.5",
+    "fast-xml-parser": "^5.5.9",
+    "mock-aws-s3-v3": "^6.1.12",
     "neostandard": "^0.11.4"
   }
 }

package/src/calculateEpisodeSizeAndDuration.js

@@ -1,4 +1,3 @@
-import { DateTime } from 'luxon'
 import readableDuration from './readableDuration.js'
 import path from 'node:path'
 import { existsSync, readFileSync } from 'node:fs'
@@ -96,7 +95,7 @@ async function getCachedEpisodeDataFromS3Bucket (s3Storage, s3Bucket) {
 async function calculateEpisodeDataFromS3Bucket (s3Storage, s3Bucket) {
   const cachedEpisodeData = await getCachedEpisodeDataFromS3Bucket(s3Storage, s3Bucket)
   const cachedEpisodeDataLastModifiedDate = (cachedEpisodeData.lastModified)
-    ? DateTime.fromISO(cachedEpisodeData.lastModified)
+    ? new Date(cachedEpisodeData.lastModified)
     : null
 
   console.log(`Reading episode data from S3 bucket ${s3Bucket}`)
@@ -111,7 +110,7 @@ async function calculateEpisodeDataFromS3Bucket (s3Storage, s3Bucket) {
         !('size' in result[filename]) ||
         !('duration' in result[filename]) ||
         !cachedEpisodeDataLastModifiedDate ||
-        cachedEpisodeDataLastModifiedDate < DateTime.fromISO(lastModified)) {
+        cachedEpisodeDataLastModifiedDate < new Date(lastModified)) {
       const { buffer } = await getObjectFromS3Bucket(s3Storage, s3Bucket, filename)
       const metadata = await parseBufferMetadata(buffer, null, { duration: true })
       const duration = metadata.format.duration

package/src/podcastData.js

@@ -1,5 +1,3 @@
-import { DateTime } from 'luxon'
-
 export default function (eleventyConfig) {
   eleventyConfig.addGlobalData('eleventyComputed.podcast.feedPath', () => {
     return data => data.podcast.feedPath || '/feed/podcast.xml'
@@ -23,7 +21,7 @@ export default function (eleventyConfig) {
   })
 
   function constructCopyrightNotice (data) {
-    const thisYear = DateTime.now().year
+    const thisYear = new Date().getFullYear()
     let yearRange
     if (!data.podcast.startingYear || data.podcast.startingYear === thisYear) {
       yearRange = thisYear
@@ -40,5 +38,5 @@ export default function (eleventyConfig) {
   eleventyConfig.addGlobalData('eleventyComputed.copyrightNotice', () => {
     return constructCopyrightNotice
   })
-  eleventyConfig.addGlobalData('podcast.feedLastBuildDate', DateTime.now().toRFC2822())
+  eleventyConfig.addGlobalData('podcast.feedLastBuildDate', new Date().toUTCString().replace('GMT', '+0000'))
 }

package/src/podcastFeed.js

@@ -13,7 +13,9 @@ export default function (eleventyConfig, options = {}) {
     eleventyExcludeFromCollections: true,
     eleventyImport: {
       collections: ['episodePost']
-    }
+    },
+    script: options?.feedScript,
+    stylesheet: options?.feedStylesheet
   })
 
   const chaptersPath = path.join(import.meta.dirname, './chapters.njk')

package/src/podcastFeed.njk

@@ -5,12 +5,14 @@ eleventyAllowMissingExtension: true
 ---
 {%- set siteUrl %}{{ podcast.siteUrl or site.url }}{% endset -%}
 <?xml version="1.0" encoding="utf-8"?>
+{% if stylesheet %}<?xml-stylesheet type="text/xsl" href="{{ stylesheet }}" ?>{% endif %}
 <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/"
   xmlns:podcast="https://podcastindex.org/namespace/1.0">
   <channel>
+    {% if script %}<script src="{{ script }}" xmlns="http://www.w3.org/1999/xhtml"></script>{% endif %}
     <title>{{ podcast.title }}</title>
     <link>{{ siteUrl }}</link>
     <atom:link href="{{ permalink | htmlBaseUrl(siteUrl) }}" rel="self" type="application/rss+xml" />

package/src/readableDuration.js

@@ -1,10 +1,29 @@
-import { Duration } from 'luxon'
+function pluralise (value, unit) {
+  return `${value} ${unit}${value === 1 ? '' : 's'}`
+}
+
+function toComponents (seconds) {
+  return {
+    d: Math.floor(seconds / 86400),
+    h: Math.floor((seconds % 86400) / 3600),
+    m: Math.floor((seconds % 3600) / 60),
+    s: Math.round((seconds % 60) * 1000) / 1000
+  }
+}
 
 export default {
-  convertFromSeconds (seconds) {
-    return Duration.fromMillis(seconds * 1000)
-      .shiftTo('days', 'hours', 'minutes', 'seconds')
-      .toHuman()
+  longFormat (seconds) {
+    const { d, h, m, s } = toComponents(seconds)
+    return [pluralise(d, 'day'), pluralise(h, 'hour'), pluralise(m, 'minute'), pluralise(s, 'second')].join(', ')
+  },
+  shortFormat (seconds) {
+    const h = Math.floor(seconds / 3600)
+    const m = Math.floor((seconds % 3600) / 60)
+    const s = Math.floor(seconds % 60)
+    if (h === 0) {
+      return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`
+    }
+    return `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`
   },
   convertToSeconds (duration) {
     const durationPattern = /^(?:(?<hours>\d+):)?(?<minutes>\d{1,2}):(?<seconds>\d{2}(?:\.\d+)?)$/

package/src/readableFilters.js

@@ -1,29 +1,24 @@
-import { DateTime, Duration } from 'luxon'
 import hr from '@tsmx/human-readable'
+import readableDuration from './readableDuration.js'
 
 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 new Date(date).toLocaleDateString(readableDateLocale, {
+      weekday: 'long',
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric',
+      timeZone: 'UTC'
     })
-    return result.setLocale(readableDateLocale).toLocaleString(DateTime.DATE_HUGE)
   })
 
   eleventyConfig.addFilter('readableDuration', (seconds, length) => {
     if (!seconds) return '0:00'
     if (length === 'long') {
-      return Duration.fromMillis(seconds * 1000)
-        .shiftTo('days', 'hours', 'minutes', 'seconds')
-        .toHuman()
-    } else if (seconds < 60 * 60) {
-      return Duration.fromMillis(seconds * 1000).toFormat('mm:ss')
-    } else {
-      return Duration.fromMillis(seconds * 1000).toFormat('h:mm:ss')
+      return readableDuration.longFormat(seconds)
     }
+    return readableDuration.shortFormat(seconds)
   })
 
   eleventyConfig.addFilter('readableSize', (bytes, fixedPrecision = 1) =>