APA Style via Markdown

(Under Construction)

A good place to start learning about writing Quarto documents is here. I will cover material needed to use apaquarto to write an APA Style document in Markdown text.

Markdown makes writing in a consistent style straightforward and easy. Its plain-text format was designed to be easy to read and easy to write, yet also flexible and specific enough that it could be converted automatically into fully formatted documents.

If you are used to writing with a word processor (e.g., MS Word, Google Docs), it might feel disconcerting to not see what the document will look like as you type. This feeling will pass, and the benefits of typing in a plain-text format will become evident. While writing in APA style, the plain-text Markdown approach prevents the introduction of many inconsistencies and makes it much easier to spot and fix any inconsistencies that are already present.

Create a Quarto Document

To create an Quarto document in RStudio, in the menu (See Figure 1), click File → New File → Quarto Document.

Figure

Create new Quarto docuemnt from the RStudio men

The resulting file can be edited. Here is an annotated example of a short Quarto document:

---                                
1title: "My Title"
author: "W. Joel Schneider"
---                                

2This is plain text.
A pair asterisks makes *italics*.
Two asterisks will **bold** text.

3```{r}
x <- 5
```

1: The yaml between pairs of three hyphens (---) contains “metadata” (information about the document). Yaml
2: Markdown text below the yaml becomes part of the document’s content.
3: Anything between pairs of three backticks (```) is code. The r between the curly braces ({r}) means to run the code in R rather than some other language (e.g., Python or Julia). In this example, x <- 5 means “Define a new variable x to be equal to 5.”

Basic Styling

A comprehensive guide to Markdown conventions in Quarto is here. Some highlights:

Formatting	Markdown	Rendered Text
Italic	`An italicized phrase`	An italicized phrase.
Bold	`A bolded word`	A bolded word
_Subscript	`H~2~O`	H₂O
^Superscript	`21^st^`	21^st
En dash (–)	`6--8 hours of sleep`	6–8 hours of sleep
Em dash (—)	`It wasn't good---it was the best!`	It wasn’t good—it was the best!
Bullet List	`* Item A * Item B * Item C`	Item A Item B Item C
Numeric List	`1. Item A 2. Item B 3. Item C`	Item A Item B Item C
Block Quote	`> Short cuts make long delays. --- J.R.R. Tolkien`	Short cuts make long delays. — J.R.R. Tolkien

Headings in APA Style

APA Style differentiates between headings at 5 levels. All headings should be in title case according to these rules and exceptions.

Tip

Quarto works best when there is at least one blank line above and below the heading. If you forget to follow this advice, Quarto will try its best, but it might not parse the document correctly.

In markdown, a heading starts with the #, followed by a space, and then the text of the heading. The number of #s in a row determines the level of the heading:


# Level 1 Heading

## Level 2 Heading

### Level 3 Heading

#### Level 4 Heading

##### Level 5 Heading

Level 1 Headings

APA Style reserves a small number of level-1 headings with standard names:

Method
Results
Discussion
References
Appendices

There should be no level-1 heading for the introduction. The title acts as the heading for the introduction, and apaquarto places it there automatically.

Levels 2–5

Readers are better able to follow your ideas if you differentiate long sections in your document with headings. I try limit my writing to just levels 1 and 2, but sometimes level 3 headings are needed. I am sparing to the point of stinginess with levels 4 and 5.

What Can Follow a Heading

Anything can follow immediately after headings at levels 1–3, including other headings.
Headings at levels 4 and 5 must have text paragraphs below them. Why? When rendered, level-4 and level-5 headings appear on the same line as the paragraphs they summarize.


# Level 1 Heading

This paragraph follows the level-1 heading.

## Level 2 Heading 

### This Level-3 Heading Directly Follows the Level-2 Heading.

This paragraph follows the level-3 heading.

#### Level 4 Heading

This paragraph will appear on the same line as the level-4 heading.

Subsequent paragraphs go on their own lines.

##### Level 5 Heading

This paragraph will appear on the same line as the level-5 heading.

Subsequent paragraphs go on their own lines.

Level 1 Heading

This paragraph follows the level-1 heading.

Level 2 Heading

This Level-3 Heading Directly Follows the Level-2 Heading.

This paragraph follows the level-3 heading.

Level 4 Heading.

This paragraph will appear on the same line as the level-4 heading.

Subsequent paragraphs go on their own lines.

Level 5 Heading.

This paragraph will appear on the same line as the level-5 heading.

Subsequent paragraphs go on their own lines.

Block Quotes and Suppressing Indentation

Sometimes you want to give a longer quote that needs to go in its own paragraph. Block quotes are on their own line starting with the > character. For example, Jane Austen’s (1814/1990) Mansfield Park has some memorable insights about the mind:

> If any one faculty of our nature may be called more wonderful than the rest, I do think it is memory. There seems something more speakingly incomprehensible in the powers, the failures, the inequalities of memory, than in any other of our intelligences. The memory is sometimes so retentive, so serviceable, so obedient; at others, so bewildered and so weak; and at others again, so tyrannic, so beyond control! We are, to be sure, a miracle every way; but our powers of recollecting and of forgetting do seem peculiarly past finding out. (p. 163)

If your quote has multiple paragraphs, like this passage from Brown (2012), separate them with a lone > character between the lines:



> In the entire field of astronomy, there is no word other than planet that has a precise, lawyerly definition, in which certain criteria are specifically enumerated. Why does planet have such a definition but star, galaxy, and giant molecular cloud do not? Because in astronomy, as in most sciences, scientists work by concepts rather than by definitions. The concept of a star is clear; a star is a collection of gas with fusion reactions in the interior giving off energy. A galaxy is a large, bound collection of stars. A giant molecular cloud is a giant cloud of molecules. The concept of a planet—in the eight-planet solar system—is equally simple to state. A planet is a one of a small number of bodies that dominate a planetary system. That is a concept, not a definition. How would you write that down in a precise definition?
>
> I wouldn’t. Once you write down a definition with lawyerly precision, you get the lawyers involved in deciding whether or not your objects are planets. Astronomers work in concepts. We rarely call in the attorneys for adjudication. (p. 242)

If the text after a quote is a new paragraph, you can create it in the usual fashion (i.e., plain text with an empty line between the block text and the new paragraph). However, if the text after a quote is part of the same paragraph, you can suppress the indentation by creating a div with the .NoIndent class. As an example:

Initial paragraph

> Block quote paragraph

:::{.NoIndent}
Because this sentence continues the intial paragraph, 
the indentation is suppresed.
:::

Figures

Plots for figures can be created via code chunks. A pre-existing figure can be imported directly via markdown.

Figures in Code Chunks

Code chunk (also known as code blocks) are special sections of a Quarto document that run code. Quarto supports many programming languages, but I will focus on R.

An empty code chunk looks like this:

```{r}

```

Those are not single quotes (') that fence in the code chunk. Those are backticks (`), which are usually above the Tab key on most keyboards in the US.

Figure

Keyboard with backtick hightlighted

Directly typing the three backticks and the curly braces needed for a code chunk can be tedious. In RStudio, use the keyboard shortcut to create chunks. If keyboard shortcuts are hard to remember, there is a green button with a white “C” in RStudio’s toolbar that creates code chunks. Insert Code Chunk Button

At a minimum, an APA-Style figure needs a unique label with the fig- prefix, a caption in title case specified with fig-cap, and code for the plot.

```{r}
#| label: fig-myplot
#| fig-cap: This Is the Figure Caption.
library(tidyverse)
tibble(x = seq(0, 8, .01),
       y = dlnorm(x)) %>% 
  ggplot(aes(x,y)) + 
  geom_area(fill = "royalblue", alpha = .5)
```

Code chunk options like label and and fig-cap options are preceded by #|. They tell Quarto about how to run the code and present it the document.

Notes below Figures and Tables

You can add a note below a figure or table with the chunk option apa-note. The note can have markdown formatting (e.g, bolding and italics).

```{r}
#| label: fig-myplot2
#| fig-cap: This Is the Figure Caption.
#| apa-note: This is the note below the figure.

library(tidyverse)
tibble(x = seq(0, 1, .001),
       y = dbeta(x,8,2)) %>% 
  ggplot(aes(x,y)) + 
  geom_area(fill = "royalblue", alpha = .5)
```

Note. This is the note below the figure.

Importing Figures with Markdown

Comprehensive details on importing and formatting figures with Markdown is here.

The Markdown syntax for creating a figure is

![caption](file){#fig-label}

For example,

![My Caption](myimage.png){#fig-myimage}

Note that in this context the figure label must start with #fig-. Additional information can be inserted into the curly braces. Some common options:

fig-alt An accessible description of the image. It is usually not immediately visible, but it is available to a screen reader.
width Image width
apa-note A note below the figure

For example, in the same same folder as my Quarto document, there is an image file sampleimage.png. We can display this image like so:

![A Simple Mediation Model](sampleimage.png){
  #fig-myimportedimage 
  width="5in" 
  fig-alt="A mediation model in which A causes B, and B causes C." 
  apa-note="Variable A indirectly causes Variable C."
  }

A path diagram in which A causes B, and B causes C. — Figure

A Simple Mediation Model

Note. Variable A indirectly causes Variable C.

Figure References

In APA style, we often refer to specific tables and figures by their order in the text (e.g., Figure 2, Table 4). Keeping track of which is which is a pain, especially if you decide to reorder them. In Quarto documents, we instead refer to their labels, which are converted to the right numbers later. To refer to the figure created by the code above, we would type @fig-myplot, which will be converted to Figure 3.

Tables

As with figures, we can create tables in code chunks or make them directly with Markdown.

Tables in Code Chunks

The chunk label must begin with tbl- instead of fig-. The caption is set with tbl-cap. I like making tables with flextable because it ports to to the .docx format without hassle.

```{r}
#| label: tbl-mytable
#| tbl-cap: My Table
#| ft.align: left
#| apa-note: A note below table
library(tidyverse)
library(flextable)

tibble(Letters = c("A", "B", "C"), 
       Numbers = 1:3) %>% 
  flextable() %>% 
  theme_apa() 
```

Table

My Table

Letters	Numbers
A	1
B	2
C	3

Note. A note below table

Tables Made Directly with Markdown

You can create tables with Markdown in several ways. See here for details. If you need to make a more complex table in Markdown, I suggest using RStudio’s visual editor. Here is an example of a simple table:


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

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

Table

My Caption

Letters	Numbers
A	1
B	2
C	3

Note. Note below table

Tables and Figures Spanning Two Columns in Journal Mode (.pdf)

When creating tables and figures in journal mode, care must be taken not to make figures and tables wider than the columns, otherwise sometimes makes them disappear (and sometimes takes large swaths of text with it).

You can make figures and tables span the two columns by setting the apa-twocolumn chunk option to true. This will only affect .pdf documents when in journal mode (i.e., documentmode: jou).

```{r}
#| label: fig-myplot3
#| fig-cap: A Figure that Will Span Two Columns in Journal Mode
#| apa-twocolumn: true

library(tidyverse)
tibble(x = seq(0, 1, .001),
       y = dbeta(x,2,8)) %>% 
  ggplot(aes(x,y)) + 
  geom_area(fill = "royalblue", alpha = .5)
```

Figure

A Figure that Will Span Two Columns in Journal Mode

Citations

See here for instructions on setting up citations and references.

I recommend managing your citations in Zotero and exporting them to a file automatically using the BetterBibTex addon. Installation instructions.

The apa.csl file is already included in apaquarto so there is no need to supply a reference to it in your metadata.

Parenthetical Citations

A parenthetical citation uses the reference label in square brackets and starts with @ like so:

A sentence that needs a citation [@CameronTrivedi2013].

A sentence that needs a citation (Cameron & Trivedi, 2013).

With Multiple Citations

2 or more citations are separated by a semicolon: [@CameronTrivedi2013; @cohen2003applied] becomes (Cameron & Trivedi, 2013; Cohen et al., 2003).

With Page Numbers

Page references (or any other suffixes) are placed after the reference. If you want a comma, you’ll need to insert it yourself: [@CameronTrivedi2013, pp. 35--41] becomes (Cameron & Trivedi, 2013, pp. 35–41).

With Prefixes

Prefixes (with or without a comma) are placed before the reference: [e.g., @CameronTrivedi2013] becomes (e.g., Cameron & Trivedi, 2013).
If you need a prefix at the beginning of 2 or more citations, you will have rearrange the citations so that the prefix accompanies the citation that is first alphabetically (e.g., Cameron & Trivedi, 2013; Cohen et al., 2003). That is, [e.g., @CameronTrivedi2013; @cohen2003applied], not [e.g., @cohen2003applied; @CameronTrivedi2013].
Any prefixes or suffixes needing a literal semicolon will confuse Quarto (actually Pandoc). To make it clear that you need to print a semicolon, put a backslash before the semicolon: First Outer Inner Last [FOIL\;@CameronTrivedi2013] becomes First Outer Inner Last (FOIL; Cameron & Trivedi, 2013).

Warning

This “escaped backslash in front of the semicolon trick” is a hack. When you switch to Visual Mode in RStudio, it thinks you made a mistake, and it removes the backslash. If the citation above looks wrong, it is because I forgot to fix it after switching to visual mode and back. I reported this bug to the developers of RStudio. I hope the bug will be fixed soon.

In-Text Citations

Typically, a plain citation works without any fuss:

@CameronTrivedi2013 said some interesting things.

Cameron and Trivedi (2013) said some interesting things.

Warning

Outside of apaquarto, a limitation of the .csl format requires a special filter to change the separator for multiple authors from & toand. If you render your document in a different format, @CameronTrivedi2013 will be “Cameron & Trivedi (2013).”

With Page Numbers

If you need to include page references, use square brackets afterwards:

@CameronTrivedi2013 [pp. 101--103] said some interesting things.

Cameron and Trivedi (2013, pp. 101–103) said some interesting things.

Possessive Citations

An experimental feature of apaquarto is automatic “possessive citations.” @CameronTrivedi2013 ['s] position becomes Cameron and Trivedi’s (2013) position.

If you render your document in another format, you would need to supply the name in text like this: Cameron and Trivedi's [-@CameronTrivedi2013] position, which becomes Cameron and Trivedi’s (2013) position. This works because putting a hyphen before the reference [-@CameronTrivedi2013] becomes (2013).

Citations for Articles Included in a Meta-Analysis

In a meta-analysis, all studies included in the meta-analysis should appear in the References section but ordinarily should not be cited in the text. Quarto allows references not cited in the text to appear in the References section when they are listed in the the nocite field in the metadata. All articles listed in the nocite field will be marked with an asterisk in the References section.

nocite: |
  @schneider2015intelligence, @schneider2012cattell

If marking nocite studies with asterisk is unwanted, set the meta-analysis field to false,

meta-analysis: false
nocite: |
  @schneider2015intelligence, @schneider2012cattell

Masked Citations for Anonymous Peer Review

Suppose you want to cite a previous reference of yours, but your anonymity is supposed to be protected in the review process. You can “mask” any citation you wish by setting the mask field in the metadata yaml to true. Then list all citations that need to be masked in the masked-citations field like so:

mask: true
masked-citations:
  - schneider2015intelligence
  - schneider2012cattell

If the mask field is set to false, the masked citations will print as usual. When mast is true, depending if they are an inline or parenthetical citations, they will be listed as “Masked Citations (n.d)” or “(Masked Citations, n.d)”. In parenthical citations, it is possible to mix masked and unmasked citations.

Setting mask to true will also remove the authors, affiliations, and author notes from the title page.

Appendices

If there is just just one appendix, put a level-1 header called Appendix after the references:

# Appendix

Text in appendix

If there are multiple appendices, begin each with level-1 headers, called Appendix A, Appendix B, Appendix C, and so forth. You can place titles of appendices as level-1 headers.

# Appendix A

# Title of Appendix A

Text in Appendix A

# Appendix B

# Title of Appendix B

Text in Appendix B

References

Austen, J. (1990). Mansfield Park. Oxford University Press. (Original work published 1814)

Brown, M. (2012). How I killed Pluto and why it had it coming. Spiegel & Grau.

Cameron, A. C., & Trivedi, P. K. (2013). Regression analysis of count data (2nd ed.). Cambridge University Press. https://doi.org/10.1017/CBO9781139013567

Cohen, J., Cohen, P., West, S. G., & Aiken, L. S. (2003). Applied multiple regression/correlation analysis for the behavioral sciences (3rd ed.). Lawrence Erlbaum Associates.