Using Jekyll for Lessons

This post originally appeared on the Software Carpentry website.

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:

• Only the source Markdown files go into the repository's gh-pages branch, not the generated HTML

• The lesson's title, repository URL, and other values are defined once in a configuration file called _config.yml.

• Blockquotes are styled like this:

  > ## Title
  >
  > body
  {: .style}
  

  instead of like this:

  > ## Title {.style}
  >
  > body
  

  Code blocks are styled similarly, i.e., with the style after the block instead of at the top.

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:

• this post from John Blischak about us having come full circle, and about us putting time into tooling that we should be putting into creating lesson content;

• this one from Doug Latornell about re-mixing our current Pandoc-based workflow; and

• this one from Carl Boettiger about Markdown syntax.

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.