A few weeks ago I wrote about how to get a free GitHub account for education, and then a week later I signal boosted a method for building a course website using R Markdown and Github. I like the sites generated using that method, but the styling options are somewhat limited for these sites, and they’re not best for all purposes (or even all course websites). For today’s post, then, I want to share another method I’ve used lately for generating sites using Jekyll, a static website generator, and GitHub Pages.
As I wrote in that previous post, in recent years I’ve moved away from my Wordpress network because of the increasing bloat required to keep Wordpress sites stable and secure, which is largely unnecessary for most of my course and project websites; the speediness of flat HTML sites as compared to database-driven sites like Wordpress; and the simplicity, both in creation and use, of flat HTML sites. If you’re thinking of moving away from Wordpress, Jekyll is a nice alternative. In 2015 Alex Gil wrote a three-part series here at ProfHacker describing how to get started (Part 1, Part 2, Part 3), and last year Jason wrote about how leaving the LMS makes it easier to remix courses. Amanda Visconti also published a very detailed tutorial at the Programming Historian.
I’ve been moving toward writing almost exclusively in Markdown for awhile, and I was thus drawn to the simplicity of creating pages and blog posts in Jekyll: you simply write a new Markdown file, add a basic header, which can be as short as two lines, and drop the file in the appropriate folder. I hesitated for too long, however, because of the requirement to use some basic Ruby scripts to create the initial Jekyll site and regenerate the site’s HTML after each update. It’s not that these tasks seemed impossible—I was able to create a basic Jekyll site without much trouble when I tested it out—but only that I don’t work often in Ruby. It didn’t feel intuitive, and I just wasn’t (yet) invested enough in Jekyll practice those few lines of code until they did feel intuitive. If I was going to transition entirely to a new system, it would need to feel like less work, not more.
I couldn’t shake the appeal of Jekyll, though, for all the reasons Alex and Jason outline. Fortunately, this summer, I realized that GitHub pages can make publishing a Jekyll website much simpler. Essentially, if you have GitHub repository that follows Jekyll’s directory structure, GitHub pages will automatically build the site without you needing use Ruby on your command line to do so. Jonathan McGlone wrote a nice tutorial for using GitHub pages to publish a Jekyll site (and there’s another one from Barry Clark, so I won’t repeat his work here. For me, the discovery of this simpler way has enabled me to enjoy all the benefits of Jekyll without the (admittedly minor) hassles of Ruby.
Using GitHub pages, the easiest way to create a new static site is to find the Github repository of a Jekyll theme you like, fork that repository, and…well that’s really it. GitHub pages will build the Jekyll site and in a few minutes you’ll have a copy of the theme running at yourusername.github.io. All you will need to do then is start modifying the page and post files to include your own content. If you want to adjust the style of your new page, you’ll need to dig into some of the more advanced styling and layout files, but that isn’t required. If you’re migrating from Wordpress to Jekyll, there are a number of methods, but I had success using the Jekyll Exporter plugin to export my content to Jekyll-ready markdown files that could be simply dropped into the appropriate folders. In the past GitHub pages only worked with about a dozen Jekyll themes, but this past November they announced support for several hundred community-curated themes available on Github, substantially expanding the possibilities for hosting Jekyll websites directly through GitHub.
There’s definitely some work involved in getting familiar with the structure of a Jekyll site, and especially in learning to tinker with its files for layout and styling. Some Jekyll themes are more complicated than others. But once a site is set up—for a class, say—creating a new one for the next semester’s class is as simple as cloning its repository. Updating Jekyll sites for GitHub pages is likewise a breeze. Simply create new Markdown files or edit existing ones (or edit other files, such as layout files), commit those changes to the repository, and within a few minutes the site will update. If you use a custom domain (or subdomain) as I do for my sites, you’ll need to do a bit more work to get those working through GitHub Pages, but there’s nice documentation describing how to do so.
Using this method, I’ve migrated my research blog and the websites for my research projects, Viral Texts and Oceanic Exchanges, to fast, static Jekyll sites. I’m currently in the process of building a site for my spring class, Technologies of Text, in Jekyll as well (that site is far from complete so please don’t judge it yet!). It took me awhile to really grok Jekyll, and maybe I’m not entirely there yet since I’m using this simpler method, but I don’t envision returning to Wordpress anytime soon.
How about you? Have you moved your class or research sites to a static HTML site like Jekyll? Tell us about your experiences in the comments.
