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:

• https://rubygems.org/gems/jekyll-livid

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 Bdkgc6Wvujvh %}

With parameters

{% livid Bdkgc6Wvujvh autoplay=true muted=true loop=true %}
{% livid Bdkgc6Wvujvh color=ff0000 controls=false %}
{% livid Bdkgc6Wvujvh dnt=true %}
{% livid Bdkgc6Wvujvh 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

• https://jasonchance.com/projects/jekyll-livid/

Development

Install dependencies:

bundle install

Run tests:

ruby -Ilib -Itest test/livid_tag_test.rb

License

MIT