Setting elements in yaml headers for r-markdown documents

In yamlme: Writing '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")

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")

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")

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")

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")

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

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

yamlme documentation built on Nov. 10, 2022, 5:10 p.m.