Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Plugin Ecosystem #1272

benbalter opened this Issue Jul 6, 2013 · 14 comments


None yet
10 participants

benbalter commented Jul 6, 2013

Plugins are treated as second-class citizens in the Jekyll world. Sure, there's the plugin page on the docs site, (which deprecated a wiki), but beyond that, we don't give plugins much love. Most are just gists floating around, or links to the _plugins folder of a live site. No versioning, no dependency management, no forums for bugs. Most importantly, no community. Let's change that. Let's grow an ecosystem of vibrant and community-collaborated plugins:


Each plugin should be its own GitHub repository (so we can get Issues, forks, pull requests, documentation, and versioning) and should be globally referenced by it's relative URL to github.com (e.g., benbalter/some-plugin, "the plugin slug"). Plugins continue to live in the _plugins folder and are fully backwards compatible, but can now be managed as git submodules. If the plugin has external dependencies, it should specify a Gemfile. All plugins should have their own readme, and ideally tests/travis ci integration. Like homebrew, git is used for versioning, avoiding the need for a centralized repository.

Jekyll Install

Plugins live in _config.yml as an array of plugin slugs. If it's not in _config.yml, it doesn't get included at runtime (allowing for deactivated plugins). If I clone down a new site, I can simply run the jekyll install command, which will parse _config.yml and install the necessary plugins (similar to bundle install). This includes dependencies, etc. The process would involve looking in the _plugins folder for a submodule, installing if not, and installing dependencies if there's a Gemfile present.

  - benbalter/sitemap
  - parkr/rss-feed
  - mojombo/tag-cloud

Jekyll Install [plugin]

Just like gem install, jekyll install [plugin slug] should install the plugin. Passing the --save flag will add the installed plugin to your _config.yml file.

Jekyll Update (or Jekyll update [plugin])

Update submodules in the _plugins directory, update dependencies.

The plugin directory

The mechanics is half the equation. Plugins need to be more than a list of bullets below the fold of a documentation page 3 clicks from the main site. Lets stand up jekyllrb.com/plugins. Each plugin would be its own post, complete with categories, tags, descriptions, and (by storing the plugin slug in YAML), links to documentation, Issues, source code, the works. Want your plugin added? Simply submit a pull request. All this information should be exposed as a JSON (static) API as well, allowing for better command-line integration down the line.

Plugin best practices

Jekyll should ship with a boilerplate "hello world" core plugin (deactivated by default), that shows developers (and users) how plugins work. I'd also love to see a bunch of (current and proposed) core functionality migrated to plugins to force us to begin dogfooding the plugin experience.


Once plugins are first-class Jekyll citizens, and an integral part of the Jekyll experience, it simply wouldn't make sense to not allow plugins on GitHub.com, and with an established plugin infrastructure to version and file issues against plugins, plugin support is a lot more feasible, especially looking at something like the WordPress.com model which allows a whitelist of .com blessed plugins.


I don't know if anything here is technically possible (Can you have a Gemfile in a subfolder without things going 💥?, do submodules scale? etc.), and don't expect the jekyll install command to ship in the next version, but looking at some other successful plugin ecosystems (I'm looking at you WordPress), which really drive the community, often times more so than core does, I'd love to sketch out where we'd want the plugin experience to be (for end users and plugin authors), say a year and a half from now, and work backwards from there to build that community. Let's make plugins awesome, halp?


gregkare commented Jul 7, 2013

In the config file, I would rather have something that supports any kind of git repo rather than username/repo on GitHub being the only choice. Bundler is using a :github shorthand for a GitHub repo and :git for a vanilla Git repo.

I like the rest of your proposal!


parkr commented Jul 8, 2013

Thanks for writing up your thoughts, @benbalter. Plugins are kind of second-class citizens in that they are (generally) standalone ruby files and cannot be executed on GitHub Pages. The Jekyll dev team never gave any guidance about how plugins should be shared or packaged, so we have today's hodgepodge of plugins floating around the web.

@imathis, @MrJoy and I talked extensively about plugins for Octopress. Originally, Brandon and I took a git-centric route, but found that it was very prone to errors. In the new release of Octopress, we'll be asking plugin authors to release plugins in gem form.

Some brief thoughts:

  • plugins must be strictly versioned (interdependencies and general stability)
  • we'll have to use a different key - something like bundle - in the _config.yml file. plugins is already taken
  • for gem-based dependencies, RubyGems reigns king
  • provide a scaffold plugin
  • provide better discovery of other plugins

In the commando branch, @mojombo completed a first version of new CLI implementation which allows injection of commands, options, dependencies and all that. This, coupled with some sort of Jekyll::Plugin subclass instantiation would give us the best

I would vote for RubyGems-based integration, bringing in commando to specify new commands (e.g. jekyll s3), plugin autoloading, and developing something like plugins.jekyllrb.com, a simple directory service for Jekyll plugin discovery.


qrush commented Jul 8, 2013

I'm very 👎 to re-implementing RubyGems and Bundler like features inside of Jekyll. There's several plugin based ecosystems that are doing well by just using what the community already provides, like Rails and RSpec.

Despite that, standardizing on how to install, provide, and scaffold a plugin should be feasible. Let's just use gems and bundle as normal.


ixti commented Jul 8, 2013

@qrush 👍


parkr commented Jul 8, 2013

@qrush Amen.

@tombell Yes to the overhead for . I think the maintainer of aforementioned plugin listing would be fine with doing a quick check-over at accept-time and compiling a list every week or something and shooting someone an email to do more auditing. But yeah, I agree that's a big hurdle.

@ixti Wow, didn't even know about @JDStraughan's jekyll-plugins website and repository. I'd prefer to make the site run on GitHub Pages as a Jekyll site, though. I'll write up a proposal in a Gist and paste it here soon.

I'm actually working on jekyll-plugins.com today, trying to get it caught up. It is open source, Ruby on Rails, and runs on a postgres datastore to enable full text search, etc.

If there is anything I can do to help the community, I'm happy to. jekyll-plugins.com is just sitting on a heroku instance right now. I'd love for it to become the place to find and share plugins.


parkr commented Jul 8, 2013

As for a plugin directory, it'd be splendid if we could collect the information we want as posts in a jekyll site, compile them to JSON and load everything in dynamically. Kind of like this but way better: https://github.com/parkr/plugins.jekyllrb.com

MrJoy commented Jul 9, 2013

I'd consider using the jekyll-models plugin, in order to capture more rich/structured data about plugins in a simpler/more maintainable/more uniform way…


On Jul 8, 2013, at 4:31 PM, Parker Moore notifications@github.com wrote:

As for a plugin directory, it'd be splendid if we could collect the information we want as posts in a jekyll site, compile them to JSON and load everything in dynamically. Kind of like this but way better: https://github.com/parkr/plugins.jekyllrb.com

Reply to this email directly or view it on GitHub.

Any updates on this? I would love to stop copy and pasting stuff around 😭


parkr commented Oct 18, 2013

@bitboxer An easier gem-like integration for plugins can be found at #1557. However, it does not tackle integrating plugins which have site assets, such as images, layouts, includes, etc.


parkr commented Dec 6, 2013


parkr commented Jul 31, 2014

We'll continue to use RubyGems/Bundler for plugins. Once 3.0 is more feature-complete, we'll release an alpha or something with good docs. Eventually we'll want a way to search RubyGems database just for Jekyll plugins. A new naming convention around plugins will be enforced and we'll be golden.

@parkr parkr closed this Jul 31, 2014

@jekyllbot jekyllbot locked and limited conversation to collaborators Feb 27, 2017

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.