jekyll-livid

A Jekyll plugin that provides a {% livid %} Liquid tag for embedding Livid-hosted videos with a responsive iframe wrapper and full support for advanced embedding parameters.

Scope

This plugin is intentionally narrow. It handles one thing: embedding Livid videos cleanly in Jekyll templates with a minimal, standards-compliant iframe output.

Who this is for

  • Jekyll site owners who host video on Livid
  • Anyone migrating from Vimeo to Livid who wants drop-in embed support
  • Developers who want fine-grained control over player behavior via URL parameters

Features

  • {% livid VIDEO_ID %} tag with responsive 16:9 iframe wrapper
  • Full support for all Livid advanced embedding parameters
  • #t= hash fragment support for timestamp-based start positions
  • Unknown parameter warnings via Jekyll logger (skipped silently in output)
  • Lazy-loading iframe by default

GitHub Pages compatibility

This plugin is compatible with Jekyll sites deployed to GitHub Pages when the site is built through a custom GitHub Actions workflow.

It is not compatible with the default GitHub Pages safe-mode build, which does not load custom plugins.

Installation

Published on RubyGems:

Add the gem to your Gemfile:

gem "jekyll-livid", "~> 0.1.0"

Then add it to _config.yml:

plugins:
  - jekyll-livid

Run:

bundle install

Styling

The plugin outputs a wrapper div with the class livid-embed. No spacing or layout styles are applied — this is intentional, since every site has its own typographic rhythm and spacing scale.

If the embed sits too close to the content below it, add a rule to your site's CSS or SCSS:

.livid-embed {
  margin-bottom: 32px; /* adjust to match your site's heading/paragraph spacing */
}

Usage

Basic embed

{% livid CEm15HFpXlBO %}

With parameters

{% livid CEm15HFpXlBO autoplay=true muted=true loop=true %}
{% livid CEm15HFpXlBO color=ff0000 controls=false %}
{% livid CEm15HFpXlBO dnt=true %}
{% livid CEm15HFpXlBO t=30 %}

The t parameter starts playback at a specific second and is appended as a URL hash fragment (#t=30). All other parameters are appended as query string parameters.

Advanced embedding parameters

All parameters from the Livid advanced embedding documentation are supported. Boolean parameters accept true/false or 1/0.

Parameter Values Default Notes
airplay true/false true AirPlay support (Safari only). Pro/Premium accounts.
autoplay true/false false Autostart playback.
background true/false false Background mode: no controls, loops, autoplay, muted. Pro/Premium.
cc true/false true Closed captions button. Pro/Premium.
chromecast true/false true Chromecast button. Pro/Premium.
color hex code 4e48f9 Player control color (no #). Pro/Premium.
colors 1–4 hex codes, comma-separated — Button, accent, icon/text, background. Pro/Premium.
controls true/false true Show/hide all player controls. Pro/Premium.
custom_logo true/false — Show custom logo. Pro/Premium.
dnt true/false false Do Not Track — disables analytics. All videos.
fullscreen true/false true Fullscreen button. Pro/Premium.
keyboard true/false true Keyboard controls. All videos.
livid_logo true/false true Show Livid logo. Pro/Premium.
loop true/false false Loop the video. All videos.
max_quality 240p–4k auto Maximum quality ceiling. Pro/Premium.
min_quality 240p–4k auto Minimum quality floor. Pro/Premium.
muted true/false false Mute on load. All videos.
pip true/false true Picture-in-picture button. Pro/Premium.
play_button_position auto/bottom/center auto Play button position. Pro/Premium.
playsinline true/false true Inline playback on mobile. All videos.
preload auto/metadata/none none Pre-playback loading behavior. All videos.
progress_bar true/false true Progress bar. Pro/Premium.
quality_selector true/false true Quality selector menu. Pro/Premium.
share true/false true Share button. Pro/Premium.
speed true/false true Speed controls. Pro/Premium.
t seconds 0 Start at timestamp (appended as #t=N). All videos.
title true/false true Show video title. Pro/Premium.
transparent true/false true Transparent iframe background. All videos.
volume true/false true Volume control. Pro/Premium.

Live example

Development

Install dependencies:

bundle install

Run tests:

ruby -Ilib -Itest test/livid_tag_test.rb

License

MIT