If you use Ruby, you’ve most likely heard of GitHub, the amazing and beloved DVC repository. You’ve also probably heard of Jekyll, the blog aware static site generator. What you might not know is that GitHub lets you host your Jekyll site on their GitHub Pages service for free! Like any other free service, there is a catch. It’s not ads, bandwidth limitations, or hidden fees though, it’s the utilization of Jekyll plugins.
If you’re not familiar with Jekyll or GitHubPages, check out the Quick-start guide and their introduction to deploying sites to GitHub Pages.
Jekyll by default does more than enough to let you hit the ground running. You can write your posts in markdown, use the simple templating engine Liquid to make your site look handsome, then generate static pages with jekyll build
and boom you’ve got HTML files and assets ready to be deployed. Because these are static HTML files (and possibly some JavaScript) you can host them almost anywhere
- Personal server
- Shared hosting
- Public dropbox folder
- GitHub Pages (the obvious correct choice)
1 and 2 take time and money to maintain, and trying to host a site on Dropbox is probably not a good idea for anything more than testing. The GitHub Pages service (which is provided so users, organizations and projects can host sites about themselves, their organizations, and projects) runs on Jekyll; a tool they built and maintain because they dog food everything.
This is where the plugins come in (or rather, don’t). It is pretty easy to get going with GitHub Pages even, if you’re pretty new to Ruby and Git. But what they don’t tell you is, when you git push
your Jekyll repo to your user/gh-pages repo on Github and it builds your _site
directory for public consumption it doesn’t run any Jekyll plugins that aren’t a part of the official repo.
This is because when Github creates your pages it does so with jekyll build --safe
. The --safe
parameter prevents any arbitrary code from being executed at build time, because GitHub obviously does not want you executing arbitrary code on their servers.
Fun fact: the liquid template engine is used in Jekyll specifically because it is safe and doesn’t allow arbitrary code injection. This makes it safely “user editable”.
There are lots of great Jekyll plugins, like archive and rss generators, that add highly desirable functionality. However, because they are not core Jekyll plugins, they will not run on GitHub Pages. Of course, you’ll still want this functionality in your site, so how can we get around this (completely legitimate) fear of arbitrary code execution? There are a few different ways, from the drop-dead simple to the highly automated (and complicated). The good news is, the simple way will work for anyone.
GitHub Pages hosts your site, but it doesn’t technically have to have been generated by Jekyll. This technicality means you can generate your site locally and then push the static files to GitHub. Github won’t find anything to compile via a jekyll build
so you end up with a repo of your site instead of a repo of your Jekyll files. You can make sure GitHub doesn’t try to build your site by including a .nojekyll
file in your repo.
The Simple Way
This is actually the method I used at first because I realized my plugins weren’t working on GitHub Pages and it was far and away the easiest and quickest fix. That also means it requires a little bit of manual work each time you want to update your site. Here is what you need to do:
- Rename the directory with your Jekyll site to
compiled_site
- Create a new directory (outside of the
compiled_site
directory) and name itjekyll_site
- Copy all the contents of
compiled_site
intojekyll_site
- Run
jekyll build
in your newjekyll_site
directory - In your
compiled_site
directory rungit rm -r
to remove all files - Copy the entire contents of
jekyll_site/_site
intocompiled_site
- Create a
.nojekyll
file incompiled_site
- Run
git add --all :/
incompiled_site
to add all the static files into the git repo and remove the old ones - Run
git commit -m "Built site locally"
- Run
git push
to update GitHub
If you need plugins working on your site now, there isn’t a faster way to get the content into GitHub Pages then this. Unfortunately, every time you write a new post, tweak your theme, or make any other change, you’ll need to do a manual copy of the files built in your _site
directory into the actual GitHub directory.
The Less Simple, More Awesome Way
Manual file copying? The Jekyll motto is “blog like a hacker” and this manual file management doesn’t seem very hacker-esque. Fortunately, we have rake
. We can make a simple rake task to automate the process outlined above. If your Jekyll blog isn’t already using a Rakefile
, create one and put it into the jekyll_site
directory created earlier. Add the following into this Rakefile:
GH_PAGES_DIR = "compiled_site"
desc "Build Jekyll site and copy files"
task :build do
system "jekyll build"
system "rm -r ../#{GH_PAGES_DIR}/*" unless Dir['../#{GH_PAGES_DIR}/*'].empty?
system "cp -r _site/* ../#{GH_PAGES_DIR}/"
end
Before you run your Rakefile make sure to exclude it from building into the _site/
by adding an exclude line to your_config.yml
. The exclude line requires an array, even if there is just one file.
exclude: [Rakefile]
Now instead of using jekyll build
to get your site ready you can use rake build
. This Rakefile
will
- run
jekyll build
for you - empty your destination folder if it has contents (in case you deleted files/posts/assets since your last site build)
- copy the contents of the newly built
jekyll_site/_site
directory to yourcompiled_site
git repo directory
Now you can cd
into compiled_site
and run
git add --all
git commit -m "Updated my site!"
git push origin master
You can expand your Rakefile
to handle the git add
, git commit
, and git push
commands as well, if you want to get even fancier. I eventually expanded my Rakefile
to manage the whole thing for me via git branches instead of multiple directories (a post for another day!) However, with this setup you can use all the Jekyll plugins you want, build your site locally, and still host your site on the fantastic (and free!) GitHub Pages easily.
Are you blogging like a hacker? Do you use GitHub pages to host those Jekyll files? Let me know in the comments what automations you build into your process, and the Jekyll plugins you’ll be able to use now.
Frequently Asked Questions about Jekyll Plugins and GitHub
What are Jekyll plugins and how do they work?
Jekyll plugins are tools that extend the functionality of Jekyll, a static site generator. They are written in Ruby and can be used to add new features or modify the existing behavior of Jekyll. They work by hooking into the Jekyll build process and manipulating the content that Jekyll generates. This can include tasks such as generating additional pages, modifying the site’s configuration, or even changing the way Jekyll parses your source files.
How do I install a Jekyll plugin?
Installing a Jekyll plugin is a straightforward process. First, you need to add the plugin to your site’s Gemfile. Then, you need to run the ‘bundle install’ command to install the plugin. Finally, you need to add the plugin to your site’s _config.yml file under the ‘plugins’ key. This tells Jekyll to load the plugin when it builds your site.
Can I use Jekyll plugins with GitHub Pages?
Yes, you can use Jekyll plugins with GitHub Pages. However, GitHub Pages only supports a limited set of plugins for security reasons. If you want to use a plugin that is not supported by GitHub Pages, you will need to build your site locally and then push the generated static files to your GitHub repository.
How do I create my own Jekyll plugin?
Creating your own Jekyll plugin involves writing a Ruby script that defines a new class or module that inherits from one of Jekyll’s plugin classes. This script should be placed in the _plugins directory of your Jekyll site. The specific class or module that your plugin inherits from determines when and how your plugin is called during the Jekyll build process.
What are some common uses for Jekyll plugins?
Jekyll plugins can be used for a wide variety of tasks. Some common uses include generating additional pages, adding custom Liquid tags or filters, modifying the site’s configuration, and changing the way Jekyll parses your source files. For example, you might use a plugin to generate a sitemap for your site, add support for a new markup language, or add custom metadata to your pages.
How do I troubleshoot issues with Jekyll plugins?
Troubleshooting issues with Jekyll plugins can involve several steps. First, you should check the plugin’s documentation for any known issues or troubleshooting tips. If that doesn’t help, you can try disabling other plugins to see if there’s a conflict. You can also try running Jekyll with the ‘–verbose’ flag to get more detailed output about what’s happening during the build process.
Can I use Jekyll plugins to customize the look and feel of my site?
Yes, you can use Jekyll plugins to customize the look and feel of your site. Some plugins allow you to add custom Liquid tags or filters that you can use in your templates. Others allow you to modify the site’s configuration or change the way Jekyll parses your source files, which can give you more control over the generated HTML.
How do I update a Jekyll plugin?
Updating a Jekyll plugin is as simple as updating the version number in your site’s Gemfile and then running the ‘bundle update’ command. This will update the plugin to the latest version and install any new dependencies.
Can I use Jekyll plugins to optimize my site for search engines?
Yes, there are several Jekyll plugins available that can help optimize your site for search engines. These plugins can generate sitemaps, add metadata to your pages, and even help with things like URL structure and redirects.
How do I uninstall a Jekyll plugin?
Uninstalling a Jekyll plugin involves removing the plugin from your site’s Gemfile and _config.yml file. Then, you need to run the ‘bundle install’ command to update your site’s dependencies.
David is an Instructional Technologist happily hacking away in higher ed. When not behind a keyboard he can be found behind a controller, handlebars, or in the mountains.