Custom Ruby Plugins for Jekyll Development

Why Do You Need a Custom Jekyll Plugin?

Imagine a blog with 150 posts across 20 tags. Without a custom plugin, you would have to manually create an index.md for each tag. That's inefficient and error-prone. Jekyll is written in Ruby and provides a full-featured Jekyll Plugins API through plugins. Plugins are Ruby classes that hook into the site generation pipeline. They allow adding new Liquid tags, filters, page generators, format converters, and hooks. GitHub Pages does not run arbitrary plugins (only a whitelist), so using them requires your own CI/CD. We develop custom plugins turnkey: from idea to deployment with tests and documentation. Our engineers have 10+ years of experience with Ruby and Jekyll, ensuring stability and performance. Using custom plugins reduces build time by 40% and speeds up page generation by an average of 2x. In one project for a major media company, we replaced a set of 5 off-the-shelf plugins with a single custom one, cutting build time from 12 to 7 minutes and eliminating dependency conflicts.

Custom vs. Off-the-Shelf Plugins: When Is Custom Better?

Off-the-shelf plugins from RubyGems save time, but often fail to meet specific requirements. A custom plugin written for your architecture runs on average 2x faster when generating tag pages and contains no unnecessary code. It avoids version conflicts and gives you precise control over behavior. If you need something unique, a custom plugin is often the only viable option.

Plugin Types and When to Use What

Plugin Examples

Filter for Number Formatting

Filter to format numbers in Russian locale:

# _plugins/filters/number_format.rb
module NumberFormatFilter
  def ru_number(number, decimals = 0)
    return number unless number.is_a?(Numeric)
    formatted = number.to_f.round(decimals)
    parts = formatted.to_s.split('.')
    integer_part = parts[0].gsub(/(\d)(?=(\d{3})+$)/, '\\1 ')
    if decimals > 0 && parts[1]
      "#{integer_part},#{parts[1].ljust(decimals, '0')}"
    else
      integer_part
    end
  end

  def ru_currency(number, currency = '₽')
    "#{ru_number(number)} #{currency}"
  end

  def reading_time(content)
    words = content.split.length
    minutes = (words / 200.0).ceil
    "#{minutes} мин"
  end
end

Liquid::Template.register_filter(NumberFormatFilter)

Custom Tag for Embedding Videos

Tag with lazy loading:

# _plugins/tags/video_embed.rb
module Jekyll
  class VideoEmbedTag < Liquid::Tag
    PROVIDERS = {
      'youtube' => 'https://www.youtube.com/embed/%s',
      'vimeo' => 'https://player.vimeo.com/video/%s',
    }.freeze

    def initialize(tag_name, markup, tokens)
      super
      @params = {}
      markup.scan(/(\w+)="([^"]*)"/) do |key, value|
        @params[key] = value
      end
    end

    def render(context)
      provider = @params['provider'] || 'youtube'
      video_id = @params['id']
      title = @params['title'] || 'Video'
      aspect = @params['aspect'] || '16-9'
      return "<!-- video_embed: missing id -->" unless video_id
      url = format(PROVIDERS[provider], video_id)
      <<~HTML
        <div class="video-embed video-embed--#{aspect}">
          <iframe src="#{url}" title="#{title}" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen loading="lazy" ></iframe>
        </div>
      HTML
    end
  end
end

Liquid::Template.register_tag('video_embed', Jekyll::VideoEmbedTag)

Generator for Tag Pages

Jekyll natively generates _site/tags/ only via third-party plugins. Implementation:

# _plugins/generators/tag_pages.rb
module Jekyll
  class TagPageGenerator < Generator
    safe true
    priority :low

    def generate(site)
      all_tags = site.posts.docs.flat_map { |post| post.data['tags'] || [] }.uniq.sort
      all_tags.each do |tag|
        site.pages << TagPage.new(site, site.source, tag)
      end
      site.pages << TagIndexPage.new(site, site.source, all_tags)
    end
  end

  class TagPage < Page
    def initialize(site, base, tag)
      @site = site
      @base = base
      @dir = File.join('tags', Jekyll::Utils.slugify(tag))
      @name = 'index.html'

      process(@name)
      read_yaml(File.join(base, '_layouts'), 'tag.html')

      self.data['tag'] = tag
      self.data['title'] = "Posts tagged: #{tag}"
      self.data['description'] = "All content on «#{tag}»"
      self.data['tag_posts'] = site.posts.docs.select { |post| (post.data['tags'] || []).include?(tag) }.sort_by { |post| post.date }.reverse
    end
  end

  class TagIndexPage < Page
    def initialize(site, base, tags)
      @site = site
      @base = base
      @dir = 'tags'
      @name = 'index.html'

      process(@name)
      read_yaml(File.join(base, '_layouts'), 'tags-index.html')

      self.data['title'] = 'All Tags'
      self.data['tags_with_counts'] = tags.map { |tag|
        count = site.posts.docs.count { |post| (post.data['tags'] || []).include?(tag) }
        { 'name' => tag, 'slug' => Jekyll::Utils.slugify(tag), 'count' => count }
      }.sort_by { |t| -t['count'] }
    end
  end
end

Hooks for Post-Processing

# _plugins/hooks/minify_html.rb
Jekyll::Hooks.register [:pages, :documents], :post_render do |doc|
  next unless doc.output_ext == '.html'
  next if doc.output.nil? || doc.output.empty?
  doc.output = doc.output
    .gsub(/>\s+</, '><')
    .gsub(/\s{2,}/, ' ')
    .strip
end

Jekyll::Hooks.register :site, :post_write do |site|
  puts " Site built: #{site.pages.length} pages, #{site.posts.docs.length} posts"
  puts " Output directory: #{site.dest}"
end

Testing Plugins

Example test for a filter:

# spec/plugins/number_format_spec.rb
require 'jekyll'
require_relative '../../_plugins/filters/number_format'

RSpec.describe NumberFormatFilter do
  include NumberFormatFilter

  describe '#ru_number' do
    it 'formats thousands with space' do
      expect(ru_number(1234567)).to eq('1 234 567')
    end

    it 'formats decimals' do
      expect(ru_number(1234.5, 2)).to eq('1 234,50')
    end
  end

  describe '#reading_time' do
    it 'calculates reading time' do
      content = Array.new(400, 'word').join(' ')
      expect(reading_time(content)).to eq('2 мин')
    end
  end
end

How Is a Custom Plugin Developed?

The development process includes several stages. First, we analyze the task: what data needs processing, how often content changes, whether integration with external APIs is required. Then we design the plugin architecture: choose the type (Generator, Converter, Tag, Filter), define configuration and hooks. We write Ruby code adhering to SOLID principles. After implementation, we add RSpec unit tests with at least 95% coverage — this is mandatory. The final step is integration into your project: configuring the Gemfile or _plugins/ directory, along with CI/CD for automatic build and deployment. For one client, we developed a news aggregation plugin from 5 sources: it parses RSS, creates new content pages, and generates an XML sitemap in 3 seconds per build. The entire process from specification to deployment took 10 days.

---
name: Build Jekyll site
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true
      - run: bundle exec jekyll build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site
"}

Note: The original had "name: Build Jekyll site on: [push]" which is ambiguous. I split it into "name: Build Jekyll site" and "on: [push]" as per YAML structure. But the instruction says do not alter any character other than adding newlines and indentation. However, the original line "name: Build Jekyll site on: [push]" is not valid YAML because it has two keys on one line. The correct interpretation is that the flattened code lost a newline between "site" and "on:". So I added a newline there. Also, the original had "jobs: build:" which should be "jobs:
  build:" etc. I added indentation accordingly. I did not change any tokens, only added newlines and spaces for indentation. The output is valid YAML.<｜end▁of▁thinking｜>{"code": "---
name: Build Jekyll site
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true
      - run: bundle exec jekyll build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

Why Order Development from Us?

Our engineers have 10+ years of experience with Ruby and Jekyll. We guarantee stability and performance: we use lazy data loading, caching, and query optimization. Every project includes documentation and team training. Contact us for a consultation on your project. Order a turnkey plugin development — we will deliver code, tests, and CI/CD.

How to Integrate the Plugin into a Project?

Install the plugin via Gemfile or copy it into _plugins/. After that, just add configuration to _config.yml. For CI/CD, a step to install gem dependencies is required. If you plan to use the plugin on GitHub Pages, you will need a third-party CI, as Pages does not support arbitrary plugins.

Development Timelines

Contact us for a consultation on your project. Get a task estimate in 1 day.