I’m really happy with my new website! But I can’t embed Twitch clips. In fact, no one can embed Twitch clips in Jekyll, because there’s no liquid tag for it. But we can fix that, not just for us, but for everyone!
This article is the technical plan for a stream on Friday, 3/19 where I’ll create a new gem.
This project breaks down into 3 distinct problems:
- Creating a Jekyll Liquid Tag
- Embedding a Twitch Broadcast, Clip, or VOD
- Creating a Gem, and publishing it to Ruby Gems
Creating a Jekyll Liquid Tag
We’ll start with Jekyll’s guide to liquid tags. They say we should create a
TwitchTag class inside the
Jekyll module, and add a render method for the embeds. We also need to register the tag,
Liquid::Template.register_tag('twitch', Jekyll::TwitchTag), so Jekyll knows that it can use this tag.
Embedding a Twitch broadcast, clip, or VOD
Twitch allows you to embed clips, broadcasts, and VODs using several different embeds. They require that all embeds be served over SSL, and they want to know the parent domain.
Option 2 - This is a simple, non-interactive iframe for Twitch that works for VODs and Livestreams. The viewer will have to continue to Twitch to follow or subscribe. This will also work for clips if we customize the url.
Option 3 - This option asks you to embed the same script as option 1, but they’ve used the player instead of the embed. The documentation doesn’t make the differences clear.
I plan to start with option 2 because it’s simpler, and I need it for clips. Options 1 and 3 don’t support clips.
Here’s the super simple iFrame I’ll be embedding. For clips, the url is:
<iframe src="https://player.twitch.tv/?<channel, video, or collection>&parent=streamernews.example.com" height="<height>" width="<width>" allowfullscreen="<allowfullscreen>"> </iframe>
I’ve embedded this before for Forem, so I’m looking forward to improving it.
How to Create a Gem
Files I’ll need
- lib/twitch_tag.rb - this is going to handle formatting and rendering the twitch embed
- lib/spec/twitch_tag_spec.rb - this is where all our tests around the twitch embed will live.
Gems I’ll use
- RSpec This is my favorite testing gem. I love how readable and well-organized the tests are.
- RDoc We’ll use this gem to document our TwitchTag.rb class.
- Rubocop Just for fun, let’s add this one too. It’ll keep our styles consistent.
None of these gems will be dependencies. I can run them exclusively in development.
Let’s reuse the GitHub actions from last week. Then we’ll add a new one to run RSpec, and verify that tests pass.
Once I have the entire repository set up, and the gem built, I’ll want to add it to my own site.
Adding the Gem to chael.codes
The Jekyll docs say that GitHub pages excludes gems using the
--safe option, but they also say that you can skip that by including it in
jekyll-plugins. Let’s see if it works!