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:

---
[]
---

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

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 :

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:

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.