[benecaster_related_episodes]
Displays a list of related episodes based on the selected query strategy. Tier-aware — locked episodes render with a lock indicator rather than full content. Falls back to latest if the selected query type returns no results.
Query types are extensible via the benecaster_related_episodes_query_types filter. The resolved episode list is filterable via benecaster_related_episodes. Final HTML is filterable via benecaster_related_episodes_output.
Note: by_guest silently falls back to by_tag without Guest Manager active. by_season silently falls back to by_tag when the current episode has no season number assigned.
When the AI Search add-on is active, a by_semantic query type is available that uses vector similarity against the episode’s embedding to find thematically related episodes. Results are cached per episode with a configurable TTL (default: 1 week) — the API is called at indexing time, not per page load. When AI Search is not active, by_semantic is not registered, so the list falls back to latest.
Parameters
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
episode_id |
int |
(current episode)
|
No | Source episode for relationship queries |
show_id |
int |
(current show)
|
No | Which show to query |
query |
string |
by_tag
|
No | Query strategy. Built-in: by_tag, by_season, by_guest, latest. The AI Search add-on adds by_semantic when active. Additional types via the benecaster_related_episodes_query_types filter. |
count |
int |
5
|
No | Number of related episodes to display. 0 = all results. Every query type except latest searches the whole show, newest first. |
style |
string |
list
|
No | Display style: list (vertical episode list), grid (responsive card grid), cards (full episode cards with artwork) |
exclude_current |
bool |
true
|
No | Whether to exclude the current episode from results |
title |
string |
— | No | Optional heading rendered above the episode list (e.g. 'You might also like', 'More from this season'). Empty string suppresses the heading. Also configurable per-show in Settings → Show → Episode Page when the related_episodes block is enabled. |
Example
<!-- Default: by-tag related episodes, list style -->
[benecaster_related_episodes]
<!-- By season, cards style, 3 results -->
[benecaster_related_episodes query="by_season" count="3" style="cards"]
<!-- By guest, grid style (falls back to by_tag without Guest Manager) -->
[benecaster_related_episodes query="by_guest" style="grid"]
<!-- Latest episodes, specific show -->
[benecaster_related_episodes show_id="2" query="latest" count="6"]