How to Install Jekyll Plugins as Submodules

The delivery of static files from a web server to your browser can be blazing fast. That is one of the advantages of using Jekyll vs. other dynamic web content systems like Wordpress. One of the drawbacks, unfortunately, is that Jekyll requires much more knowledge about the intricacies of how all the pieces work together. (i.e. fix things when they break in Ruby, install or bake your own plugins, etc.)

Installing plugins though can be quite painless though. I’ll run you though an example and more details as we go..

Note: as we continue this assumes you’re using Git for revision control. If you aren’t you should be. More on Git here.

Update 4/22: Since moving my content over to Netlify I had to scrap using submodules. I ended up following this guide on how to use subtrees instead. That way, when I check out my repository everything is included without having to go to another service or clone several subdirectories.

Update 10/22/2018: Netlify does have the ability to close private and public submodules. For Bitbucket, it does require you to copy the public key that is associated with your Jekyll repository to the repository of the submodule. More info here.

So you want to add a plugin to your Jekyll site eh?

Your Jekyll directory will have a _plugins folder. You can basically copy and paste any Jekyll plugin into this directory. More info on the Jekyll plugin structure here;

Ok that was easy.. big deal?

The drawback to this method is that if (and when) you make changes to these plugins they are not reflected back into the original source code management tool they came from.

So say for instance you have multiple sites running the same plugins. It is suddenly much more difficult to determine what site has what version of the plugin. You can really pull your hair out over this issues. The friendly folks that developed Git came up with a nifty solution: submodules.

Enter Submodules

Most Git ninjas know about submodules by now. It’s a nifty feature in which you can embed another Git repository within your own. This gives you the ability to edit and update the plugin code without having to copy and paste your changes to every app.

Lets hypothetically say you want to add robwierzbowski’s image-tag to your Jekyll project. Lets add it as a submodule to the _plugins folder:

    git submodule add git@github.com:robwierzbowski/jekyll-image-tag.git \_plugins/jekyll-image-tag/

If you’re like me and may want to make changes (like I have done) you can also fork the plugin on Github and then add it as a submodule.

    git submodule add git@github.com:jaredwolff/jekyll-image-tag.git \_plugins/jekyll-image-tag/

What about updates?

Update 2/28/14 I thought I would put up a faster version of this (instead of doing it manually)

In the root of your repo just run these commands:

    git pull
    git submodule update

A big hat-tip to Craig for enligtening me in the comments.

Note: I am using Git 1.9.0. If you are using a different version your mileage may vary!

Another way of doing it..

Lets say the author adding some extra functionality. How do we get those changes?

    cd \_plugins/jekyll-image-tag/
    git pull

Just like pulling changes from any remove Git repository you can do the same here. This will update your working copy of the plugin and reflect that information in your site’s repository.

You can also run through each of your submodules:

    git submodule foreach git pull

Saves a bit of time if you have a bunch.

Brew your own Jekyll Plugins

So that’s it! If you brew your own plugin (or fork someone else’s) feel free to share with the world on Github!

My current (original and forked) plugins

For those who are interested, i’ve written and modified some Jekyll plugins to fit my needs. Here’s the list:

1. jekyll-tag-cloud - a fork from Anurag Priyam

2. jekyll-trophy-case - an original plugin that generates chooses a thumbnail and title of the most popular (or featured) posts on your Jekyll blog and displays them as such. Many dynamic sites have this functionality and there’s no reason to bring it over to the static side of things.

3. jekyll-Disqussion - another original. This plugin uses the (unofficial) Disqus API for Ruby (Disqussion) and enables you to create a list of the most recent posts on your Jekyll blog.

4. jekyll-image-tag - originally from robwierzbowski. I sped things up a bit in the processing. Turns out I already have gigabytes worth of pictures on this site (thanks to all my Alaska posts.) The processing is significantly faster but still not ideal.

And that’s just the first few that are most interesting. Feel free to check out all of them here!

Last Modified: 2020.3.7