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.