Author: Miguel Alvarez
Date: 2022-11-09

# Setting elements in yaml headers for r-markdown documents

#### Miguel Alvarez

#### 2022-11-09

# 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.