Exercise: Formatting Quarto documents in APA 7 style

Note

This exercise is only relevant, if you are a psychologist or want to publish in journals that require manuscripts to be formatted in the APA 7 style (Publication Manual of the American Psychological Association: 7th Edition). If you are from another discipline, checkout whether Quarto already provides article templates for your most beloved journals.

Description

Pick a preprint of your own and implement it using Quarto in the APA 7 manuscript style. You also can view an example document that incorporates all features from this exercise.

Getting started

The official Quarto extension apaquarto can be used to format documents according to the APA 7 guidelines1. After installing the extension into the current project, we can set the format to apaquarto-pdf or apaquarto-docx. Here are the detailed steps that are necessary to create a manuscript in APA 7 style (Note: skip step 1 if you want to use an already existing Quarto document).

  1. Prerequisites

    • Install required packages

      • Click on Console

      • Enter

        install.packages(c("rmarkdown", "conflicted", "tidyverse", "flextable", "ftExtra"))
    • Install TinyTeX
      • Click on Terminal
      • Enter quarto install tinytex

  2. Optional: Create a new Quarto Document

    • Click on File > New File > Quarto Document
    • Fill Title and Author
    • Choose PDF
    • Click Create

  3. Add APA 7 Quarto extension

    • Go to Terminal
    • Enter quarto add wjschne/apaquarto
    • Confirm installation by entering Y twice, then avoid opening the documentation by entering n
    • If you want to update the extension at a later point, enter quarto update wjschne/apaquarto

  4. Declare the language of the document by setting e.g. lang: en in the YAML header (see the Quarto documentation on document language for more information)

  5. Change format as follows:

    format:
  apaquarto-pdf:
    documentmode: man
    a4paper: true
    pdf-engine: lualatex
    keep-tex: false

  6. Click on the disk symbol to save (maybe call the file manuscript.qmd)

  7. Click on Render
    (alternatively, go to the Terminal and enter quarto render manuscript.qmd)

We can now provide additional information in the YAML header as detailed below.

Short title

A running header in upper case can be added like this:

shorttitle: "My short title"

Authors

Say we have two authors called Ana Fulana and Blanca Zutana, each with their own ORCID, email address and CRediT roles. They have a common affiliation and Ana acts as corresponding author. In the YAML header this looks as follows:

author:
  - name: Ana Fulana
    corresponding: true
    orcid: "0000-0000-0000-0000"
    email: "af@example.org"
    roles:
      - conceptualization
      - writing
    affiliations:
      - id: "lmu"
        name: "Ludwig-Maximilians-Universität München, Munich, Germany"
        department: "Department of Psychology"
        ror: "https://ror.org/05591te55"
        url: "https://www.lmu.de/"
  - name: Blanca Zutana
    roles:
      - project administration
    affiliations: 
      - ref: lmu

Available CRediT roles are:

See the Quarto documentation on author roles for more information.

Abstract

You can add an abstract using the abstract YAML key:

abstract: "Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquid ex ea commodi consequat. Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."

Keywords

One can add multiple keywords by using a list:

keywords:
  - meta science
  - replication
  - multiverse analysis

Author Note

The author note can be populated with various disclosures as follows:

author-note:
  disclosures:
    study-registration: "This study was preregistered at OSF at ...."
    data-sharing: "Code and data of this study are available at ..."
    related-report: "This article is based on data published in ..."
    conflict-of-interest: "We declare we have no competing interests."
    financial-support: "This research was funded by the German Research Foundation (DFG SCHO ..., Blanca Zutana)."
    gratitude: "We would like to thank Carina Mengana and Dolorita Perengana for their very helpful comments and discussions on this project."
    authorship-agreements: "Because the authors are equal contributors, order of authorship was determined by a fair coin toss."

Figures

For including images, it is recommended to define a label starting with fig- to make the figure cross-referencable. One can also add a note and set the image width and height. In APA 7 style, captions are to be written in title case.

![This Image Depicts a Flower.](flower.jpg){#fig-flower apa-note="This is the note below the figure." height="5cm" width="5cm"}

For figures that are computed dynamically, the following might serve as an example:

```{r}
#| label: fig-cars
#| fig-cap: Plot of the cars Dataset.
#| apa-note: Another note.
#| out-height: 5cm
#| out-width: 5cm
#| fig-height: 3
#| fig-width: 3

plot(cars)
```

When using the apaquarto extension, by default, figures appear at the end of the document, unless one sets floatsintext: true in the YAML header. Therefore it might make sense to add a final heading Appendix below which the figures will appear. Figures can be cross-referenced by using the @ symbol followed by the reference label: For an image of a flower, see @fig-flower.

For more information on how to work with figures, head over to the Quarto documentation on figures.

Tables

Tables need to have labels prefixed with tbl-:

| Letters | Numbers |
|:-------:|:-------:|
| A       | 1       |
| B       | 2       |
| C       | 3       |

: My Caption {#tbl-mytable apa-note="Note below table" data-quarto-disable-processing="true"}

As an alternative to using markdown, tables can be created dynamically, e.g. using the R packages tibble and flextable:

```{r}
#| label: tbl-ingredients
#| tbl-cap: Substances and Their Key Ingredients.
#| apa-note: The note below the table.

tibble::tribble(
  ~"Substance", ~"Key Ingredient",
  "a",   "None",
  "b",   "Sugar",
  "c",   "Salt"
  ) |>
  flextable::flextable() |>
  flextable::theme_apa()
```

When using the apaquarto extension, by default, tables appear at the end of the document, unless one sets floatsintext: true in the YAML header. One can refer to tables by using the @ symbol followed by the reference label: Key ingredients are given in @tbl-ingredients.

For more information on how to create tables, head over to the Quarto documentation on tables.

Footnotes

The following serves as an example for how to add footnotes:

Here is an inline note.^[This text appears as a footnote.]

References

Put your bibliography in a BibTeX file (extension .bib) and reference it in your YAML metadata:

bibliography: literature.bib

Add a level one heading and a Div with the id refs at the end of the document (but before the appendix, if you have one):

# References

::: {#refs}
:::

You can now cite from your bibliography using the syntax [@id].

For more information on how to cite literature, head over to the Quarto documentation on citations.

Numbered lines

If you would like to have your lines numbered, set numbered-lines: true in the YAML header.

Generate .tex file

Sometimes you might need the intermediate .tex file in addition to the final .pdf file. In order to keep that, set keep-tex: true in the YAML header.

Use publication style

In the YAML header shared above, the style of the document is a manuscript as required when submitting to an APA journal. To switch to publication style which resembles the format of an article printed in an APA journal, change the document mode by setting documentmode: jou

Generate .docx file

If you prefer to create your manuscript as DOCX rather than PDF, you can set the format as follows:

format:
  apaquarto-docx: default

Final notes

You can download a manuscript with all the features presented on this page via the following button:

If you are interested in all the options provided by the apaquarto extension (e.g., masked citations for anonymous peer review), have a look at the apaquarto documentation. Also, we recommend reading the guide APA Style via Markdown.

Footnotes

  1. For a list of Quarto extensions for specific journal formats, click here.↩︎