swcarpentry/bc — pull request #342 by gvwilson (2014-02-25 17:46:50+00:00)
Title: Proposal: eliminate Jekyll for lessons, use Pandoc instead

Work in progress: do not merge. This is here as a proposal to be discussed.

Our existing build system uses a mix of nbconvert, Jekyll, and Pandoc to create HTML versions of our lessons. This PR simplifies that:

1. Lesson pages are built using nbconvert and Pandoc only - no Jekyll.
2. Websites for bootcamps are still built using Jekyll, but don't automatically include lessons (because those are now in http://software-carpentry.org/v5/.

Most of the work is in `Makefile`; other changes are mostly to support the switch from Jekyll to Pandoc (e.g., taking out the per-page headers in `.md` files that Jekyll needed).

Pro:

* Simpler build process (fewer tools) for lessons.
* Fewer templates to edit.
* Pandoc supports styling of fenced `pre` blocks, which Jekyll doesn't, so we can reliably distinguish input and output "cells" in Markdown-formatted lessons.

Con:

* Lesson pages aren't automatically built when we check things in to GitHub (but that wasn't happening anyway, since GitHub doesn't know anything about nbconvert).

Undone:

1. The Pandoc template for lessons in `_templates/lesson.tpl` duplicates a lot of stuff in the other templates, and doesn't `%include` (or equivalent) the standard header, footer, banner, javascript, etc.
2. We don't actually style the input and output cells of the final pages using CSS.
3. We should be able to modify the `bin/make-book.py` tool to patch image paths on the fly rather than using `sed` to do it into a second staging area.

Thoughts would be very welcome - is this change a net win? Is this the right way to do it?