Building Jekyll-Twitch, the gem

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 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

Jekyll liquid tags allow you to embed user-generated content safely. You might be okay with letting your users embed youtube videos, but you don't want them executing random javascript on your website. Liquids are an extensible templating library designed by Shopify. You specify a tag type, and then pass your url or id, and the tag sanitizes it and embeds the content. {% twitch <clip url here> %}

Examples:

Jekyll-YouTube
Jekyll-Twitter
Jekyll-Gist (This one is maintained by Jekyll)

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 1 - Twitch offers an embed that includes chat, login, subscription, and everything normally available on the Twitch site. Unfortunately, it serves everything through JavaScript, and requires you to embed their script on your site.

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: https://clips.twitch.tv/embed?clip=<VeryLongClipTitle>&parent=streamernews.example.com

<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

We can create the gem using the same tool we use for managing versions: Bundler. Then, I plan to publish it on RubyGems. I'm really excited about this!

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.

CI/CD

Let's reuse the GitHub actions from last week.

Automatically Lint New PRs #1

ChaelCodes posted on Mar 12, 2021

Description of Problem

I want some quality control and consistency. If I don't have some sort of linter, I can't ensure that happens.

Technical Solution

• Run rubocop on every push using github actions.

View on GitHub

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. This did not work. GitHub Pages only supports their allow-listed plugins.

ChaelCodes / jekyll-twitch

Embed Twitch clips, VODs, and broadcasts in your Jekyll sites.

Jekyll::Twitch

This gem allows you to embed twitch channels, clips, collections, and videos in your Jekyll websites. It adds and registers a new twitch liquid tag that accepts a twitch clip, channel, broadcast, or highlight url. It's based on the Twitch video embeds.

{% twitch https://www.twitch.tv/chaelcodes/clip/SpoopySlipperyGrasshopperPogChamp %}

See the DEMO site

Check out the demo site for install instructions and to review different embed examples.

Installation

Add this line to your application's Gemfile:

gem 'jekyll-twitch'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install jekyll-twitch

Then add Jekyll-Twitch to your _config.yml like so:

plugins:
  - jekyll-twitch

Usage

This is a Jekyll liquid tag, so just put {% twitch https://www.twitch.tv/chaelcodes/clip/SpoopySlipperyGrasshopperPogChamp %} to embed your clip, channel, or broadcast.

When building your site, Jekyll no longer substitutes site.url for localhost, which means Twitch embeds will not render. You need to supply host and localhost to view…

View on GitHub