+ "markdown": "---\ntitle: \"Installation\"\nengine: knitr\nlightbox: true\n---\n\n\n::: {.cell}\n\n:::\n\n\n\nInstalling apaquarto is not hard, but it takes a bit more effort than installing a standalone program. There are four main steps:\n\n1. Install Quarto\n2. Install a programming language (e.g., R, Python, Julia)\n3. Install a programming environment (e.g., RStudio, Positron, VS Code, Jupyter) \n4. Install apaquarto\n\n\n## Install Quarto\n\nThe current stable version of Quarto can be installed [here](https://quarto.org/docs/get-started/). \n\nIf you use a recent version of [RStudio](https://posit.co/download/rstudio-desktop/), 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.\n\n:::{.callout-note collapse=true}\n## How to check which version of Quarto is installed\n\nIn a [terminal](https://docs.posit.co/ide/user/ide/guide/tools/terminal.html), run\n\n\n::: {.cell filename='Terminal'}\n\n```{.bash .cell-code}\nquarto --version\n```\n:::\n\n\n\n:::\n\n## Install a Programming Language \n\nYour primary options are\n\n1. [R](https://www.r-project.org/)\n2. [Python](https://www.python.org/)\n3. [Julia](https://julialang.org/)\n \n\n:::{.callout-tip collapse=true}\n\n### What if I do not want to use any programming languages?\n\nIf 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.\n:::\n\n\n## Install your programming environment\n\nAt the [same link for installing Quarto](https://quarto.org/docs/get-started/), there are links for selecting an environment for using Quarto. Your options include:\n\n1. [RStudio](https://posit.co/download/rstudio-desktop/) will probably give the smoothest experience to anyone new to data analysis. It is made by Posit, the same company that makes Quarto.\n2. [Positron](https://positron.posit.co/) 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.\n3. [VS Code](https://code.visualstudio.com/) 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.\n4. [Jupyter](https://jupyter.org/), as its name indicates, works with `Ju`lia, `Pyt`hon, and `R`.\n5. [Neovim](https://neovim.io/), a hyperextensible Vim-based text editor\n6. [Any text editor](https://quarto.org/docs/get-started/hello/text-editor.html) will do. Everyone has options---Quarto won't box you in.\n\n# Install apaquarto\n\nWhat 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.\n\nThere 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](https://github.com/mcanouil/quarto-wizard).\n\n\n:::: {.panel-tabset .nav-pills}\n\n### Via the terminal\n\nFirst open the the terminal and navigate to the folder where you want to install apaquarto.\n\n\n\n\n:::{.panel-tabset .nav.pills}\n\n#### To create a new file\n\nRun this in the terminal:\n\n\n::: {.cell filename='Terminal'}\n\n```{.bash .cell-code}\nquarto use template wjschne/apaquarto\n```\n:::\n\n\n#### Convert an existing document\n\nRun this in the terminal:\n\n\n::: {.cell filename='Terminal'}\n\n```{.bash .cell-code}\nquarto add wjschne/apaquarto\n```\n:::\n\n\n:::\n\nEntering the command above will prompt a question about whether you trust [the author](https://wjschne.github.io/) 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.\n\n:::{.callout-note collapse=true}\n\n#### What is the terminal?\n\nA 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 @fig-console). 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).\n\n{#fig-terminal}\n\nAlternatively, you can open a terminal directly on any computer:\n\n1. [Mac](https://support.apple.com/en-in/guide/terminal/welcome/mac): Click the Launchpad icon in the Dock, type Terminal in the search field, then click Terminal.\n2. [Windows](https://www.wikihow.com/Open-Terminal-in-Windows): Click the Windows Start Icon (or press the {{< kbd Win >}} key), type `cmd`, select Command Prompt.\n3. [Linux](https://www.wikihow.com/Open-a-Terminal-Window-in-Ubuntu): Press {{< kbd Ctrl+Alt+T >}}\n\n:::\n\n:::{.callout-note collapse=true}\n\n#### How to nagivate to a folder\n\nSuppose there is a folder on your computer at this location:\n\n`C:/Users/myname/Documents/MyProject/`\n\nThe `cd` command means \"change directory.\" Thus, entering this command will \"navigate\" you to your desired folder:\n\n\n::: {.cell filename='Terminal'}\n\n```{.bash .cell-code}\ncd \"C:/Users/myname/Documents/MyProject/\"\n```\n:::\n\n\n\n:::\n\n\n:::{.callout-note collapse=true}\n\n## Pasting commands into the terminal\n\nIn many terminals, the \"paste\" shortcut is different from what you might be used to (i.e., {{< kbd Ctrl+Shift+V >}} instead of {{< kbd Ctrl+V >}}). If that does not work, try right-clicking and selecting `paste`. If all else fails, just type the command.\n\n:::\n\n### Via the R console\n\nIf you are an R user, you can install extensions with the [quarto package](https://quarto-dev.github.io/quarto-r/) using the R Console. \n\n1. Set the working directory to the folder where you want the template to be installed. \n2. In the R console, run this code:\n\n::: {.panel-tabset .nav-pills}\n\n#### Create a new file\n\n\n::: {.cell}\n\n```{.r .cell-code}\nquarto::quarto_use_template(\"wjschne/apaquarto\", no_prompt = TRUE)\n```\n:::\n\n\n\n#### Convert an existing document\n\n\n::: {.cell}\n\n```{.r .cell-code}\nquarto::quarto_add_extension(\"wjschne/apaquarto\", no_prompt = TRUE)\n```\n:::\n\n\n:::\n\n\n\nA prompt may ask if you trust [the author](https://wjschne.github.io/) not to place malicious code on your machine. To proceed, answer `Yes` or just `Y`.\n\n\n\n:::{.callout-note collapse=true}\n\n#### What is the R Console?\n\nThe console is for entering R commands. In RStudio, it is in the lower left pane by default. See @fig-console. It is okay if your console looks different from mine.\n\n{#fig-console}\n\nTo use the console, type a command and press {{< kbd Enter >}}.\n:::\n\n:::{.callout-note collapse=true}\n\n#### What is the quarto package?\n\nThe 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).\n\nIf the quarto package is not installed, you can can install it by running this code in the console:\n\n\n::: {.cell}\n\n```{.r .cell-code}\ninstall.packages(\"quarto\")\n```\n:::\n\n\nAlternatively, in RStudio's lower right pane:\n\n1. Select the **Packages** tab.\n2. Click the **Install** button.\n3. Enter \"quarto\" in the input box.\n4. Click **Install**.\n\n:::\n\n:::{.callout-note collapse=true}\n\n## How to set the working directory\n\nSuppose there is a folder on your computer at this location:\n\n`C:/Users/myname/Documents/MyProject/`\n\n\nYou can set the working directory in the R console with this command\n\n\n::: {.cell}\n\n```{.r .cell-code}\nsetwd(\"C:/Users/myname/Documents/MyProject/\")\n```\n:::\n\n\n\nAlternatively, you can set the working directory in the RStudio menu:\n\n1. Select *Session → Set Working Directory → Choose Directory*\n\n\n\n2. Navigate to a folder where you want to create a new folder.\n\n\n:::\n\n\n\n:::{.callout-note collapse=true}\n\n#### How to skip the prompts\n\nRun the `quarto_use_template` function with the `no_prompt` option set to `TRUE`:\n\n\n::: {.cell}\n\n```{.r .cell-code}\nquarto::quarto_use_template(\"wjschne/apaquarto\", no_prompt = TRUE)\n```\n:::\n\n\n:::\n\n:::{.callout-note collapse=true}\n\n#### How to inspect the code before installing it\n\nThe apaquarto source code is in [this repository](https://github.com/wjschne/apaquarto). 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:\n\n- bibliography.bib\n- README.md\n- example.qmd\n\n:::\n\n\n\n::::\n\n### After installing apaquarto\n\nSetting up an initial file is most easily done with [this web app](https://wjschne.github.io/apa7maker/).\n\nOf course, you can always create an apaquarto file from scratch, \n\n\nIf you made a...\n\n#### A new file\n\nIf 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`. \n\n\nThe 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.\n\nIt is recommended for RStudio users to use apaquarto inside a project. To create project for an existing directory, see [here](https://support.posit.co/hc/en-us/articles/200526207-Using-RStudio-Projects). \n\n\n#### An existing file\n\nOnce 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:\n\nTo include all four formats, add this to your .qmd file's yaml `format` option:\n\n``` yaml\nformat:\n apaquarto-docx: default\n apaquarto-html: default\n apaquarto-pdf: default\n apaquarto-typst: default\n```\n\nWhen 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.\n\n\nHere is a minimal example of what the YAML metadata might look like:\n\n``` yaml\n---\ntitle: \"My Paper's Title: A Full Analysis of Everything\"\nshorttitle: \"My Paper's Title\"\nauthor:\n - name: W. Joel Schneider\n corresponding: true\n orcid: 0000-0002-8393-5316\n email: schneider@temple.edu\n affiliations:\n - name: Temple University\n department: College of Education and Human Development\n address: 1301 Cecil B. Moore Ave.\n city: Philadelphia\n region: PA\n postal-code: 19122-6091\nabstract: \"This is my abstract.\"\nkeywords: [keyword1, keyword2]\nauthor-note:\n disclosures:\n conflict of interest: The author has no conflict of interest to declare.\nbibliography: mybibfile.bib \nformat:\n apaquarto-docx: default\n apaquarto-html: default\n apaquarto-pdf: default\n apaquarto-typst: default\n---\n\n```\n\n\n\n\n\n\n\n\n\n\n\n",
0 commit comments