eleventy-plugin-podcaster 2.0.2 → 2.2.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx ava:*)"
+    ]
+  }
+}

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/eleventy.config.js

@@ -5,7 +5,7 @@ import podcastData from './src/podcastData.js'
 import episodeData from './src/episodeData.js'
 import calculateEpisodeSizeAndDuration from './src/calculateEpisodeSizeAndDuration.js'
 import calculateEpisodeFilename from './src/calculateEpisodeFilename.js'
-
+import validation from './src/validation.js'
 import readableFilters from './src/readableFilters.js'
 import chapters from './src/chapters.js'
 import excerpts from './src/excerpts.js'
@@ -23,6 +23,7 @@ export default function (eleventyConfig, options = {}) {
   eleventyConfig.addPlugin(episodeData, options)
   eleventyConfig.addPlugin(calculateEpisodeSizeAndDuration, options)
   eleventyConfig.addPlugin(calculateEpisodeFilename, options)
+  eleventyConfig.addPlugin(validation, options)
 
   // Filters
 

package/jsconfig.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-podcaster",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "An Eleventy plugin that allows you to create a podcast and its accompanying website",
   "main": "eleventy.config.js",
   "exports": {
@@ -29,7 +29,7 @@
   "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",
@@ -40,8 +40,8 @@
   "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/podcastData.js

@@ -1,4 +1,4 @@
-export default function (eleventyConfig) {
+export default function (eleventyConfig, options = {}) {
   eleventyConfig.addGlobalData('eleventyComputed.podcast.feedPath', () => {
     return data => data.podcast.feedPath || '/feed/podcast.xml'
   })
@@ -10,10 +10,8 @@ export default function (eleventyConfig) {
   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) {
+      const siteUrl = data.podcast.siteUrl || data.site?.url
+      if (!siteUrl && !options.validation) {
         console.error('[eleventy-plugin-podcaster] No site URL found. Please set `siteUrl` in your podcast data.')
       }
       return URL.parse('episodes/', siteUrl)

package/src/podcastFeed.js

@@ -5,7 +5,7 @@ import isEpisodePost from './isEpisodePost.js'
 
 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.')
+    console.error('[podcaster] 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')
@@ -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" />
@@ -27,8 +29,10 @@ eleventyAllowMissingExtension: true
     {%- else %}
     <itunes:category text="{{ podcast.category }}" />
     {%- endif %}
-    {% if podcast.explicit !== undefined %}
-    <itunes:explicit>{{ podcast.explicit }}</itunes:explicit>
+    {% if podcast.explicit == true %}
+    <itunes:explicit>true</itunes:explicit>
+    {% else %}
+    <itunes:explicit>false</itunes:explicit>
     {% endif -%}
     <itunes:author>{{ podcast.author }}</itunes:author>
     {%- if podcast.type %}

package/src/validation.js

@@ -0,0 +1,62 @@
+import isEpisodePost from './isEpisodePost.js'
+
+function warn (message) {
+  console.warn(`[podcaster] ${message}`)
+}
+
+function warnOrThrow (message) {
+  if (process.env.ELEVENTY_RUN_MODE === 'build') {
+    throw new Error(`[podcaster] ${message}`)
+  } else {
+    console.warn(`[podcaster] ${message}`)
+  }
+}
+
+export default function (eleventyConfig, options = {}) {
+  eleventyConfig.addGlobalData('eleventyDataSchema', () => {
+    return (data) => {
+      if (!options.validation) return
+
+      // podcast data
+
+      if (!(data.podcast.siteUrl || data.site?.url)) {
+        warnOrThrow('Site URL is required')
+      }
+      if (!data.podcast.title) {
+        warnOrThrow('Podcast title is required')
+      }
+      if (!data.podcast.description) {
+        warnOrThrow('Podcast description is required')
+      }
+      if (!data.podcast.language) {
+        warnOrThrow('Podcast language is required')
+      }
+      if (!data.podcast.category) {
+        warnOrThrow('Podcast category is required')
+      }
+      if (!data.podcast.author) {
+        warnOrThrow('Podcast author is required')
+      }
+
+      // episode data
+
+      if (isEpisodePost(data, options)) {
+        if (!data.title) {
+          warnOrThrow(`Episode title is required (${data.page.inputPath})`)
+        }
+        if (!data.episode.filename) {
+          warnOrThrow(`Episode filename is required (${data.page.inputPath})`)
+        }
+        if (!data.episode.size) {
+          warnOrThrow(`Episode size is required (${data.page.inputPath})`)
+        }
+        if (!data.episode.episodeNumber) {
+          warn(`Episode number is recommended (${data.page.inputPath})`)
+        }
+        if (!data.episode.duration) {
+          warn(`Episode duration is recommended (${data.page.inputPath})`)
+        }
+      }
+    }
+  })
+}