Author Carpentry : Open Authorship and Reproducible Reporting with Markdown and Pandoc

Content Contributors: Gail Clement, Tom Morrell, Patrick Koppula, Sebastian Karcher

Lesson Maintainers: None

Lesson status: Future

What you will learn:

During this lesson, participants will:

• Review examples of reproducible research compendia that combine “the whole tale” of an investigation – the narrative, computer code, resulting plots, and data – in one coherent package or presentation
• Explain why the genre of the reproducible research compendium improves on the traditional static scientific paper, whether published in print or as ‘digital paper’ (PDF)
• Describe the benefits of writing in plain text for not only the author but for potential readers, both human and machine
• Apply the text-based markup syntax Markdown to produce an informative, expressive, and polished-looking research output
• Apply the universal document conversion tool Pandoc to render a single markdown file into multiple types of outputs and formats for various uses
• Practice using Markdown and Pandoc both at the command line and via the RStudio Integrated Development Environment (IDE)

Credit: This lesson idea was inspired by the Sustainable Authorship lesson developed and delivered by Programming Historian: http://programminghistorian.org/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown. AuthorCarpentry instructors are adapting it as a prerequisite module for our Reproducible Reporting curriculum.

Topics:

1. Introduction: The limitations of the traditional scientific paper
2. Why Author in Plain Text?
3. Markdown and Pandoc at the command line
4. Markdown, Pandoc, and Knitr in RStudio

Data

Student files for this lesson are available from the AuthorCarpentry site at: https://github.com/AuthorCarpentry/markdown-pandoc-student

Requirements

Author Carpentry’s teaching is hands-on, so participants are encouraged to use their own computers to insure the proper setup of tools for an efficient workflow. These lessons assume no prior knowledge of the skills or tools, but working through this lesson requires working copies of the software described below. To most effectively use these materials, please make sure to install everything before working through this lesson.

• Unix Shell
• R
• RStudio
• Pandoc
• Github account

Cheat Sheet

Markdown Cheatsheeet

RMarkdown Cheatsheet

References