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
| Type | Superclass | Use Case |
|---|---|---|
| Generator | Jekyll::Generator |
Programmatic page creation, data aggregation |
| Converter | Jekyll::Converter |
New content formats (AsciiDoc, reStructuredText) |
| Command | Jekyll::Command |
New CLI commands (jekyll mycommand) |
| Tag | Liquid::Tag |
Custom tags {% mytag %} |
| Block | Liquid::Block |
Tags with content {% block %}...{% endblock %} |
| Filter | include in Liquid::Template.register_filter |
Custom filters `{{ value |
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.
Example CI/CD Setup for GitHub Actions
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
| Plugin Type | Estimated Time |
|---|---|
| Filter or simple tag | 0.5–1 day |
| Tag with parameters | 1–2 days |
| Generator for pages | 2–3 days |
| Format converter | 3–5 days |
| Complex plugin with API and tests | 1–2 weeks |
Contact us for a consultation on your project. Get a task estimate in 1 day.