yaml-fieldguide.Rmd

---
title: "The YAML Fieldguide"
output: 
  prettydoc::html_pretty:
    theme: tactile
vignette: >
  %\VignetteIndexEntry{The YAML Fieldguide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  echo = FALSE,
  message = FALSE,
  collapse = TRUE,
  comment = "", 
  warning = FALSE
)
```


```{r pandoc_check, echo=FALSE}
if (!rmarkdown::pandoc_available()) {
  cat("pandoc is required to use ymlthis. Please visit https://pandoc.org/ for more information.")
  knitr::knit_exit()
}
```


```{r roxygen_check, echo=FALSE}
if (!requireNamespace("roxygen2")) {
  cat("roxygen2 is required to render this vignette: `install.packages('roxygen2'`")
  knitr::knit_exit()
}
```

```{r setup}
library(ymlthis)
oldoption <- options(devtools.name = "Malcolm Barrett", crayon.enabled = FALSE)

function_name <- function(x) {
  function_call <- x$call
  ifelse(rlang::has_length(function_call), as.character(function_call[[2]]), NA)
}

block_names <- function(x) x$tags %>% purrr::map_chr(~.x$tag)

get_doc_name <- function(x) {
  tags <- block_names(x)
  rdname_index <- which(tags == "rdname")
  if (purrr::is_empty(rdname_index)) return(function_name(x))
  
  x$tags[[rdname_index]]$val
}

get_params <- function(x) {
  param_lists <- which(block_names(x) == "param")
  f <- get_doc_name(x)
  if (!rlang::has_length(param_lists) || is.na(f)) return(data.frame())
  
  params_desc <- x$tags[param_lists] %>% 
    purrr::map(~as.data.frame(.x$val, stringsAsFactors = FALSE)) %>% 
     do.call(rbind, .)
  
  params_desc$description <- stringr::str_replace_all(
    params_desc$description, 
    "\n", 
    " "
  )
  
  params_desc$name <- params_desc$name %>% 
    stringr::str_split(",") %>% 
    purrr::map_chr(
      ~paste0("`", .x, "`") %>% paste(collapse = ", ")
    )
  
  cbind(func = f, params_desc, stringsAsFactors = FALSE)
}

link_help_page <- function(x) {
  url <- "https://ymlthis.r-lib.org/"
  glue::glue("<a href='{url}/reference/{x}.html'>{x}</a>")
} 

filter_kable <- function(.tbl, .pattern = NULL, caption = NULL) {
  if (!is.null(.pattern)) {
    index <- stringr::str_detect(.tbl$func, .pattern)
    .tbl <- .tbl[index, ]
  }
  .tbl$func <- link_help_page(.tbl$func)
  
  knitr::kable(
    .tbl, 
    col.names = c("Help Page", "Argument", "Description"), 
    row.names = FALSE, 
    caption = caption
  )
}

fields_df <- roxygen2::parse_package("../") %>% 
  purrr::map(get_params) %>% 
  do.call(rbind, .)
```

**ymlthis** attempts to write common YAML for you in the right way and to document the many YAML field options in one place. The fieldguide is a collection of all the fields documented in the **ymlthis** help pages, organized by source. Note that some argument names do not match the YAML field name exactly in order because not all field names are valid R names (e.g. the `link-citations` YAML field needs to be `link_citations` in R); these differences are noted in the argument description. Additionally, not all of these arguments are top-level YAML; see the linked help pages for more details.

## Basic YAML

```{r}
fields_df %>% 
  filter_kable("yml_author|yml_runtime|yml_clean|yml_toc", caption = "Basic YAML")
```

The nested fields for the `output` field are based on the arguments of the output function. See the help page for the function you are using, e.g., `?rmarkdown::pdf_document`.

## LaTeX/PDF Options

```{r}
fields_df %>% 
  filter_kable("latex", caption = "LaTeX/PDF Options")
```

## R Markdown Websites

```{r}
fields_df %>% 
  filter_kable("site|navbar|vignette", caption = "R Markdown Websites")
```

## Citations

```{r}
fields_df %>% 
  filter_kable("citations", caption = "Citations")
```

## blogdown YAML

```{r}
fields_df %>% 
  filter_kable("yml_blogdown_opts", caption = "blogdown YAML")
```

## bookdown YAML

```{r}
fields_df %>% 
  filter_kable("bookdown", caption = "bookdown YAML")
```

## pkgdown YAML

```{r}
fields_df %>% 
  filter_kable("yml_pkgdown", caption = "pkgdown YAML")
```

## pagedown YAML

```{r}
fields_df %>% 
  filter_kable("pagedown", caption = "pagedown YAML")
```

## distill YAML

```{r}
fields_df %>% 
  filter_kable("distill", caption = "distill YAML")
```

## rticles YAML

```{r}
fields_df %>% 
  filter_kable("rticles", caption = "rticles YAML")
```

## RStudio Connect Scheduled Email YAML

```{r}
fields_df %>% 
  filter_kable("rsconnect", caption = "RStudio Connect Scheduled Email YAML")
```

```{r, include=FALSE}
options(oldoption)
```