Markdown In Rstudio



R Markdown in R Studio Export Code with Result in HTML. Create HTML or PDF Files with R Knitr MikTex Pandoc. RStudio is not required but recommended, because it makes it easier for an average user to work with R Markdown. If you do not have RStudio IDE installed, you will have to install Pandoc ( ), otherwise there is no need to install Pandoc separately because RStudio has bundled it. However, I would suggest that beginners understand some of the R terminology by looking at the R markdown. Exactly, opening rmarkdown in r studio, opens.

Source: vignettes/lua-filters.Rmd

This vignettes gives some detailed information regarding the Lua filters including in the rmarkdown package. You don’t have to do anything to use them usually as they just works usaully. This document presents the features they power.

To know more about Lua filters in general, you can jump directly to last section

Pagebreaks

This filter is available since rmarkdown 1.15 and works with Pandoc 2.1+ (shipped in RStudio >= 1.2).

Adding a pagebreak in document was always possible using custom output specific syntax in a rmarkdown file but one drawback was the compatibility with several output format.

With this Lua filter, it is possible to add a newpage or pagebreak command in a new line to include a pagebreak in any of these formats: pdf_document(), html_document(), word_document() and odt_document().

rmarkdown will convert those commands in the correct output format syntax using a Lua filter during pandoc conversion.

Using with PDF/ latex documents

As the commands are the ones already used in latex syntax, this works as expected in a tex output document, and thus with pdf. Adding a pagebreak was already possible with rmarkdown when output is pdf_document() or latex_document(), without any restriction about the version of pandoc.

Using with HTML documents

A newpage or pagebreak command in a rmarkdown document with output as HTML will be converted by default in this html code with inline style using CSS rule page-break-after

This will always insert a pagebreak after this div.

To get more flexibility, you can use a HTML class and some custom CSS instead of an inline style. You need to add a metadata field newpage_html_class in your yaml header to set the class.

Then you can control the behavior using custom CSS as in this example

newpage will be converted here to

and the style will be applied to this class from the CSS included in the chunk.

This customisation can also be achieved by setting the environnement variable PANDOC_NEWPAGE_HTML_CLASS in the R session that will render the document (or in .Renviron file for example)

Let’s note that in this example we use break-after property instead of page-break-after as it is recommended now to use the former which is the replacement. The latter is kept around for compatibility reason with browsers.

Using with Word documents

A newpage or pagebreak command in a rmarkdown document with output as Word document will be converted in a pagebreak for word document. Manually, this would mean adding this in your rmarkdown

For example, using the pagebreak feature, this will add the first header in the second page of the work document

Using with ODT documents

To use the pagebreak feature with odt_document(), you need to provide a reference document that includes a paragraph style with, by default, the name Pagebreak. This named paragraph style should have no extra space before or after and have a pagebreak after it. (see libre office documentation on how to create a style).

The name of the named paragrah style could be customized using newpage_odt_style metadata in yaml header or PANDOC_NEWPAGE_ODT_STYLE environment variable (as in html document).

As the previous one, this example will lead to a two pages document, with first header on the second page.

Number sections

This filter is available since rmarkdown 2.4 and works with Pandoc 2.1+ (shipped in RStudio >= 1.2).

Numbering sections are supported by Pandoc for limited formats (e.g., html and pdf). The rmarkdown package adds number_sections.lua to support this feature in other formats (e.g., docx, odt, and so on). Users do not have to know which formats use the Pandoc’s feature or the Lua filter.

In general, numbers and titles of sections are separated by a space. An exception is the word_document function, which separates them by a tab in order to be consistent with Pandoc’s number sections for docx format in Pandoc >= 2.10.1. If one wants to have fine controls on the format of section numbers, prepare customized docx file and specify it to the reference_docx argument of the word_document function.

Custom environment for LaTeX

This filter is available since rmarkdown 1.15 and works with Pandoc 2.1+ (shipped in RStudio >= 1.2).

Pandoc supports a syntax called Fenced Divs that allows to create <div> in HTML. For example, the syntax is

By default, this special syntax will be ignored in LaTeX conversion for PDF output and the content of the block will be used as-is. However, this syntax could be used to create LaTeX environment.

That is why rmarkdown uses a custom Lua filter to allow any Fenced Divs to be converted as a LaTeX environment (begin{env} … end{env}) when desired by adding a special attribute.

Its LaTeX output will be:

This feature we call Custom blocks is documented in details in the R Markdown Cookbook

About Lua filters

Since pandoc 2.0, it is possible to use Lua filters to add some extra functionality to pandoc document conversion. Adding a pagebreak command in markdown to be compatible with several output documents is one of them. You can find some more informations about Lua filters in pandoc’s documentation and also some examples in a collection of Lua filters for pandoc. These examples, and any other Lua filters, can be use in your Rmarkdown document directly by adding a pandoc argument in yaml header

You can also use a special helper using a !expr syntax for yaml in your header

The package rmdfiltr provides a collection of Lua filters and helpers functions to use them.

Before pandoc 2.0, using filter with pandoc was already available through programs that modifies the AST. pandoc-citeproc is an example used to deal with citations. The package pandocfilter is useful to create filters using R.

Using filters with output format

If you want to create a format that uses a special filter, you can add it as a pandoc option if the output format.

How To Use R Markdown

Either by modifying an existing format:

Or by creating a new format :

As this is an advanced feature, if you want to go further, we encourage you to look at the examples of formats in packages such as rmarkdown, bookdown or pagedown.

If you're doing reproducbility in R Studio, you're probably using knitr. And if you're using knitr, you're probably using Markdown. Unfortunately, due to the lack of a standard for Markdown (and the subsequent proliferation of various flavours and extensions), it's sometimes not clear what syntax is available to you. Consequently, you tend to write in the lowest common denominator / most common syntax.

This is an exploration of what markup is available should you use Markdown in R Studio, based on the source distribution, documentation and some experiments. I'm not trying to explain all of Markdown, just the oddities and extras you'll find in R Studio.

Note

You can use reStructured Text instead of Markdown, it's more powerful and has more features, but Markdown is the first class citizen in the R Studio universe and you'll always be fighting the system in some way.

Technical details

R Studio v0.98 on Mac OSX 10.9, April 2015.

Markdown Rstudio Error

General issues

R Studio Markdown (henceforth RSMarkdown) is an R package that is based on pandoc. While it is possible to install extensions for the package, it's not clear to me how to get RSMarkdown to use these extensions.

Markdown is generally focused on HTML as an output. RSMarkdown is more general and allows other and mutliple output formats.

Where a block of text must be indented, that indentation is a tab or at least 4 spaces.

Metadata & headers

Rstudio

RSMarkdown explicitly allows for metadata, which may define title and output format. Multiple outputs can be defined, with variables that apply just in those contexts:

Possible output formats are:

Rstudio Markdown Preview

  • html_document
  • pdf_document
  • word_document
  • md_document
  • beamer_presentation
  • ioslides_presentation
  • slidy_presentation

How To Use R Markdown In R Studio

This style of metadata is in fact YAML and can include other fields:

Obscurely, RSMarkdown includes a second type of metadata, where the intial lines of a file can include 3 lines beginning with percent signs, giving bibliographic information:

The order and number of lines are fixed. It is unclear whether R Studio does anything with this info.

Two styles of headers are permitted, covering slightly different levels of headings:

'Leading hash' style headers can have matching trailing hashes, e.g. ## FOO ##, which is arguably more readable.

Text styling

Strike-through text is flanked with double-tildes:

Superscripts are flanked with the 'hat' symbol, subscripts are flanked with a single tilde:

Verbatim / literal text is placed inside backticks:

Quotes & code blocks

Quotes are precded with > marks. Only the first line need have one if subsequent lines are flush against the left margin:

Literal quote blocks preserve linebreaks, such as you might want to do for addresses or for poetry. This are preceded with vertical bars |:

Code blocks are 'fenced' with lines of 3 or more tildes, or indented:

Lists

Definition lists can be used, with the initial definition line preceded with : and subsequent lines at the same depth. These lists must be indented:

Note

Markdown In Rstudio

I've had a lot of trouble with definition lists, even after reading the spec and documentation. Regardless of what is written elsewhere, it seems like the whole list has to be indented and the definition has to be at the same level of indentation as the term.

Numbered lists can be constructed with (@):

Tables

You can do tables in RSMarkdown. Lord, can you do tables. There's multiple ways to do them, but I'll drop a few simple examples here, from which the general form can be inferred. Note that no header is required and horizontal lines arefairly freeform:

Markdown Rstudio Pdf

Tables can also be given a label that either proceeds or follows them:

Note

Tables are tremendously fiddly. Get even a single character out of the column and RSMarkdown will foul it up. I've even had cases where a seemingly valid table won't format correctly for unclear reasons.