Setting elements in yaml headers for r-markdown documents

Miguel Alvarez

2020-12-21

Introduction

The package yamlme targets to write yaml-heads and even full r-markdown documents from plain R codes. The tasks of this package are the automatic generation of reports from R sessions as well as producing templates that can be shared as R-functions.

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)

To start a new session, load the package:

library(yamlme)

Writting yaml heads

Several internal funcions and classes are implemented in this package, while the only visible result will be produced by the function write_rmd(). Each entry in the yaml head can be provided as custom argument in this function, where at the moment four different categories are defined.

A vector of lentght 1 is the basing entry for a head, for instance:

my_document <- write_rmd(title = "My first document")
my_document

## ---
## 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 in post you start with a vertical line as first element in the vector.

my_document <- write_rmd(description = c("|",
                "This text starts with a vertical line",
                "and will be thus used as a description",
                "in the head."))
my_document

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

A similar way is applied in the case of the entries for the element vignette in a vignette document, hier for convenience recycling the tile of the vignette.

the_title <- "Introduction to this package"
my_document <- write_rmd(
        title = the_title,
        vignette = c(">",
                paste0("%\\VignetteIndexEntry{", the_title, "}"),
                "%\\VignetteEngine{knitr::rmarkdown}",
                "%\\VignetteEncoding{UTF-8}"))
my_document

## ---
## title: Introduction to this package
## vignette: >
##   %\VignetteIndexEntry{Introduction to this package}
##   %\VignetteEngine{knitr::rmarkdown}
##   %\VignetteEncoding{UTF-8}
## ---

A further class is used for entries starting with a dash symbol.

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

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

And finaly, nested entries can be provided as lists.

my_document <- write_rmd(output=list(pdf_document="default"))
my_document

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

A full example

With the function write_rmd() you can create a full r-markdown document. You cam either assign the result to an object or write it in a file, or both. For it, the parameters filename (name and path for the output file), body (body of the document as caracter vector), and append (appended blocks in yaml-head, for instance comments) are suitable.

my_document <- write_rmd(title = "Mi First Document", author = "My Name",
        output = "html_document", append = "# This is a comment in head",
        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

## ---
## title: Mi First Document
## author: My Name
## output: html_document
## # This is a comment in head
## ---
## 
## # 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

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

render_rmd(input = my_document, output_file = "my_document")

Using the objects as template

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

my_template <- write_rmd(
        title = "Example HTML document",
        author = "My Self",
        output = "html_document",
        body = txt_body(
                "# Introduction",
                "",
                "This is just an example."))
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",
        append = "# this is a modified version")
my_template

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