The Jekyll Plugin Template is a Ruby gem skeleton, created by Mike Slinn, that scaffolds a new working Liquid tag block for Jekyll sites and packages it as a publishable gem.
What is the Jekyll Plugin Template?
The Jekyll Plugin Template is a GitHub repository that provides a starter project for developing Jekyll plugins as Ruby gems. It includes a working Liquid tag block named new_tag_block_name, a collection of Jekyll hook loggers, and an installer script (bin/run_this_first) that renames the entire project to a name you choose. The repo is preconfigured as a Visual Studio Code project with Rake, Rubocop, and RSpec settings. It comes from the Jekyll Plugin Template Collection maintained by Mike Slinn, who also wrote the blog posts linked in the README about Jekyll gem development.
Key Features
- Automated customization script —
bin/run_this_firstrenames directories, files, and contents across the project, deletes its own tests and test data, and removes the template README in favor ofPLUGIN_README.mdrenamed toREADME.md. - GitHub integration — The script initializes a local git repository and optionally creates a public or private project on GitHub.
- Sample Jekyll hooks — The template includes
CleanHook,DocumentHooks,PageHooks,PostHooks,SiteHooks,MyBlock, andPluginMetaLogger, with configurable log levels via theplugin_loggerssetting in_config.yml. - Hook call order logging — Log output from the template reveals the exact order Jekyll invokes its hooks; the README includes an elided example showing the sequence from
:after_resetthrough:post_write. - Build and release tasks —
bundle exec rake installbuilds the gem locally, andbundle exec rake releasepublishes it to RubyGems.org. - Development tooling — Preconfigured settings for Visual Studio Code, Rake, Rubocop, and RSpec support testing and linting.
- Ready-to-push gem structure — After customization, the gem can be pushed to RubyGems.org or any other Ruby gem repository.
Who is it for?
Jekyll plugin developers who want to ship their Liquid tags and hooks as Ruby gems. Ruby developers who prefer a preconfigured environment with Rake, Rubocop, and RSpec. Anyone studying Jekyll's plugin API who wants a logging example that traces hook call order. It is also useful for teams that need a standardized starting point for multiple Jekyll plugins.
What can you do with the Jekyll Plugin Template?
- Jekyll theme and site developers: Add custom Liquid block tags to a Jekyll site and release them as a gem that other sites can include in their
Gemfile. - Ruby gem authors: Use the bundled Rake tasks, RSpec setup, and Rubocop configuration to build, test, and publish a gem without writing boilerplate.
- Jekyll contributors: Observe hook call order by setting log levels and processing a Jekyll site; the template logs when each of the 45 hooks runs.
How does the Jekyll Plugin Template work?
Clone the repository, run bin/run_this_first, and answer the prompts to rename the project. The script rewrites project files and directories, creates a new git repository, and optionally sets up a GitHub remote. Then build with bundle exec rake install and add the gem to a Jekyll site's Gemfile under the :jekyll_plugins group.
FAQ
How do I rename the Jekyll plugin template?
Run bin/run_this_first from the project root. The script renames directories, files, and their contents to the name you provide, deletes its own tests and test data, and removes the template README. After it finishes, the project is ready for the new plugin name.
What plugins does the template provide?
The template includes sample Jekyll hooks: CleanHook, DocumentHooks, PageHooks, PostHooks, SiteHooks, a Liquid block tag called new_tag_block_name, and PluginMetaLogger for logging. You can delete the parts you do not need.
How do I build and publish the gem?
Run bundle exec rake install to build and install the gem locally. When ready to publish, use bundle exec rake release to push it to RubyGems.org or another gem repository.
Does the template create a GitHub repository?
Yes, the bin/run_this_first script initializes a local git repository and asks whether you want to create a public or private project on GitHub.
How do I configure logging?
Add a plugin_loggers key to your Jekyll site's _config.yml and set a log level (info, warn, etc.) for each plugin type. The template's README shows an example with all loggers set to info.
