June 24, 2015: Using Jekyll for Lessons

A recurring complaint about our lesson template is that it requires authors to commit generated HTML files to their repositories as well as their Markdown source files. This is necessary because we use Pandoc to convert Markdown to HTML, but GitHub will only run Jekyll.

There were a bunch of reasons for using Pandoc instead of Jekyll, but it is now clear that the simplicity of only committing Markdown—i.e., of using GitHub pages the way they're meant to be used—is more important. We have therefore created a prototype of a Jekyll-based template (which is rendered here). The most important changes are:

People using source formats other than Markdown, such as R Markdown or Jupyter Notebooks, will still need to convert their files to plain old Markdown (styled as shown above) in order for them to be rendered properly by Jekyll. And we'll need to upgrade the format checking script, which means finding a Kramdown-compatible parser in Python (or getting Kramdown to spit out its AST as a data structure that a Python program can consume). But most of these things have to be done anyway, and it seems that most of our contributors think they're a price worth paying for a "real" GitHub Pages experience.

If you think the change is worth making, please say so in the comments below this GitHub issue. If you think we should stick with our existing tools, please say that too.

Postscript: many people have said they want the change, largly because it brings us in line with the standard GitHub Pages workflow (which Data Carpentry is using). Several others have counter-arguments, some of which are in this thread from our discussion list. In particular, please read:

We are grateful to Brittany Hemming for her work on the CSS for this prototype, and to Thomas Leitner for advice on Kramdown's Markdown parsing.

< OlderNewer >

This post originally appeared in the Software Carpentry blog.