Wavecast Radio

Wavecast can be used in two ways. Choose the one that fits your project.

Prerequisites

  • Hugo v0.146.0 or later
  • Go 1.23 or later (only if using the module install path)

Option A: Install as a Hugo Theme

Recommended for most sites. Clone Wavecast into your themes/ directory:

git clone git@github.com:adurrr/wavecast.git themes/wavecast

Then add to your site’s hugo.toml:

theme = "wavecast"

That’s it. Hugo automatically discovers the shortcode (layouts/_shortcodes/podcast-player.html), JS (assets/js/podcast-player.js), and CSS (assets/css/podcast-player.css) from the theme directory.

Option B: Install as a Hugo Module

If you’re already using Hugo modules or need to compose Wavecast with other modules:

hugo mod init github.com/yourusername/your-site
hugo mod get github.com/adurrr/wavecast

Then in your site’s hugo.toml:

[module]
  [[module.imports]]
    path = "github.com/adurrr/wavecast"

Hugo resolves the module and makes the shortcode, JS, and CSS available automatically.

Which Option Should I Choose?

You want…Use
Simple setup, one themeTheme (theme = "wavecast")
To use Wavecast alongside other modulesModule ([module.imports])
To override Wavecast’s templates in your own projectTheme (Hugo’s theme cascade handles overrides)
Pinned, reproducible buildsEither: both support version pinning
No git submodule or clone in your repoModule (hugo mod get)

Choose a Navigation Framework

Wavecast’s <podcast-footer> survives page navigation only if a framework that respects data-turbo-permanent / data-turbolinks-permanent / hx-preserve is loaded. This is a separate step from installing Wavecast.

Pick one and follow the snippet in Homepage Setup → Framework Attributes:

  • htmx — ~14 KB, no dependencies, drop-in.
  • Turbo — ~22 KB, requires <script type="module"> and may conflict with other module scripts.
  • Turbolinks 5 — vendored in assets/js/vendor/turbolinks.js, but is in maintenance mode; prefer htmx or Turbo for new projects.

If your theme already loads one of these (some Hugo themes ship with Turbolinks), no extra step is needed.

Local Development / Demo

Clone the repo and run the included example site:

git clone git@github.com:adurrr/wavecast.git
cd wavecast/exampleSite
hugo server --port 1313

Open your browser to the URL shown in the server output (e.g. http://localhost:1313/wavecast/). The first demo player uses a local .wav file so it works immediately with no external dependencies.

Verify Installation

After installing, check that the shortcode is recognized:

cd wavecast/exampleSite
hugo server --port 1313

Create a test page and add a podcast-player shortcode. If the player renders, you’re all set.

Edit this page on GitHub