Overview

In some cases you might want to produce plain markdown output from R Markdown (e.g. to create a document for a system that accepts markdown input like Stack Overflow or WordPress).

To create an markdown document from R Markdown you specify the md_document output format in the front-matter of your document:

---
title: "Habits"
author: John Doe
date: March 22, 2005
output: md_document
---

Markdown Variants

By default the md_document format produces “strict” markdown (i.e. conforming to the original markdown specification with no extensions). You can generate a different flavor of markdown using the variant option. For example:

---
output:
  md_document:
    variant: markdown_github
---

Valid values are:

  • markdown (Full pandoc markdown)
  • markdown_strict (Original markdown specification)
  • markdown_github (GitHub flavored markdown)
  • markdown_mmd (MultiMarkdown)
  • markdown_phpextra (PHP markdown extra)

You can also compose custom markdown variants, for example:

---
output:
  md_document:
    variant: markdown_strict+backtick_code_blocks+autolink_bare_uris
---

The pandoc markdown specification defines all of the markdown extensions and their name to be used in composing custom variants.

Publishing Formats

Many popular publishing systems now accept markdown as input. Here are the correct markdown variants to use for some popular systems:

System Markdown Variant
GitHub Wikis markdown_github
Drupal markdown_phpextra
WordPress.com markdown_phpextra+backtick_code_blocks
StackOverflow markdown_strict+autolink_bare_uris

In many cases you can simply copy and paste the markdown generated by render into the editing interface of the system you are targeting. Note however that if you have embedded plots or other images you’ll need to upload them separately and fixup their URLs to point to the uploaded location.

Table of Contents

You can add a table of contents using the toc option and specify the depth of headers that it applies to using the toc_depth option. For example:

---
title: "Habits"
output:
  md_document:
    toc: true
    toc_depth: 2
---

If the table of contents depth isn’t explicitly specified then it defaults to 3 (meaning that all level 1, 2, and 3 headers will be included in the table of contents).

Figure Options

There are a number of options that affect the output of figures within HTML documents:

  • fig_width and fig_height can be used to control the default figure width and height (7x5 is used by default)

  • fig_retina specifies the scaling to perform for retina displays (defaults to null which prevents retina scaling). Retina scaling is generally not useful for markdown output since rendering retina images requires explicit use of HTML img tags rather than native markdown image syntax.

  • dev controls the graphics device used to render figures (defaults to png)

For example:

---
title: "Habits"
output:
  md_document:
    fig_width: 7
    fig_height: 6
---

Advanced Customization

Includes

You can do more advanced customization of output by including additional content. To include content in the document header or before/after the document body you use the includes option as follows:

---
title: "Habits"
output:
  md_document:
    includes:
      in_header: header.md
      before_body: doc_prefix.md
      after_body: doc_suffix.md
---

Pandoc Arguments

If there are pandoc features you want to use that lack equivilants in the YAML options described above you can still use them by passing custom pandoc_args. For example:

---
title: "Habits"
output:
  md_document:
    pandoc_args: [
      "--csl", "/var/csl/acs-nano.csl"
    ]
---

Documentation on all available pandoc arguments can be found in the pandoc user guide.

Shared Options

If you want to specify a set of default options to be shared by multiple documents within a directory you can include a file named _output.yaml within the directory. Note that no YAML delimeters or enclosing output object are used in this file. For example:

_output.yaml

md_document:
  variant: markdown_phpextra
  fig_width: 6
  fig_height: 4.5

All documents located in the same directory as _output.yaml will inherit it’s options. Options defined explicitly within documents will override those specified in the shared options file.

comments powered by Disqus