---
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 these files under a default `rjarticle` folder: 

  - **quokka-bilby.Rmd**: the main document
  - **motivation-letter.md**: a motivation letter template for the article
  - **penguins.png**: an example png used to illustrate how to include a figure in the new format
  - **Rjreferences.bib**: the bibtex file for reference
  - **RJwrapper.tex**: the tex template for compiling the pdf output
  - **Rjournal.sty**: the R journal style sheet for the pdf output

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")
```

## Your first knit

The `rjtools::rjournal_web_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
  - **quokka-bilby-files/**: a folder of Javascript libraries, necessary to view the the html article
  
You can use the regular ways to render the files, either through the RStudio `knit` button, or using `rmarkdown::render("paper/quokka-bilby.Rmd")` on the R command line. 

## Note: `rticles` template

The `rticles` package contains 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 creates an article that will be compiled with latex into a pdf format paper. It is using the current style file. If this new `distill` version of the delivery of the *R Journal* is successful, we will also synchronise the template to the one in `rjtools`. 

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