feat: podcast RSS feed generation (iTunes-compatible) (#46)

* feat: add podcast RSS feed generation (iTunes-compatible)

- Add layouts/_default/rss.xml: auto-detects podcast config and renders
  either iTunes podcast RSS (with itunes: namespace, categories, owner,
  artwork, per-episode enclosure/tags) or a standard RSS 2.0 feed.
- Detection: checks for author, image, or description in [params.podcast];
  no toggle flag needed.
- Episode front matter: all RSS fields under podcast: key (src, type,
  duration, season, episode, explicit, author, guid, episodeType).
- Local audio auto-resolves enclosure length via Hugo resources.
- Add exampleSite podcast config and rss-demo episode with full metadata.
- Add copy-to-clipboard buttons on code blocks (assets/js/code-copy.js).
- Improve content typography: h2/h3/p/pre/table spacing in baseof.css.
- Improve episode nav: SVG chevron arrows, actual episode titles,
  dashed back-to-program link, mobile stacking layout.
- Fix program URL fallback for episodes without a program page.
- Add 7 Hugo integration tests for RSS (podcast + standard modes).
- Document podcast RSS in README with config examples and front matter
  reference.

* fix: self-contained testdata sites, remove module imports

The RSS test fixtures used go.mod files with replace directives to
import the wavecast module. This failed on CI because Hugo module
resolution in subdirectories differs from local dev.

Fix: follow the existing testdata pattern - copy the RSS template
locally into each test fixture's layouts/_default/rss.xml and remove
the [module] imports and go.mod files. The test sites are now fully
self-contained, matching how the shortcode tests work.

Also removed --quiet from buildHugoSite to ensure Hugo error output
is visible in CI logs when builds fail.

* fix: replace .Site.Language.Locale with .Site.LanguageCode for Hugo v0.146+

.Site.Language.Locale was added in Hugo v0.148.0. The CI workflow
uses Hugo v0.146.0, so the RSS template crashed with:
  can't evaluate field Locale in type *langs.Language

Replaced with .Site.LanguageCode which is available since Hugo 0.80+.

Author: adurrr

README.md

@@ -38,7 +38,8 @@ Both components are **bidirectionally synced** - pausing the footer pauses all i
 - **Keyboard shortcuts**: Space (play/pause), Left/Right (skip), M (mute)
 - **Media Session API**: integrates with OS media controls (lock screen, notification centre)
 - **Accessible**: ARIA labels, `:focus-visible` rings, semantic controls
-- **Well tested**: Go integration tests, JS unit tests (Vitest), Playwright E2E
+- **Well tested**: Go integration tests, JS unit tests (Vitest), Playwright E2E, RSS output tests
+- **Podcast RSS feed**: iTunes-compatible podcast RSS generation from Hugo content with automatic detection
 
 ---
 
@@ -298,6 +299,83 @@ Multiple players on the same page use separate `sessionStorage` keys (`podcastPl
 
 ---
 
+## Podcast RSS Feed
+
+Wavecast provides a built-in podcast RSS template at `layouts/_default/rss.xml`. When podcast metadata is configured in your `hugo.toml`, the template automatically renders an iTunes-compatible podcast feed suitable for submission to Apple Podcasts, Spotify, and other directories. Without podcast config, it falls back to a clean standard RSS 2.0 feed.
+
+### Enabling the podcast feed
+
+Add a `[params.podcast]` section to your site's `hugo.toml`. The template detects at least one of `author`, `image`, or `description` and switches into podcast mode:
+
+```toml
+[params.podcast]
+  description = "A weekly show about open-source and software engineering."
+  author = "Your Name"
+  summary  = "Longer show description (up to 4000 characters). Shown on the ⓘ info popup in podcast apps."
+  image    = "/podcast-cover.jpg"    # ≥1400×1400 px recommended
+  explicit = false                    # "true" or "false"
+  type     = "episodic"               # "episodic" or "serial"
+  owner_name  = "Your Name"
+  owner_email = "you@example.com"
+  language = "en-us"                  # overrides site.languageCode if set
+  copyright = "© 2026 Your Name"
+
+  [[params.podcast.categories]]
+    category = "Technology"
+  [[params.podcast.categories]]
+    category = "Education"
+    subcategory = "Courses"           # optional
+```
+
+### Episode front matter
+
+Add a `podcast:` key to each episode's YAML front matter. Only `src` is required for an item to appear in the feed:
+
+```yaml
+---
+title: "Episode 42: The Big One"
+date: 2026-06-01
+podcast:
+  src: "https://example.com/audio/ep42.mp3"
+  type: "audio/mpeg"        # MIME type (default: audio/mpeg)
+  duration: "00:45:00"      # HH:MM:SS or seconds
+  season: 2                 # season number
+  episode: 42               # episode number
+  explicit: false           # overrides site-level explicit
+  author: "Guest Host"      # overrides site-level author
+  guid: "unique-ep-42"      # falls back to permalink
+  episodeType: "full"       # "full", "trailer", or "bonus"
+  subtitle: "A short episode teaser (≤255 chars, appears in Description column)"
+  summary: "Full episode summary, up to 4000 characters."
+---
+```
+
+### How it works
+
+| Scenario | RSS output |
+|----------|-----------|
+| No `[params.podcast]` in config | Standard RSS 2.0 (suitable for blogs) |
+| `[params.podcast]` with `author`, `image`, or `description` | Full iTunes podcast RSS with itunes: namespace |
+| Episode has `podcast.src` (local file) | Enclosure with `length` auto-resolved from Hugo resources |
+| Episode has `podcast.src` (remote URL) | Enclosure with `length="0"` |
+| Episode has NO `podcast.src` | Omitted from feed entirely |
+
+### Feed output
+
+The feed is available at `/index.xml` (home page). Hugo automatically enables RSS output for the home page by default. You can also enable it for section pages in your `hugo.toml`:
+
+```toml
+[outputs]
+  home    = ["html", "rss"]
+  section = ["html", "rss"]
+```
+
+### Validating
+
+Once your site is live, validate the feed at [https://validator.w3.org/feed/](https://validator.w3.org/feed/).
+
+---
+
 ## CSS Theming
 
 The player renders in a Shadow DOM with a default dark theme. The external stylesheet provides a light theme that activates automatically. Both are fully customizable via CSS custom properties defined on `<podcast-player>` and `<podcast-footer>`.
@@ -416,8 +494,10 @@ assets/
   js/sources.js             # Re-exports for test imports
   demo/demo-audio.wav       # Demo audio file for the example site
 layouts/
+  _default/
+    rss.xml                   # Podcast RSS template (auto-detects podcast config)
   _shortcodes/
-    podcast-player.html     # Hugo shortcode template
+    podcast-player.html       # Hugo shortcode template
 tests/
   hugo/                     # Go integration tests (builds Hugo sites per case)
   js/                       # Vitest unit tests (80)

assets/js/code-copy.js

@@ -0,0 +1,59 @@
+// Add copy-to-clipboard buttons to all code blocks on the page.
+// Targets Hugo's .highlight wrapper (Chroma syntax highlighting).
+// Falls back to document.execCommand for older browsers.
+(function () {
+  'use strict';
+
+  document.querySelectorAll('.highlight').forEach(function (el) {
+    var btn = document.createElement('button');
+    btn.className = 'code-copy-btn';
+    btn.type = 'button';
+    btn.title = 'Copy code';
+    btn.innerHTML =
+      '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">' +
+      '<rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>' +
+      '<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>' +
+      '</svg>';
+
+    btn.addEventListener('click', function () {
+      // Extract text: if Hugo generated line numbers (table layout) the
+      // code lives in td:last-child, otherwise the first <code> element.
+      var code = el.querySelector('td:last-child code');
+      if (!code) code = el.querySelector('code');
+      var text = code ? code.textContent : el.textContent;
+
+      if (navigator.clipboard && navigator.clipboard.writeText) {
+        navigator.clipboard.writeText(text).then(function () {
+          showCopied(btn);
+        }).catch(function () {
+          fallbackCopy(btn, text, el);
+        });
+      } else {
+        fallbackCopy(btn, text, el);
+      }
+    });
+
+    el.insertBefore(btn, el.firstChild);
+  });
+
+  function showCopied(btn) {
+    btn.classList.add('copied');
+    btn.title = 'Copied!';
+    setTimeout(function () {
+      btn.classList.remove('copied');
+      btn.title = 'Copy code';
+    }, 2000);
+  }
+
+  function fallbackCopy(btn, text, container) {
+    var ta = document.createElement('textarea');
+    ta.value = text;
+    ta.style.position = 'fixed';
+    ta.style.left = '-9999px';
+    container.appendChild(ta);
+    ta.select();
+    try { document.execCommand('copy'); } catch (e) {}
+    container.removeChild(ta);
+    showCopied(btn);
+  }
+})();

exampleSite/content/_index.md

@@ -11,4 +11,7 @@ buttons:
   - text: "Schedule"
     url: "/schedule/"
     class: ""
+  - text: "<svg viewBox=\"0 0 24 24\" width=\"16\" height=\"16\" fill=\"currentColor\" style=\"vertical-align:middle;margin-right:2px\"><path d=\"M6.18 15.64a2.18 2.18 0 0 1 2.18 2.18C8.36 19 7.38 20 6.18 20C5 20 4 19 4 17.82a2.18 2.18 0 0 1 2.18-2.18M4 4.44A15.56 15.56 0 0 1 19.56 20h-2.83A12.73 12.73 0 0 0 4 7.27V4.44m0 5.66a9.9 9.9 0 0 1 9.9 9.9h-2.83A7.07 7.07 0 0 0 4 12.93V10.1Z\"/></svg>RSS Feed"
+    url: "/index.xml"
+    class: ""
 ---

exampleSite/content/episodes/rss-demo.md

@@ -0,0 +1,118 @@
+---
+title: "Introduction to Wavecast RSS Feeds"
+program: "Wavecast Demo"
+episode: "S1E1"
+date: 2026-06-01
+tags: [Wavecast, Hugo, Podcasting, RSS]
+podcast:
+  src: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3"
+  poster: "https://picsum.photos/seed/wavecast-rss/400/400"
+  chapters: "00:00:00-Intro,00:00:30-How It Works,00:01:20-Episode Front Matter,00:02:10-Channel Config,00:02:45-Validating the Feed"
+  type: "audio/mpeg"
+  duration: "00:03:45"
+  season: 1
+  episode: 1
+  explicit: false
+  author: "Wavecast Radio"
+  guid: "wavecast-demo-s1e1"
+  episodeType: "full"
+  subtitle: "Learn how Wavecast generates iTunes-compatible podcast RSS feeds from Hugo content."
+show_notes:
+  - "[W3C Feed Validator](https://validator.w3.org/feed/): validate your RSS feed before submitting to directories"
+  - "[Apple Podcasts Connect](https://podcastsconnect.apple.com/): submit your podcast to Apple Podcasts"
+  - "[Hugo RSS Templates](https://gohugo.io/templates/rss/): Hugo's official RSS template documentation"
+attribution:
+  text: "Wavecast RSS Demo"
+  url: "https://github.com/adurrr/wavecast"
+---
+
+This episode demonstrates how Wavecast automatically generates
+iTunes-compatible podcast RSS feeds when you configure
+`[params.podcast]` in your Hugo site config.
+
+## How It Works
+
+Wavecast ships `layouts/_default/rss.xml`, a single template that handles both
+standard blogs and podcast feeds. At build time, the template checks your
+`[params.podcast]` config:
+
+<div class="info-card" style="margin:1.5rem 0">
+
+**Detection rules:**
+
+| Condition                                | Behaviour                                            |
+|------------------------------------------|------------------------------------------------------|
+| `[params.podcast]` has `author`, `image`, or `description` | Renders a **full iTunes podcast RSS** feed (with `itunes:` namespace, categories, owner, artwork) |
+| `[params.podcast]` is missing or empty   | Renders a **plain RSS 2.0** feed suitable for blogs   |
+| Page has `podcast.src` in its front matter | Included as an `<item>` with an `<enclosure>` element |
+| Page has no `podcast.src`                | Skipped entirely (not a podcast episode)             |
+
+</div>
+
+There is no toggle or flag to set. If your site config defines podcast metadata,
+you get a podcast feed. If it does not, you get a blog feed. Both work from the
+same single template.
+
+Episodes with a local audio file (e.g. `src: "audio/episode.mp3"`) get their
+`<enclosure>` file size auto-resolved via Hugo resources. Remote URLs default to
+`length="0"`, which is valid RSS and accepted by all major podcast directories.
+
+## Episode Front Matter
+
+All iTunes-specific fields live under the `podcast:` key in your episode's
+YAML front matter:
+
+```yaml
+podcast:
+  src: "https://example.com/audio/ep42.mp3"   # required
+  type: "audio/mpeg"                           # MIME type
+  duration: "00:45:00"                         # HH:MM:SS or seconds
+  season: 2                                    # season number
+  episode: 42                                  # episode number
+  explicit: false                              # "true" or "false"
+  author: "Guest Host"                         # overrides site-level
+  guid: "unique-ep-42"                         # falls back to permalink
+  episodeType: "full"                          # full|trailer|bonus
+  subtitle: "A short episode teaser"           # max 255 chars
+  summary: "Full episode description"          # max 4000 chars
+```
+
+Standard Hugo fields (`title`, `date`, `tags`, `summary`) are pulled from
+the regular front matter automatically.
+
+## Channel Configuration
+
+Site-level podcast metadata goes in your `hugo.toml`:
+
+```toml
+[params.podcast]
+  author = "Your Name"
+  image  = "/podcast-cover.jpg"   # min 1400x1400px recommended
+  description = "A weekly show about open-source."
+  explicit = false
+  type     = "episodic"           # "episodic" or "serial"
+  owner_name  = "Your Name"
+  owner_email = "you@example.com"
+
+  [[params.podcast.categories]]
+    category = "Technology"
+```
+
+## Validating the Feed
+
+Once your site is live, validate your feed:
+
+1. Visit [validator.w3.org/feed](https://validator.w3.org/feed/)
+2. Enter your site's feed URL (usually `/index.xml`)
+3. Fix any warnings before submitting to directories
+
+The feed is ready for **Apple Podcasts**, **Spotify**, **Google Podcasts**,
+and any RSS-compatible podcast app.
+
+<div class="nav-buttons" style="margin-top:1.5rem">
+  <a href="/wavecast/index.xml" class="nav-button nav-button-primary" target="_blank" rel="noopener">
+    <svg viewBox="0 0 24 24" width="16" height="16" fill="currentColor" style="vertical-align:middle"><path d="M6.18 15.64a2.18 2.18 0 0 1 2.18 2.18C8.36 19 7.38 20 6.18 20C5 20 4 19 4 17.82a2.18 2.18 0 0 1 2.18-2.18M4 4.44A15.56 15.56 0 0 1 19.56 20h-2.83A12.73 12.73 0 0 0 4 7.27V4.44m0 5.66a9.9 9.9 0 0 1 9.9 9.9h-2.83A7.07 7.07 0 0 0 4 12.93V10.1Z"/></svg>
+    View RSS Feed
+  </a>
+  <a href="https://validator.w3.org/feed/" target="_blank" rel="noopener" class="nav-button">Validate Feed</a>
+</div>

exampleSite/hugo.toml

@@ -14,10 +14,29 @@ ignoreLogs = ["warning-goldmark-raw-html"]
   [[module.imports]]
     path = "github.com/adurrr/wavecast"
 
-# Site-wide description
+# ── RSS / Podcast feed ──
+# Configuring [params.podcast] enables an iTunes-compatible podcast RSS
+# feed.  Omit the whole section for a plain RSS 2.0 feed.
+[params.podcast]
+  description = "Wavecast Radio brings you the best in tech podcasting, from Infrastructure as Code to open-source culture and modern DevOps practices."
+  author = "Wavecast Radio"
+  summary  = "A demo podcast showcasing the Hugo Wavecast theme. Each episode features a full persistent audio player, chapter markers, and episode notes — all powered by standard Markdown front matter."
+  image    = "/wavecast/logo.png"
+  explicit = false
+  type     = "episodic"
+  owner_name  = "Wavecast Demo"
+  owner_email = "demo@wavecast.example"
+  language = "en-us"
+  copyright = "© 2025 Wavecast Radio"
+
+  [[params.podcast.categories]]
+    category = "Technology"
+  [[params.podcast.categories]]
+    category = "Leisure"
+    subcategory = "Hobbies"
+
 [params]
   description = "Wavecast Radio: Tune in to Tech. A demo radio station showcasing the Wavecast persistent podcast-player Web Component for Hugo."
-
   [params.podcastPlayer]
     source = "local"
     persistent = true

exampleSite/layouts/_default/baseof.html

@@ -14,6 +14,10 @@
   <link rel="manifest" href="{{ "site.webmanifest" | relURL }}">
   {{ $turbolinks := resources.Get "js/vendor/turbolinks.js" | fingerprint }}
   <script src="{{ $turbolinks.RelPermalink }}" integrity="{{ $turbolinks.Data.Integrity }}"></script>
+  {{- $codeCopy := resources.Get "js/code-copy.js" -}}
+  {{- if $codeCopy }}
+  <script src="{{ $codeCopy.RelPermalink }}" defer></script>
+  {{- end }}
   {{- /* Always load podcast-player CSS so the persistent footer has theme support on every page */ -}}
   {{- $playerCSS := resources.Get "css/podcast-player.css" -}}
   {{- if $playerCSS }}
@@ -110,6 +114,26 @@
     td a{color:var(--accent);text-decoration:none;font-weight:500}
     td a:hover{text-decoration:underline}
 
+    /* ── Content typography ── */
+    main h2{font-size:1.35rem;font-weight:700;margin:1.5rem 0 0.5rem}
+    main h3{font-size:1.1rem;font-weight:600;margin:1rem 0 0.25rem}
+    main p{margin-bottom:0.75rem}
+    main pre{margin:1rem 0;overflow-x:auto;padding-left:0.75rem}
+    main ul,main ol{margin:0.5rem 0 0.75rem;padding-left:1.25rem}
+    main li{margin-bottom:0.25rem}
+    main table{width:100%;border-collapse:collapse;font-size:0.85rem;margin:1rem 0}
+    main th{font-weight:700;text-align:left;padding:0.4rem 0.6rem;border-bottom:2px solid var(--border)}
+    main td{padding:0.35rem 0.6rem;border-bottom:1px solid var(--border)}
+
+    /* ── Code copy button ── */
+    .highlight{position:relative}
+    .highlight .code-copy-btn{visibility:hidden;position:absolute;top:0;right:0;z-index:10;display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;cursor:pointer;background:var(--surface);border:1px solid var(--border);border-radius:0 var(--radius) 0 var(--radius);color:var(--text-muted);opacity:0;transition:opacity .15s,visibility .15s}
+    .highlight:hover .code-copy-btn,.highlight .code-copy-btn:focus-visible{visibility:visible;opacity:1}
+    .highlight .code-copy-btn:hover{background:var(--accent);border-color:var(--accent);color:#fff}
+    .highlight .code-copy-btn.copied{background:var(--accent);border-color:var(--accent);color:#fff}
+    .highlight .code-copy-btn.copied svg{display:none}
+    .highlight .code-copy-btn.copied::after{content:"Copied!";font-size:0.65rem;font-weight:600;white-space:nowrap}
+
     /* ── Links (content areas) ── */
     main a{color:var(--accent);text-decoration:underline;text-decoration-color:color-mix(in srgb,var(--accent) 25%,transparent);text-underline-offset:2px;transition:text-decoration-color .15s}
     main a:hover{text-decoration-color:var(--accent)}
@@ -123,6 +147,12 @@
     .footer-nav a{color:var(--text-muted);text-decoration:none;font-size:0.85rem;transition:color .15s}
     .footer-nav a:hover{color:var(--accent)}
 
+    /* ── Episode nav ── */
+    .episode-nav{gap:0.6rem}
+    .episode-nav .nav-button{max-width:100%;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+    .episode-nav-back{font-size:0.85rem;border-style:dashed}
+    @media(max-width:640px){.episode-nav{flex-direction:column;align-items:stretch}.episode-nav .nav-button{justify-content:flex-start}}
+
     /* ── Responsive ── */
     @media(max-width:640px){
       .hero h1{font-size:1.5rem}
@@ -169,6 +199,7 @@
         <a href="{{ "schedule.md" | relref . }}">Schedule</a>
         <a href="{{ "about.md" | relref . }}">About</a>
         <a href="{{ "contact.md" | relref . }}">Contact</a>
+        <a href="{{ "index.xml" | relURL }}"><svg viewBox="0 0 24 24" width="14" height="14" fill="currentColor" style="vertical-align:middle;margin-right:3px"><path d="M6.18 15.64a2.18 2.18 0 0 1 2.18 2.18C8.36 19 7.38 20 6.18 20C5 20 4 19 4 17.82a2.18 2.18 0 0 1 2.18-2.18M4 4.44A15.56 15.56 0 0 1 19.56 20h-2.83A12.73 12.73 0 0 0 4 7.27V4.44m0 5.66a9.9 9.9 0 0 1 9.9 9.9h-2.83A7.07 7.07 0 0 0 4 12.93V10.1Z"/></svg>RSS</a>
         <a href="https://github.com/adurrr/wavecast" target="_blank" rel="noopener">GitHub</a>
       </div>
       <p>Wavecast Radio: Tune in to Tech. Powered by <a href="https://github.com/adurrr/wavecast" target="_blank" rel="noopener">Wavecast</a>, built with Hugo.</p>

exampleSite/layouts/episodes/single.html

@@ -15,7 +15,8 @@
 
   {{- $program := .Params.program -}}
   {{- $programPage := .Site.GetPage (printf "programs/%s" ($program | urlize)) -}}
-  {{- $programUrl := cond (ne $programPage nil) $programPage.RelPermalink .Site.Home.RelPermalink -}}
+  {{- $programUrl := .Site.Home.RelPermalink -}}
+  {{- if and $programPage $programPage.RelPermalink }}{{ $programUrl = $programPage.RelPermalink }}{{ end -}}
 
   <section class="hero">
     <h1>{{ .Title }}</h1>