Notes on knitr and markdown

and Carl Boettiger

2012-05-15

About knitr

Knitr and Markdown help enable fast, reproducible sharing of research and methods. We use them for both formal and informal workflows.

Knit files include both text and code, and are easy to distribute and revise. They have four components

  • Markdown (or HTML or LaTeX or …) text
  • R code
  • Patterns - designate the start and end of code chunks
  • Options - designate how to evaluate code, either for a specific chunk or for the whole file

When a knit file is evaluated, you get

  • The same text you started with
  • The R code you wrote
  • The results of the code - as text and images, and
  • Hooks - text that designates the start and end of code.

Patterns and hooks allow us to use knit in pretty much any document format. By default, knitr will read the extension of the file you write and determine its format, and set appropriate patterns and hooks to generate output in the same format.

Other features

  • Code cleanup: knitr uses the formatR package to make your code readable. If you are exporting HTML, it will also syntax-highlight code
  • Cacheing - for computationally intense chunks, you can cache results so that, if the document is revised, you don’t have to re-run code.
  • Many options for figure output, as well has image upload to imgur
  • Highly customizable
  • Ability to choose what output is displayed and what isn’t

Getting Knitr

Knitr has a great website with many examples.

All you need to use knitr is to install with

install.packages("knitr")

RStudio’s latest version has native support for knitr. Just go to Options/Preferences >> Sweave >> and enable “knitr”.

Workflow

Using github, we generally do this:

  • Write knit file
  • Knit
  • Upload both the source and knit files to github

With RStudio, a one-button “Knit HTML” button generates an HTML page that can be uploaded anywhere.

About Markdown

  • Simple format for web publishing
  • Many blogging services (inc. wordpress, github pages) allow one to write and publish in markdown directly.
  • Many different parsers with slightly different flavors for markdown. Syntax for most basic elements (images, links, headings, etc.) is the same but, different for more advanced features (tables, code blocks, citations)

  • Parsers can convert markdown HTML, LaTeX, even (gasp!) MS Word. (MultiMarkdown, Pandoc)

  • You can find documentation on markdown syntax here
  • Github has its own modification to markdown, documented here

  • Pandoc and Multimarkdown are programs that convert markdown to HTML, LaTeX, and other formats. They include support for LaTeX-style math for HTML, using MathJax

Some examples