---
title: "Setting elements in yaml headers for r-markdown documents"
author: Miguel Alvarez
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Setting elements in yaml headers for r-markdown documents}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r eval = FALSE}
library(devtools)
install_github("kamapu/yamlme", build_vignettes = TRUE)
```

Load the package after you start a new session.

```{r}
library(yamlme)
```

# Writting R-markdown documents

This package uses functions of
[`yaml`](http://biostat.app.vumc.org/wiki/Main/YamlR) for reading and writing
yaml-headers.
In `yamlme`, R-markdown documents can be created from lists, for instance:

```{r}
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.

```{r}
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.

```{r}
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.

```{r}
my_document <- list(output = list(pdf_document = "default"))
as(my_document, "rmd_doc")
```

The following is a more complex map using embedded lists.

```{r}
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](https://biostat.app.vumc.org/wiki/Main/YamlR).


# Case example

Here there is an example of a full Rmarkdown document.

```{r}
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.

```{r eval = FALSE}
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()`.

```{r}
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.

```{r}
my_template <- update(my_template,
  title = "Example PDF document",
  output = "pdf_document"
)
my_template
```