Pandoc and Building Pages

Pandoc and Building Pages

1. People should be able to write lessons in Markdown. We choose Markdown rather than LaTeX or HTML because it's easier to read, diff, and merge; we choose it rather than AsciiDoc or reStructuredText (reST) because it's much better known.
2. People should be able to preview their lessons locally before publishing them, both to avoid embarrassment and because many people compose offline.
3. Lessons should be easy to write and read. We shouldn't require people to put div's and other bits of HTML in their Markdown.
4. It should be easy to add machine-comprehensible structure to lessons. We want to be able to build tools to extract lesson titles, count challenge exercises, etc., all of which requires machine-comprehensible source. This is in tension with the point above: everything we do to make lessons more readable to computers means extra work or less readbility for people.
5. We should use only off-the-shelf tools. We don't want to have to build, document, and maintain custom plugins for formatting tools. We do want to use GitHub's gh-pages magic.
6. The workflow for creating and publishing lessons should be authentic, i.e., the way people write and publish lessons should be a way they might use to write and publish research papers.

Read full article from Pandoc and Building Pages