# Installation

Installing apaquarto is not hard, but it takes a bit more effort than installing a standalone program. There are four main steps:

1. Install Quarto
2. Install a programming language (e.g., R, Python, Julia)
3. Install a programming environment (e.g., RStudio, Positron, VS Code, Jupyter)
4. Install apaquarto

## Install Quarto

The current stable version of Quarto can be installed here.

If you use a recent version of RStudio, Quarto is already installed. If you are not sure if your version of Quarto is recent enough, there is no harm in re-installing it.

NoteHow to check which version of Quarto is installed

In a terminal, run

    Terminal

    quarto --version

## Install a Programming Language

Your primary options are

1. R
2. Python
3. Julia

TipWhat if I do not want to use any programming languages?

If you just want to use apaquarto to make APA-style documents, but do not plan to do any analyses, install R and RStudio. You do not need R for anything, but the Quarto experience will be easier in RStudio with R installed.

## Install your programming environment

At the same link for installing Quarto, there are links for selecting an environment for using Quarto. Your options include:

1. RStudio will probably give the smoothest experience to anyone new to data analysis. It is made by Posit, the same company that makes Quarto.
2. Positron is made by Posit, the same company that makes Quarto and RStudio. It is inspired by RStudio but is multi-lingual by design. Positron will likely become the default recommendation on this list when it is further along in its development.
3. VS Code works for any language. Some R users really like VS Code, but those who do will likely migrate to Positron because Positron is a data-science-specific fork of VS Code.
4. Jupyter, as its name indicates, works with `Ju`lia, `Pyt`hon, and `R`.
5. Neovim, a hyperextensible Vim-based text editor
6. Any text editor will do. Everyone has options—Quarto won’t box you in.

# Install apaquarto

What do you wish to do with apaquarto? You can create a new template file in a new project folder, or you can add the apaquarto format to an existing Quarto file.

There are two ways to install Quarto extensions like apaquarto: Anyone can use the terminal method. If you are an R user, you might prefer the R console method using the quarto package. If you are a Positron user, it is especially easy to install extensions with Mickaël Canouil’s Quarto Wizard.

- Via the terminal
- Via the R console

First open the the terminal and navigate to the folder where you want to install apaquarto.

- To create a new file
- Convert an existing document

Run this in the terminal:

    Terminal

    quarto use template wjschne/apaquarto

Run this in the terminal:

    Terminal

    quarto add wjschne/apaquarto

Entering the command above will prompt a question about whether you trust the author of the extension to not run malicious code. If you answer Yes, you will be prompted to name a new folder where the extension will be installed. Do not enter a complete file path. Just supply a folder name. This folder will be created in the folder you have navigated to.

NoteWhat is the terminal?

A terminal is an interface for telling your computer what to do. A terminal can be pulled up on most programming environments. For example, In RStudio, the terminal is in a tab next to the console (see Figure 2). If you cannot see a terminal tab next to the console, use the keyboard shortcut Alt-Shift-R to make a terminal appear (or select Tools → Terminal → New Terminal. in the RStudio menu).

Figure 1: RStudio terminal. It is okay if your console looks different from mine.

Alternatively, you can open a terminal directly on any computer:

1. Mac: Click the Launchpad icon in the Dock, type Terminal in the search field, then click Terminal.
2. Windows: Click the Windows Start Icon (or press the `Win` Win key), type `cmd`, select Command Prompt.
3. Linux: Press `Ctrl+Alt+T` Ctrl+Alt+T

NoteHow to nagivate to a folder

Suppose there is a folder on your computer at this location:

`C:/Users/myname/Documents/MyProject/`

The `cd` command means “change directory.” Thus, entering this command will “navigate” you to your desired folder:

    Terminal

    cd "C:/Users/myname/Documents/MyProject/"

NotePasting commands into the terminal

In many terminals, the “paste” shortcut is different from what you might be used to (i.e., `Ctrl+Shift+V` Ctrl+Shift+V instead of `Ctrl+V` Ctrl+V). If that does not work, try right-clicking and selecting `paste`. If all else fails, just type the command.

If you are an R user, you can install extensions with the quarto package using the R Console.

1. Set the working directory to the folder where you want the template to be installed.
2. In the R console, run this code:

- Create a new file
- Convert an existing document

    quarto::quarto_use_template("wjschne/apaquarto", no_prompt = TRUE)

    quarto::quarto_add_extension("wjschne/apaquarto", no_prompt = TRUE)

A prompt may ask if you trust the author not to place malicious code on your machine. To proceed, answer `Yes` or just `Y`.

NoteWhat is the R Console?

The console is for entering R commands. In RStudio, it is in the lower left pane by default. See Figure 2. It is okay if your console looks different from mine.

Figure 2: RStudio console

To use the console, type a command and press `Enter` Enter.

NoteWhat is the quarto package?

The quarto package is not Quarto itself, but it provides convenient functions to interact with Quarto. You will need a recent version of the quarto package (version 1.4 or higher).

If the quarto package is not installed, you can can install it by running this code in the console:

    install.packages("quarto")

Alternatively, in RStudio’s lower right pane:

1. Select the Packages tab.
2. Click the Install button.
3. Enter “quarto” in the input box.
4. Click Install.

NoteHow to set the working directory

Suppose there is a folder on your computer at this location:

`C:/Users/myname/Documents/MyProject/`

You can set the working directory in the R console with this command

    setwd("C:/Users/myname/Documents/MyProject/")

Alternatively, you can set the working directory in the RStudio menu:

1. Select Session → Set Working Directory → Choose Directory

Set Working Directory Via RStudio Menu

2. Navigate to a folder where you want to create a new folder.

NoteHow to skip the prompts

Run the `quarto_use_template` function with the `no_prompt` option set to `TRUE`:

    quarto::quarto_use_template("wjschne/apaquarto", no_prompt = TRUE)

NoteHow to inspect the code before installing it

The apaquarto source code is in this repository. Installing the extension will install the contents of the `_extensions/apaquarto` folder. If you install the template, it will install the `template.qmd` file and rename it to the name of the folder you install the template to. In addition, these files will be installed:

- bibliography.bib
- README.md
- example.qmd

### After installing apaquarto

Setting up an initial file is most easily done with this web app.

Of course, you can always create an apaquarto file from scratch,

If you made a…

#### A new file

If you create a new apaquarto file, you will see a template file in the folder you select. The template file will have the same name as the folder you installed the template to and ends with `.qmd`.

The example.qmd file has most of the options already filled out and explains how and why to change them. It also has a examples of how to use the extension in the text.

It is recommended for RStudio users to use apaquarto inside a project. To create project for an existing directory, see here.

#### An existing file

Once the extension is installed, you still need to change the output format of your document. You can select one or more of three formats: .docx, .pdf, or .html. You can add all of these formats or any combination of them:

To include all four formats, add this to your .qmd file’s yaml `format` option:

    format:
      apaquarto-docx: default
      apaquarto-html: default
      apaquarto-pdf: default
      apaquarto-typst: default

When writing, I prefer to output to .html, because it renders quickly. Then I switch to .docx or .pdf, depending on where I need to submit the paper.

Here is a minimal example of what the YAML metadata might look like:

    ---
    title: "My Paper's Title: A Full Analysis of Everything"
    shorttitle: "My Paper's Title"
    author:
      - name: W. Joel Schneider
        corresponding: true
        orcid: 0000-0002-8393-5316
        email: schneider@temple.edu
        affiliations:
          - name: Temple University
            department: College of Education and Human Development
            address: 1301 Cecil B. Moore Ave.
            city: Philadelphia
            region: PA
            postal-code: 19122-6091
    abstract: "This is my abstract."
    keywords: [keyword1, keyword2]
    author-note:
      disclosures:
        conflict of interest: The author has no conflict of interest to declare.
    bibliography: mybibfile.bib
    format:
      apaquarto-docx: default
      apaquarto-html: default
      apaquarto-pdf: default
      apaquarto-typst: default
    ---