feat: control footer URL via shortcode url param (#64) (#67)

The persistent footer's source label is upgraded from plain text to a
clickable link. A new url shortcode parameter on podcast-player
controls the link: an explicit URL overrides the auto-derived link,
"none" hides the link, and omitting it auto-derives the link from the
audio src by stripping the filename. The same attribute can be set on
the top-level <podcast-footer url="..."> to override what the inline
player sends. URLs are sanitized at build time
(http/https/relative/fragment/dot-relative, plus "none") and at
runtime (http/https only).

Co-authored-by: Adur <adurrr@users.noreply.github.com>

Author: adurrr

CHANGELOG.md

@@ -20,6 +20,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   active (helps diagnose "footer disappears on navigation" issue).
 - Footer player horizontally scrolls long episode titles when they overflow,
   with a `prefers-reduced-motion: reduce` fallback to ellipsis (#63).
+- `url` shortcode parameter on `podcast-player` controls the footer
+  source link: a URL makes the label clickable, `"none"` hides it,
+  omitted auto-derives from the audio source (#64).
 
 ## [1.3.0] - 2026-06-16
 

assets/js/podcast-player.js

@@ -157,7 +157,7 @@ class PodcastPlayer extends HTMLElement {
   /** Attributes the component should react to. */
   static get observedAttributes() {
     return ["src", "title", "poster", "chapters", "type", "autoplay",
-      "data-preload", "persistent", "data-source"];
+      "data-preload", "persistent", "data-source", "url"];
   }
 
   /** Prefix for sessionStorage state key (instance ID appended). */
@@ -906,7 +906,7 @@ class PodcastPlayer extends HTMLElement {
         src: this._audio.src || this.getAttribute("src") || "",
         title: this.getAttribute("title") || "",
         poster: this.getAttribute("poster") || "",
-        url: this._audio.src || "",
+        url: this._resolveUrl(),
         currentTime: this._audio.currentTime,
       },
     }));
@@ -1329,6 +1329,40 @@ class PodcastPlayer extends HTMLElement {
     return `${m}:${pad(s)}`;
   }
 
+  /**
+   * Resolve the URL to use for the footer's source link.
+   * Priority: explicit `url` attribute (or "none" sentinel) > auto-derive from src.
+   * Auto-derivation strips the filename from the audio src.
+   * Returns:
+   *   - "none" when the user explicitly opted out
+   *   - an absolute http(s) URL string when a usable link can be determined
+   *   - "" when no usable URL can be determined (caller should hide the link)
+   */
+  _resolveUrl() {
+    const explicit = (this.getAttribute("url") || "").trim();
+    if (explicit.toLowerCase() === "none") return "none";
+    if (explicit) {
+      // Resolve relative URLs against the document base.
+      try {
+        return new URL(explicit, document.baseURI).href;
+      } catch (_) {
+        return "";
+      }
+    }
+    // Auto-derive from audio src.
+    const src = this._audio.src || this.getAttribute("src") || "";
+    if (!src) return "";
+    try {
+      const u = new URL(src, document.baseURI);
+      if (u.protocol !== "http:" && u.protocol !== "https:") return "";
+      // Strip filename, keep path up to last "/"
+      const lastSlash = u.href.lastIndexOf("/");
+      return lastSlash >= 0 ? u.href.substring(0, lastSlash + 1) : u.href;
+    } catch (_) {
+      return "";
+    }
+  }
+
   /** Highlight the currently playing chapter. */
   _updateActiveChapter() {
     const t = this._audio.currentTime;
@@ -1472,6 +1506,7 @@ class PodcastFooter extends HTMLElement {
       player_no_source: "No audio source available",
       player_close: "Close player",
       player_unknown_episode: "Unknown Episode",
+      player_source_link: "View episode",
     };
   }
 
@@ -1585,6 +1620,61 @@ class PodcastFooter extends HTMLElement {
     }
   }
 
+  /**
+   * Apply a URL to the footer's source link element, or hide it.
+   *   url === "none"          → hide the link entirely
+   *   url is empty/invalid    → hide the link (and clear href)
+   *   url is a valid http(s) URL → set the href, make the link visible
+   * The element is a real `<a>`, not a `<div>`, so the href is set directly.
+   * Sanitization: only http(s) protocols are accepted. Anything else
+   * (javascript:, data:, ftp:, malformed) results in the link being hidden.
+   * The most recently accepted URL is cached on `this._currentSourceUrl`
+   * so persistence (save/restore) round-trips the same value the user sees.
+   *
+   * Note: the link is only revealed if it already has text content. This
+   * prevents a top-level `<podcast-footer url="...">` attribute from
+   * flashing an empty link before any inline player has dispatched a
+   * podcast-play event.
+   */
+  _setSourceLink(url) {
+    const link = this._els.source;
+    if (!link) return;
+
+    if (typeof url === "string" && url.toLowerCase() === "none") {
+      link.hidden = true;
+      link.removeAttribute("href");
+      this._currentSourceUrl = "";
+      return;
+    }
+    if (!url) {
+      link.hidden = true;
+      link.removeAttribute("href");
+      this._currentSourceUrl = "";
+      return;
+    }
+    try {
+      const u = new URL(url, document.baseURI);
+      if (u.protocol !== "http:" && u.protocol !== "https:") {
+        link.hidden = true;
+        link.removeAttribute("href");
+        this._currentSourceUrl = "";
+        return;
+      }
+      link.href = u.href;
+      this._currentSourceUrl = u.href;
+      // Only reveal if the link has visible text (set by a podcast-play
+      // event). The footer renders no source label before a track starts.
+      if (link.textContent && link.textContent.trim()) {
+        link.hidden = false;
+        link.setAttribute("aria-label", this._t("player_source_link"));
+      }
+    } catch (_) {
+      link.hidden = true;
+      link.removeAttribute("href");
+      this._currentSourceUrl = "";
+    }
+  }
+
   /** Set the mute button icon based on current muted/volume state. */
   _setMuteIcon() {
     if (this._audio.muted || this._audio.volume === 0) {
@@ -1615,6 +1705,31 @@ class PodcastFooter extends HTMLElement {
     this._titleResizeObserver = null;
   }
 
+  /** Attributes the component should react to. The `url` attribute lets a
+   *  page override whatever the inline player sent (e.g. wrap the footer's
+   *  source label in a clickable link to a specific episode page). The
+   *  override applies whether the attribute is present at parse time or
+   *  changed at runtime via JavaScript. */
+  static get observedAttributes() {
+    return ["url"];
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue === newValue) return;
+    if (name === "url") {
+      // Cache the override so a later podcast-play event can prefer it
+      // over the inline player's URL. If the footer is already showing
+      // a source, apply immediately too.
+      this._topLevelUrlOverride = (newValue != null) ? newValue : null;
+      if (this._els && this._els.source) {
+        const link = this._els.source;
+        if (link.textContent && link.textContent.trim()) {
+          this._setSourceLink(newValue || "");
+        }
+      }
+    }
+  }
+
   /* ---- Shadow DOM template ---- */
 
   _render() {
@@ -1674,7 +1789,13 @@ class PodcastFooter extends HTMLElement {
           }
         }
         .source { font-size: .7rem; color: var(--podcast-player-text-muted, #888);
-                   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+                   white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+                   text-decoration: none; cursor: pointer; }
+        .source:hover { color: var(--podcast-player-text, #e0e0e0);
+                        text-decoration: underline; }
+        .source:focus-visible { outline: 2px solid var(--podcast-player-accent, #7c3aed);
+                                outline-offset: 2px; }
+        .source[hidden] { display: none; }
         .controls { display: flex; align-items: center; gap: 2px; flex-shrink: 0; }
         .btn {
           background: transparent; border: none; color: var(--podcast-player-text, #e0e0e0);
@@ -1757,7 +1878,7 @@ class PodcastFooter extends HTMLElement {
         <img class="cover" part="cover" src="" alt="" hidden>
         <div class="info">
           <div class="title" part="title"><span class="title-text"></span></div>
-          <div class="source" part="source"></div>
+          <a class="source" part="source" hidden></a>
         </div>
         <div class="controls">
           <button class="btn btn-skip-back" part="skip-back-btn"
@@ -1866,6 +1987,13 @@ class PodcastFooter extends HTMLElement {
     // New source — load and play
     this._els.titleText.textContent = title || this._t("player_unknown_episode");
     this._els.source.textContent = src.replace(/^https?:\/\//, "").split("/")[0] || src;
+    // Top-level <podcast-footer url="..."> always overrides what the inline
+    // player sent via the event detail.
+    const eventUrl = (e.detail && e.detail.url) || "";
+    const finalUrl = (this._topLevelUrlOverride != null)
+      ? this._topLevelUrlOverride
+      : eventUrl;
+    this._setSourceLink(finalUrl);
 
     if (poster) {
       this._els.cover.src = poster;
@@ -2120,6 +2248,7 @@ class PodcastFooter extends HTMLElement {
         timestamp:    Date.now(),
         title:        this._els.title.textContent,
         poster:       this._els.cover.getAttribute("src") || "",
+        url:          this._currentSourceUrl || "",
       };
       sessionStorage.setItem(PodcastFooter.PERSISTENCE_KEY, JSON.stringify(state));
     } catch (_) {}
@@ -2153,6 +2282,13 @@ class PodcastFooter extends HTMLElement {
       this._els.rateBtn.textContent = (state.playbackRate || 1) + "×";
       this._els.titleText.textContent = state.title || this._t("player_unknown_episode");
       this._els.source.textContent = state.src.replace(/^https?:\/\//, "").split("/")[0] || state.src;
+      // Top-level <podcast-footer url="..."> override (set in HTML or at
+      // runtime) takes precedence over the URL persisted from a prior
+      // session.
+      const restoreUrl = (this._topLevelUrlOverride != null)
+        ? this._topLevelUrlOverride
+        : (state.url || "");
+      this._setSourceLink(restoreUrl);
 
       if (state.poster) {
         this._els.cover.src = state.poster;

exampleSite/content/docs/getting-started.md

@@ -44,6 +44,7 @@ After installing Wavecast, add a podcast player to any page with a single shortc
 |-----------|----------|---------|-------------|
 | `src` | **yes** |: | Audio URL or local file path |
 | `title` | no | `""` | Episode title in the player header |
+| `url` | no | `""` | Link target for the footer source label. Set to a URL (http/https or site-relative) to make the label clickable, or `"none"` to hide the link. Omit to auto-derive from the audio source. |
 | `poster` | no | `""` | Cover image URL |
 | `description` | no | `""` | Markdown description |
 | `type` | no | `"audio/mpeg"` | MIME type |

exampleSite/content/docs/homepage-setup.md

@@ -123,6 +123,30 @@ title automatically scrolls horizontally so the full text is visible. Short
 titles render normally with no animation. The behavior respects
 `prefers-reduced-motion: reduce`, which falls back to ellipsis truncation.
 
+## Linking the Footer
+
+The persistent footer shows a small source label (the audio host's domain) below the episode title. By default this label is a link to the audio file's parent directory. The `url` shortcode parameter overrides or hides the link:
+
+- Omitted, auto-derived: the link points at the audio file's parent directory (e.g. `src="https://example.com/episodes/foo.mp3"` makes the link `https://example.com/episodes/`).
+- A URL: the link points at that URL instead. Accepts `http://`, `https://`, and site-relative paths starting with `/`, `#`, or `.`.
+- `"none"`: the link is hidden entirely. Useful for live radio streams that have no episode page.
+
+```go-html-template
+{{</* podcast-player
+  src="https://example.com/stream.mp3"
+  title="Live Broadcast"
+  url="https://example.com/shows/live"
+*/>}}
+
+{{</* podcast-player
+  src="https://example.com/stream.mp3"
+  title="Live Broadcast"
+  url="none"
+*/>}}
+```
+
+The same attribute can be set on the top-level `<podcast-footer url="...">` to override whatever the inline player sends. URLs are sanitized at build time and at runtime; only `http` and `https` schemes are accepted when the link is rendered.
+
 ## Example: Full baseof.html Footer Section
 
 ```html

exampleSite/content/es/docs/getting-started.md

@@ -44,6 +44,7 @@ Después de instalar Wavecast, añade un reproductor de podcast a cualquier pág
 |-----------|----------|---------|-------------|
 | `src` | **sí** |: | URL de audio o ruta de archivo local |
 | `title` | no | `""` | Título del episodio en el reproductor |
+| `url` | no | `""` | Destino del enlace para la etiqueta de fuente del pie. Establece una URL (http/https o relativa al sitio) para hacer la etiqueta clickeable, o `"none"` para ocultar el enlace. Omite para derivar automáticamente desde la fuente de audio. |
 | `poster` | no | `""` | URL de la imagen de portada |
 | `description` | no | `""` | Descripción en Markdown |
 | `type` | no | `"audio/mpeg"` | Tipo MIME |

exampleSite/content/es/docs/homepage-setup.md

@@ -95,6 +95,30 @@ mostrar todo el texto. Los títulos cortos se renderizan normalmente sin
 animación. El comportamiento respeta `prefers-reduced-motion: reduce`, que
 cae de vuelta a truncamiento con elipsis.
 
+## Vincular el Pie
+
+El pie persistente muestra una pequeña etiqueta de fuente (el dominio del servidor de audio) bajo el título del episodio. Por defecto esta etiqueta es un enlace al directorio padre del archivo de audio. El parámetro `url` del shortcode sobrescribe u oculta el enlace:
+
+- Omitido, derivado automáticamente: el enlace apunta al directorio padre del archivo de audio (ej. `src="https://example.com/episodes/foo.mp3"` produce el enlace `https://example.com/episodes/`).
+- Una URL: el enlace apunta a esa URL. Acepta `http://`, `https://` y rutas relativas al sitio que empiecen por `/`, `#` o `.`.
+- `"none"`: el enlace se oculta por completo. Útil para transmisiones de radio en vivo sin página de episodio.
+
+```go-html-template
+{{</* podcast-player
+  src="https://example.com/stream.mp3"
+  title="Transmisión en vivo"
+  url="https://example.com/shows/live"
+*/>}}
+
+{{</* podcast-player
+  src="https://example.com/stream.mp3"
+  title="Transmisión en vivo"
+  url="none"
+*/>}}
+```
+
+El mismo atributo puede establecerse en el `<podcast-footer url="...">` de nivel superior para sobrescribir lo que envíe el reproductor en línea. Las URL se sanitizan en tiempo de compilación y de ejecución; solo se aceptan los esquemas `http` y `https` al renderizar el enlace.
+
 ## Ejemplo: Sección de Pie en baseof.html Completa
 
 ```

exampleSite/content/posts/url-hidden.md

@@ -0,0 +1,19 @@
+---
+title: "URL Hidden Demo"
+date: 2026-06-27T10:00:00+03:00
+draft: false
+---
+
+{{< podcast-player
+  src="https://www.soundhelix.com/examples/mp3/SoundHelix-Song-10.mp3"
+  title="Episode with footer link hidden"
+  url="none"
+>}}
+
+This page demonstrates the new `url="none"` shortcode parameter: the
+footer source label is hidden entirely (no link).
+
+<div class="nav-buttons">
+  <a href="{{< relref "posts/url-override.md" >}}" class="nav-button">Next: Override Demo</a>
+  <a href="{{< relref "/" >}}" class="nav-button nav-button-primary">Back to Home</a>
+</div>

exampleSite/content/posts/url-override.md

@@ -0,0 +1,19 @@
+---
+title: "URL Override Demo"
+date: 2026-06-27T10:00:00+03:00
+draft: false
+---
+
+{{< podcast-player
+  src="https://www.soundhelix.com/examples/mp3/SoundHelix-Song-9.mp3"
+  title="Episode with custom footer link target"
+  url="https://example.com/episodes/long-title-demo"
+>}}
+
+This page demonstrates the new `url` shortcode parameter: the footer
+source label is clickable and points at the URL above.
+
+<div class="nav-buttons">
+  <a href="{{< relref "posts/url-hidden.md" >}}" class="nav-button">Next: Hidden Link Demo</a>
+  <a href="{{< relref "/" >}}" class="nav-button nav-button-primary">Back to Home</a>
+</div>

exampleSite/i18n/es.toml

@@ -59,6 +59,9 @@ other = "No hay fuente de audio disponible"
 [player_unknown_episode]
 other = "Episodio desconocido"
 
+[player_source_link]
+other = "Ver episodio"
+
 # ── Carousel ──
 [carousel_label]
 other = "Carrusel de imágenes"

exampleSite/layouts/_default/baseof.html

@@ -185,6 +185,7 @@
     "player_seek" "player_cover_alt" "player_cover_of"
     "player_episode" "player_close" "player_region"
     "player_error" "player_no_source" "player_unknown_episode"
+    "player_source_link"
     "code_copy_title" "code_copy_label" "code_copied" "code_copied_label"
   -}}
   <script nonce="{{ $cspNonce }}">