How the Jekyll SEO plugin helps you optimize your site

By CloudCannon · 15 Nov 2021

How the Jekyll SEO plugin helps you optimize your site

SEO is a hot topic for Jekyll and static sites in general. WordPress has the famous Yoast plugin, which does a great job of helping you optimize a site's SEO. Jekyll has the Jekyll SEO tag plugin, which serves a similar purpose. In this showcase, we're diving into what this plugin does and how it works.

What does the Jekyll SEO plugin do?

The plugin is designed to work out-of-the-box with minimal configuration. It'll set your page title, description, Canonical URL, next and previous pages for paginated pages, JSON-LD structured data to help with indexing, Open Graph data for social networks, and Twitter summary card.

The installation is straightforward, simply include the Gem and add {% seo %} to the <head> in your layout. The plugin does a good job using front matter and configuration data you likely already have set to generate the SEO metadata. It'll pick up fields like title, description, image & author. For a complete list, check out the docs.

The result after a build is a block of metadata that looks something like this:

<!-- Begin Jekyll SEO tag v2.7.1 -->
<title>Bootstrap | Cloudcannon</title>
<meta name="generator" content="Jekyll v4.1.1" />
<meta property="og:title" content="Bootstrap" />
<meta property="og:locale" content="en_US" />
<meta name="description" content="Not only has Bootstrap helped millions of developers build websites, but their documentation is built using Hugo. Let’s dive in and deconstruct the Bootstrap documentation." />
<meta property="og:description" content="Not only has Bootstrap helped millions of developers build websites, but their documentation is built using Hugo. Let’s dive in and deconstruct the Bootstrap documentation." />
<link rel="canonical" href="https://cloudcannon.com/community/showcases/bootstrap/" />
<meta property="og:url" content="https://cloudcannon.com/community/showcases/bootstrap/" />
<meta property="og:site_name" content="Cloudcannon" />
<meta property="og:image" content="https://cloudcannon.com/community/uploads/showcases/bootstrap/bootstrap-hero.jpg" />
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2021-05-18T04:54:43+00:00" />
<meta name="twitter:card" content="summary_large_image" />
<meta property="twitter:image" content="https://cloudcannon.com/community/uploads/showcases/bootstrap/bootstrap-hero.jpg" />
<meta property="twitter:title" content="Bootstrap" />
<script type="application/ld+json">
{"image":"https://cloudcannon.com/community/uploads/showcases/bootstrap/bootstrap-hero.jpg","headline":"Bootstrap","dateModified":"2021-05-18T04:54:43+00:00","datePublished":"2021-05-18T04:54:43+00:00","@type":"BlogPosting","mainEntityOfPage":{"@type":"WebPage","@id":"https://cloudcannon.com/community/showcases/bootstrap/"},"description":"Not only has Bootstrap helped millions of developers build websites, but their documentation is built using Hugo. Let’s dive in and deconstruct the Bootstrap documentation.","url":"https://cloudcannon.com/community/showcases/bootstrap/","@context":"https://schema.org"}
</script>
<!-- End Jekyll SEO tag -->

All of that for one line of Liquid and some front matter you probably already have set. Yes please. Before this plugin existed, this needed to be generated by hand with Liquid. It was error-prone, complicated, and a nightmare to maintain. The Jekyll SEO tag plugin almost makes it too easy.

HTML output

Let's start by looking at how the HTML is generated. template.html is a file with simple HTML/Liquid that handles the bulk of the output. A small snippet is included here but if you want to dive deeper, take a look at the raw file:

<!-- Begin Jekyll SEO tag v{{ seo_tag.version }} -->
{% if seo_tag.title? %}
  <title>{{ seo_tag.title }}</title>
{% endif %}

<meta name="generator" content="Jekyll v{{ jekyll.version }}" />

{% if seo_tag.page_title %}
  <meta property="og:title" content="{{ seo_tag.page_title }}" />
{% endif %}

{% if seo_tag.author.name %}
  <meta name="author" content="{{ seo_tag.author.name }}" />
{% endif %}
<meta property="og:locale" content="{{ seo_tag.page_locale }}" />

There's nothing too crazy going on here. It's simply checking for particular variables and outputting them if they exist. Let's take a look at where these variables are initalized.

Liquid Drops

The bulk of the plugin is a series of Liquid Drops. You may have heard this term before, but what exactly are Liquid Drops? A Drop is similar to a Hash in Ruby. It's an object you can use within Liquid with potentially dangerous methods removed.

Let's take the image Drop. All it does is gets an image from a page's front matter and returns it as an image path. Most of the logic is ensuring the path is in a sane format. Here's a snippet of the file. Again, take a look at the raw file for a full view.

class ImageDrop < Jekyll::Drops::Drop
  include Jekyll::SeoTag::UrlHelper

  def initialize(page: nil, context: nil)
    raise ArgumentError unless page && context
    @mutations = {}
    @page = page
    @context = context
  end

  def path
    @path ||= filters.uri_escape(absolute_url) if absolute_url
  end

Authors and JSON-LD are also Drops built similarly. These are all used in the Jekyll SEO drop which calculates all the values for the Liquid file include the title:

def title
  @title ||= begin
    if site_title && page_title != site_title
      page_title + TITLE_SEPARATOR + site_title
    elsif site_description && site_title
      site_title + TITLE_SEPARATOR + site_tagline_or_description
    else
      page_title || site_title
    end
  end

  return page_number + @title if page_number

  @title
end

Description:

def description
  @description ||= begin
    format_string(page["description"] || page["excerpt"]) || site_description
  end
end

Image:

def image
  @image ||= ImageDrop.new(:page => page, :context => @context)
  @image if @image.path
end

and JSON-LD:

def json_ld
  @json_ld ||= JSONLDDrop.new(self)
end

Liquid Tag

Liquid tags are the logic of a Liquid template, including statements, loops, case statements, and more. In this case, the SEO tag ( {% seo %}) is a Liquid Tag. It's the final piece of the puzzle and what the user calls to include the SEO metadata.

The file is mostly setting up data for the Drops. It ends with registering the SEO tag for Liquid:

Liquid::Template.register_tag("seo",Jekyll::SeoTag)

Wrap up

The Jekyll SEO tag plugin is a must-have for any Jekyll site. It's usually the first plugin to install on any new Jekyll site. For more learning about Jekyll, try out this Jekyll tutorial to help with your next project.