13-rticles.Rmd

# Journals

Academic journals often have strict guidelines on the formatting for submitted articles. As of today, few journals directly support R Markdown submissions, but many support the LaTeX\index{LaTeX} format. While you can convert R Markdown to LaTeX (see Section \@ref(pdf-document)), different journals have different typesetting requirements and LaTeX styles, and it may be slow and frustrating for all authors who want to use R Markdown to figure out the technical details about how to properly convert a paper based on R Markdown to a LaTeX document that meets the journal requirements.

The **rticles** package [@R-rticles]\index{rticles} is designed to simplify the creation of documents that conform to submission standards. A suite of custom R Markdown templates for popular journals is provided by the package such as those shown in Figure \@ref(rticles-templates).

(ref:rticles-templates) Two journal templates in the **rticles** package (PLOS and Springer).

```{r rticles-templates, echo=FALSE, out.width="100%", fig.cap="(ref:rticles-templates)", fig.show='hold'}
knitr::include_graphics(c("images/rticles-plos.png", "images/rticles-springer.png"), dpi = NA)
```

Understanding of LaTeX is recommended, but not essential, to use this package. R Markdown templates may sometimes inevitably contain LaTeX code, but usually we can use the simpler Markdown and **knitr** syntax to produce elements like figures, tables, and math equations as explained in Chapter \@ref(basics).

## Get started {#rticles-start}

You can install and use **rticles** from CRAN as follows:

```{r, eval = FALSE}
# Install from CRAN
install.packages("rticles")

# Or install development version from GitHub
devtools::install_github("rstudio/rticles")
```

We would recommend the development version of the package from GitHub, as it contains the most up-to-date versions along with several new templates.

If you are using RStudio, you can easily access the templates through `File -> New File -> R Markdown`. This will open the dialog box where you can select from one of the available templates as shown in Figure \@ref(fig:rticles-setup).

(ref:rticles-setup) The R Markdown template window in RStudio showing available **rticles** templates.

```{r rticles-setup, echo=FALSE, fig.cap="(ref:rticles-setup)", out.width='100%'}
knitr::include_graphics("images/rticles-templates.png", dpi = NA)
```

If you are using the command line, you can use the `rmarkdown::draft()` function, which requires you to specify a template using the journal short name, e.g.,

```r
rmarkdown::draft(
  "MyJSSArticle.Rmd", template = "jss", package = "rticles"
)
```

## rticles templates

The **rticles** package provides templates for various journals and publishers, including:

- JSS articles (Journal of Statistical Software)
- R Journal articles
- CTeX documents
- ACM articles (Association of Computing Machinery)
- ACS articles (American Chemical Society)
- AMS articles (American Meteorological Society)
- PeerJ articles
- Elsevier journal submissions
- AEA journal submissions (American Meteorological Society)
- IEEE Transaction journal submissions
- Statistics in Medicine journal submissions
- Royal Society Open Science journal submissions
- Bulletin de l'AMQ journal submissions
- MDPI journal submissions
- Springer journal submissions

The full list is available within the R Markdown templates window in RStudio, or through the function `rticles::journals()`:

```{r}
rticles::journals()
```

## Using a template {#rticles-usage}

Templates have an extended YAML section compared to the basic R Markdown template, which allows you to specify additional details relevant to the custom template. Below is an example of the YAML section for the *Springer* template:

```yaml
title: Title here
subtitle: Do you have a subtitle? If so, write it here
titlerunning: Short form of title (if too long for head)
authorrunning:
  Short form of author list if too long for running head
thanks: |
  Grants or other notes about the article that should go
  on the front page should be placed here. General
  acknowledgments should be placed at the end of the article.
authors:
  - name: Author 1
    address: Department of YYY, University of XXX
    email: abc@def
  - name: Author 2
    address: Department of ZZZ, University of WWW
    email: djf@wef
keywords:
  - key
  - dictionary
  - word
MSC:
  - MSC code 1
  - MSC code 2    
abstract: |
  The text of your abstract.  150 -- 250 words.
bibliography: bibliography.bib
output: rticles::springer_article
```

As the Rmd documents are built using customized templates, you may not be able to use the YAML metadata to control the layout of the document as described in Section \@ref(pdf-document), unless the template supports such metadata. For example, adding `toc: true` may not add a table of contents. Commands that control the building process may still be used though, including `keep_tex: true`, or those that configure **knitr** chunk options (e.g., `fig_width`).

## LaTeX content {#rticles-latex}

As the only output format of the **rticles** formats is PDF, the content of the documents may include raw LaTeX formatting. This means you may use LaTeX to produce figures and tables (if you have to), e.g.,

```latex
\begin{figure}[ht]
\centering
\includegraphics[width=\linewidth]{foo}
\caption{An example image.}
\label{fig:foo}
\end{figure}
```

Unless you have specific requirements for using LaTeX, we recommend that you use the R Markdown syntax. This keeps you work generally more readable (in terms of the source document), and less prone to formatting errors. For example, the above code block would be better represented as:

````markdown
`r ''````{r foo, out.width="100%", fig.cap="An example image."}
knitr::include_graphics("foo.png")
```
````

## Linking with bookdown {#rticles-bookdown}

As explained in Section \@ref(bookdown-markdown), **bookdown**\index{bookdown} offers several extensions to the Markdown syntax, which can be particularly useful for academic writing, including cross-referencing of figures and tables. All **rticles** output formats are based on `rmarkdown::pdf_document`, and we can use them as the "base formats" for `bookdown::pdf_book`, e.g.,

```yaml
output:
  bookdown::pdf_book:
    base_format: rticles::peerj_article
```

You can substitute `rticles::peerj_article` with the template you actually intend to use.

## Contributing templates {#rticles-contrib}

If you take a look at the GitHub repository of **rticles** (https://github.com/rstudio/rticles), you will see that a lot of the templates have been contributed by the R community. If you are interested in improving them or adding more journal templates, you may want to read Chapter \@ref(document-templates), which outlines how a template can be made for R Markdown. Basically these templates are defined to translate the Pandoc variables from the YAML frontmatter and the body of the R Markdown document into LaTeX.