---
title: "Automating 'R Makrdown' html output"
author: "Adam P Cribbs"
date: "`r format(Sys.Date(), '%m/%d/%Y')`"
output:
  rmarkdown::html_document:
    highlight: pygments
    toc: true
    fig_width: 5
vignette: >
  %\VignetteIndexEntry{Automating rmakrdown html output}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\usepackage[utf8]{inputenc}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
  echo = FALSE,
  message = FALSE,
  collapse = TRUE,
  comment = ""
)
library(magrittr)
```

```{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()
}
```

# Overview

siteymlgen makes it easy to organise 'R Markdown' website output. 
  The init() function placed within the first code chunk of the index.Rmd
  file of an 'R' project directory will initiate the generation of an automatically 
  written _site.yml file. 'siteymlgen' recomends a specific naming
  convention for your 'R Markdown' files. This naming will ensure that
  your navbar layout is ordered according to a heirarchy. 

Often writing the _site.yml can be the most annoying task when 
generating a webite using Rmarkdown, particularly when there are multiple tabs and 
sub tabs. The `init()` function should be placed in a code cell of your index.Rmd 
file. When your other `.Rmd` files are named according to the siteymlgen convention 
then the _site.yml will automatically populate. 

# Yaml overview and usefulness of siteymlgen

The basic syntax of yaml is to use key-value pairs with the format `key: value`. In
a `.Rmd` or `.Md` file, a yaml code block is bounded by `---`. Between the code block
you can pass instructions in yaml format to modify the output of each file.  For example,
specifying the author of the document is as straightforward as:

```{r}
ymlthis::yml(date = FALSE) %>% 
  ymlthis::asis_yaml_output()
```

However, writing yaml code can be quite a pain as it needs to be properly formatted and 
the use of single spaces are important (no tabs or double spacing). One awesome package
that allows you to write yaml output fast and accurately is [ymlthis](https://ymlthis.r-lib.org). 
However, when writing large html reports I have often found that writing the `_site.yml` can
be time consuming and boring. Automating this part of the workflow is the rationale for this
package.


# Writing an _site.yml with **sitegenyml**

Generating an `_site.yml` file is made as painless as possible. The first step is to add a
file named `_site.yml` into a repository and then add the following into the `index.Rmd` file:

```{r echo=TRUE, eval=FALSE}
library(siteymlgen)
init(file="_site.yml")
```

You can specify values to modify the basic yaml output. For a full range of input variables please
refer to the `?init` help section :

```{r echo=TRUE, eval=FALSE}
init(authors = c("Adam","Paul"), 
     left="yes",
     dir="~/Documents/siteymlgen/inst/extdata/", 
     navbar_title = "Main title", 
     title = "hello", 
     categories=c("r", "reprodicibility"), 
     toc=TRUE, 
     toc_depth = 3,
     file="_site.yml")
```

When you build your website within Rstudio the `init` function will parse the directory of `.Rmd` 
files and then arrange them into a navbar. The order in which the `.Rmd` files are displayed within
your website can be controlled by following our naming convention below. 

# siteymlgen Rmarkdown naming convention

In order to control how your website navbar is ordered then you need to stick to the following
naming convention:

`[A-Z][1-9]_TitleofTab.Rmd`

e.g. `A1_FileOne.Rmd`

The capital first letter of the file name controls the position of the tab in the navbar. The number controls
the position within the dropdown menu, if you do not want a dropdown menu then label the file [A-Z]1_TitleofTab.Rmd.

# Example data

Included within this package is data that demonstrates the functionality of this project. First copy the data
to a new folder:

```{r eval=FALSE}
dir.create(paste0(getwd(), "/test"))
file.copy(system.file("extdata", package="siteymlgen"), paste0(getwd(), "/test"), recursive = TRUE)

```

Then naviage to the directory and create a new R project. Set up build tools so that you can build an R markdown
website and then "Build Website". You will see that the _site.yml file has been populated with yaml output, which was
generated by the `init()` function within the first code chunk of the `index.Rmd`.