Setting elements in yaml headers for r-markdown documents

Introduction

The package yamlme targets to produce R-markdown documents from plain R code. The tasks of this package are the automatic generation of reports from R sessions as well as producing templates that can be shared as functions or rmd_doc objects.

Installing yamlme

To install this package from its GitHub repository, you can use the package devtools.

library(devtools)
install_github("kamapu/yamlme", build_vignettes = TRUE)

Load the package after you start a new session.

library(yamlme)

Writting R-markdown documents

This package uses functions of yaml for reading and writing yaml-headers. In yamlme, R-markdown documents can be created from lists, for instance:

my_document <- list(title = "My first document")
as(my_document, "rmd_doc")

## ---
## title: My first document
## ---

Some applications may also require a description (or abstract) as in the case of documents rendered by distill. To add a description you need to collapse lines into a single string (character value) including line breaks. The description will start with a vertical line in the yaml header.

my_document <- list(description = paste0(c(
  "This text starts with a vertical line",
  "and will be thus used as a description",
  "in the head."
), collapse = "\n"))
as(my_document, "rmd_doc")

## ---
## description: |-
##   This text starts with a vertical line
##   and will be thus used as a description
##   in the head.
## ---

You can use character vectors to produce sequences in the yaml header, as sometimes required for PDF documents.

my_document <- list("header-includes" = c(
  "\\usepackage{titling}",
  "\\pretitle{\\begin{flushleft}\\LARGE\\textbf}",
  "\\posttitle{\\end{flushleft}}",
  "\\sffamily"
))
as(my_document, "rmd_doc")

## ---
## header-includes:
## - \usepackage{titling}
## - \pretitle{\begin{flushleft}\LARGE\textbf}
## - \posttitle{\end{flushleft}}
## - \sffamily
## ---

List embedded into lists can be conveniently used to produce more complex maps for yaml headers in Rmarkdown documents.

my_document <- list(output = list(pdf_document = "default"))
as(my_document, "rmd_doc")

## ---
## output:
##   pdf_document: default
## ---

The following is a more complex map using embedded lists.

my_document <- list(
  author = list(
    list(
      name = "Miguel Alvarez",
      url = "https://kamapu.github.io/"
    ),
    list(
      name = "Bisrat H. Gebrekhidan"
    )
  )
)
as(my_document, "rmd_doc")

## ---
## author:
## - name: Miguel Alvarez
##   url: https://kamapu.github.io/
## - name: Bisrat H. Gebrekhidan
## ---

To know the representation of a specific yaml map in Rmarkdown documents, you can read Rmd files using the function read_rmd(). Also consider a visit to the R yaml homepage here.

Case example

Here there is an example of a full Rmarkdown document.

my_document <- list(
  title = "Mi First Document",
  author = "My Name",
  output = "html_document",
  body = txt_body(
    "# Starting a working day",
    "",
    "At the beginning of every day I will do:",
    "",
    "- Say everyone \"Good morning!\"",
    "- Start the coffe mashine",
    "- Start the computer",
    "- Read mails"
  )
)
my_document <- as(my_document, "rmd_doc")

In this case we can render the document directly from the resulting object.

render_rmd(input = my_document)
browseURL("my_document.html")

Using objects as template

The function update() can be used to modify settings and content in documents written by write_rmd().

my_template <- list(
  title = "Example HTML document",
  author = "My Self",
  output = "html_document",
  body = txt_body(
    "# Introduction",
    "",
    "This is just an example."
  )
)
my_template <- as(my_template, "rmd_doc")
my_template

## ---
## title: Example HTML document
## author: My Self
## output: html_document
## ---
## 
## # Introduction
## 
## This is just an example.

We can also modify the template to adapt the output or the template of the document.

my_template <- update(my_template,
  title = "Example PDF document",
  output = "pdf_document"
)
my_template

## ---
## title: Example PDF document
## author: My Self
## output: pdf_document
## ---
## 
## # Introduction
## 
## This is just an example.