---
title: "Create an R Journal article"
author: Sherry Zhang
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{create-article}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup, echo = FALSE}
library(rjtools)
```

With advances in html delivery of research articles through the web, the *R Journal* now has a new format of its website using a version of the `distill` package. This will allow incorporation of interactive graphics directly into articles and easier reading of the research online. 

The Rmd template in `rjtools` creates an article in the format needed for the *R Journal* `distill` web site. The `rjtools` package is provided to help authors meet these requirements with an intention that it would help authors to write an *R Journal* article, similar to the way that `devtools` help developers build an R package. In this vignette, I will walk you through how to use `rjtools` to create an *R Journal* article using the built-in template. 

## Create an Article

The `create_article()` function will create the following files and folders:

  - **test.Rmd**: the main Rmarkdown document
  - **Rjreferences.bib**: the bibtex file for reference
  - **Rjournal.sty**: the R journal style sheet for the pdf output
  - **data/**: the data folder
  - **figures/**: the figures folder that contains **penguins.png** for illustrating how to include a figure in the new format
  - **scripts/**: the script folder for additional scripts, if any
  - **motivation-letter/**: the folder contains **motivation-letter.md**, a motivation letter template for the article

The `.tex`, and `.sty` files make sure all the *R Journal* articles follow the same latex and reference style and should not be modified unless there is a strong reason to do so.

The `name` argument changes the name of the main R Markdown document, for example, if you wish to use `quokka-bilby` as the file name instead of `article`, create the article with: 

```{r eval = FALSE}
create_article(name = "quokka-bilby")
```

Please ensure that you stick to this folder structure when working with an R Journal paper. Any additional files should be organised within new folder(s) rather than being placed directly in the main directory. A uniform folder structure makes it easier to compile papers into issues during the editorial process. 

## Your first knit

To knit the `Rmd` file, you can use either through the RStudio `knit` button, or type the following command in the R console:  

```{r eval = FALSE}
rmarkdown::render("quokka-bilby.Rmd")
```
  
Before knitting, you may need to install the packages used in the template file (`plotly`, `ggplot2`, `kableExtra` and `palmerpenguins`) by 
  
```{r eval = FALSE}
install.packages(c("plotly", "ggplot2", "kableExtra", "palmerpenguins"))
```

The R Journal uses `pandoc-citeproc` to handle the Citation Style Language (CSL) style. 
If you're knitting the document within RStudio (which we recommend), this is automatically handled. However, if you're using the command line, you'll need to ensure the `pandoc-citeproc` extension is installed properly on your system.

The `rjtools::rjournal_article` output specified in the article YAML will create the article in both html and pdf formats. Additional files created during the knit are (assuming file name of `quokka-bilby`):

  - **quokka-bilby.html**: the html article 
  - **quokka-bilby.pdf**: the pdf article 
  - **quokka-bilby.tex**: the LaTeX file 
  - **quokka-bilby.R**: an R file that contains all the codes
  - **Rlogo-5.png**: the R logo used in the article - should it be hidden? 
  - **RJwrapper.log**: the log file - should it be hidden? 
  - **RJwrapper.tex**: the tex file. - it was there when created before now it is only here after rendered? 
  - **quokka-bilby.log**: the log file - should it be hidden?
  - **quokka-bilby-files/**: a folder of Javascript libraries, necessary to view the the html article  - no longer there? 
  
## Note: `rticles` template

<!--The `rticles` package historically contained a template for creating an *R Journal* article, which you might have used before if you have been already working with R Markdown for writing papers. This template is now synchronised with the template in `rjtools`.--> 

Now feel free to head to the vignette *More details on the R Journal format* for an example article and more detailed information on the template. 

## No quarto yet

At this time the journal only takes `Rmd` formatted papers, which makes sense because the journal is focused on R, not other languages. At some point in the future it may be able to accommodate `qmd` formatted papers.