Getting Started with Quarto + apaquarto in VS Code

This guide walks through setting up a complete APA 7 writing environment using Quarto, apaquarto, VS Code, Zotero, and Claude Code. By the end, you'll have a streamlined workflow for writing and citing research documents that automatically format to APA 7 standards.

Part 1: Installation and Configuration

Prerequisites

Before starting, ensure you have:

macOS with Homebrew installed (/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)")
VS Code installed
Admin privileges to install software
Approximately 30-45 minutes for complete setup

Step 1: Install Core Tools

Open Terminal and run these commands sequentially:

# Install Quarto
brew install quarto

# Verify installation
quarto --version
# Should output something like: 1.6.39

# Install Pandoc (Quarto includes it, but having the standalone version is useful)
brew install pandoc

# Install LaTeX for PDF output (optional but recommended - this is large, 2-4GB)
brew install --cask mactex-no-gui
# Alternative lighter option:
# brew install --cask basictex

If you skip LaTeX, you can still generate Word and HTML output. PDF output requires LaTeX.

Step 2: Install and Configure Zotero

# Install Zotero
brew install --cask zotero

Manual steps for Better BibTeX:

Download Better BibTeX from https://github.com/retorquere/zotero-better-bibtex/releases/latest
Get the .xpi file (e.g., zotero-better-bibtex-6.7.246.xpi)
Open Zotero → Tools → Add-ons
Click the gear icon → "Install Add-on From File"
Select the downloaded .xpi file
Restart Zotero

Configure Better BibTeX settings:

Zotero → Settings → Better BibTeX
Citation keys tab:
- Citation key format: [auth:lower][year] (produces keys like smith2023)
- OR use: [auth:lower][shorttitle3_3][year] (produces smithlearning2023)
Automatic export tab:
- Check "Automatic export"
- Set format to "Better BibLaTeX"

Step 3: Configure VS Code

Install required extensions:

Open VS Code
Press Cmd+Shift+X to open Extensions
Install these extensions:
- Quarto (by Quarto)
- Citation Picker for Zotero (by mblode) - critical for citation workflow
- Markdown All in One (by Yu Zhang) - optional but helpful
- Code Spell Checker (by Street Side Software) - recommended

Configure Citation Picker:

Press Cmd+, to open Settings
Search for "citation picker"
Configure:
- Zotero Port: 23119 (default)
- Citation format: pandoc
- Style: apa (or leave blank to use document's CSL)

Test Zotero connection:

Make sure Zotero is running
In VS Code, press Cmd+Shift+P → type "Citation Picker: Pick"
You should see your Zotero library appear
Press Esc to close

Step 4: Set Up Your Project Directory

Create a dedicated folder structure for your dissertation or research project:

# Navigate to where you keep your projects
cd ~/Documents

# Create project directory
mkdir my-dissertation
cd my-dissertation

# Create subdirectories
mkdir figures tables data appendices

# Initialize as a Git repository (recommended)
git init

Step 5: Install apaquarto Extension

In Terminal, from your project directory:

# Install apaquarto extension
quarto add wjschne/apaquarto

# When prompted:
# - "Do you trust the authors?" → Type 'Y'
# - Creates _extensions/apaquarto/ directory

Step 6: Configure Zotero Auto-Export

This ensures your bibliography stays in sync automatically:

Open Zotero
Right-click your main library (or a specific collection)
Select "Export Library" (or "Export Collection")
Choose format: "Better BibLaTeX"
Check: ☑ "Keep Updated"
Save as references.bib in your project directory (~/Documents/my-dissertation/)

Now whenever you add/modify citations in Zotero, the file updates automatically.

Part 2: Creating Your First APA 7 Document

Step 1: Create the Manuscript File

In VS Code:

Open your project folder: File → Open Folder → select my-dissertation
Create new file: manuscript.qmd
Add the YAML header:

---
title: "The Impact of AI-Assisted Learning Analytics on Student Engagement"
shorttitle: "AI Learning Analytics"
author:
  - name: Christopher Anderson
    corresponding: true
    orcid: 0000-0002-1234-5678
    email: your.email@boisestate.edu
    affiliations:
      - name: Boise State University
        department: Department of Educational Technology
        address: 1910 University Drive
        city: Boise
        region: ID
        postal-code: 83725
abstract: |
  This study examines the effectiveness of AI-assisted learning analytics in higher education contexts. Using a mixed-methods approach with 240 undergraduate students across four institutions, we investigated how real-time feedback generated by machine learning algorithms influences student engagement, metacognitive awareness, and academic performance. Results indicate significant improvements in all three domains, with effect sizes ranging from d = 0.45 to d = 0.78. Implications for instructional design and learning experience design are discussed.
keywords: [artificial intelligence, learning analytics, educational technology, student engagement, instructional design]
authornote: |
  Christopher Anderson, Department of Educational Technology, Boise State University.

  This research was supported by [Grant information if applicable].

  Correspondence concerning this article should be addressed to Christopher Anderson, Department of Educational Technology, Boise State University, 1910 University Drive, Boise, ID 83725. Email: your.email@boisestate.edu
bibliography: references.bib
csl: apa.csl
format:
  apaquarto-docx: default
  apaquarto-pdf: default
  apaquarto-html: default
---

Step 2: Download the APA 7 CSL File

# From your project directory
curl -o apa.csl https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl

Or download manually from the Citation Style Language repository and save as apa.csl in your project root.

Step 3: Add Document Content

Below the YAML header, start writing your document:

# Introduction

The integration of artificial intelligence in educational contexts has fundamentally transformed how institutions approach student support and intervention. Learning analytics—the measurement, collection, analysis, and reporting of data about learners and their contexts—has evolved from descriptive dashboards to predictive and prescriptive systems powered by machine learning algorithms.

Recent meta-analyses suggest that timely, personalized feedback represents one of the most powerful influences on learning outcomes, with effect sizes exceeding d = 0.70 in well-designed interventions. However, the scalability of such interventions has historically been limited by resource constraints. AI-assisted systems promise to address this gap by automating the generation of contextual feedback based on behavioral patterns, assessment performance, and engagement metrics.

## Theoretical Framework

This study draws on three complementary theoretical perspectives: self-regulated learning theory, cognitive load theory, and the Universal Design for Learning framework. Each contributes to understanding how AI-mediated feedback might influence student outcomes.

### Self-Regulated Learning

[Continue with your content...]

# Method

## Participants

We recruited 240 undergraduate students (165 female, 72 male, 3 non-binary; M_age = 20.3 years, SD = 2.1) from four institutions...

## Materials

### AI Learning Analytics Platform

The intervention used a custom-built learning analytics platform that...

## Procedure

[Continue with your methodology...]

# Results

## Preliminary Analyses

Before examining our primary research questions, we conducted preliminary analyses to...

## Primary Outcomes

[Continue with results...]

# Discussion

Our findings demonstrate that AI-assisted learning analytics can significantly improve student engagement and academic performance when implemented with careful attention to...

# References

::: {#refs}
:::

Important APA 7 conventions:

Use level 1 headings (#) for major sections
Use level 2 (##) for subsections
Use level 3 (###) for sub-subsections
The {#refs} div is where apaquarto automatically inserts your reference list

Part 3: Writing and Citing with Zotero

Adding Citations: The Easy Way

With Zotero running and Citation Picker installed:

Position your cursor where you want a citation
Press Option+Z (or Alt+Z on non-Mac)
Type to search your library (searches authors, titles, years)
Select the source with arrow keys
Press Enter

What gets inserted:

[@smith2023] for parenthetical: (Smith, 2023)
@smith2023 for narrative: Smith (2023)

Citation Syntax Reference

# Basic citations
Parenthetical: [@smith2023]
Narrative: @smith2023 found that...
Multiple sources: [@smith2023; @jones2024; @williams2022]

# With page numbers
[@smith2023, p. 45]
[@smith2023, pp. 45-47]

# With custom text
[see @smith2023, pp. 45-47, for a review]
[@smith2023, p. 45; also @jones2024]

# Suppress author (year only)
[-@smith2023]  → (2023)

# Multiple authors
First citation: [@smith2023]  → (Smith, Jones, & Williams, 2023)
Subsequent: [@smith2023]      → (Smith et al., 2023)
# apaquarto handles this automatically!

Real-World Example

Here's how a paragraph looks with proper citations:

The effectiveness of formative feedback has been extensively documented. Meta-analyses indicate effect sizes ranging from d = 0.48 to d = 0.79 [@hattie2007; @kluger1996], with the highest impacts observed when feedback is immediate, specific, and actionable [@shute2008]. However, @nicol2006 argue that feedback only improves learning when students actively process and use it to regulate their performance. This aligns with self-regulated learning theory, which emphasizes learners' agency in the feedback process [@zimmerman2002; @winne2005].

Managing Citations Without Citation Picker

If Citation Picker isn't working or you prefer manual entry:

Open Zotero
Find your source
Right-click → "Copy Citation Key" (from Better BibTeX)
In VS Code, type [@ and paste the key, then add ]

Common Citation Patterns in Your Field

Educational technology citations:

# Theory citations
Drawing on Universal Design for Learning [@rose2014], we designed...
This aligns with TPACK framework [@mishra2006]...

# Meta-analyses and reviews
As demonstrated in multiple meta-analyses [@hattie2009; @sung2017]...

# Methodological citations
We used thematic analysis following @braun2006 guidelines...
Analysis followed @strauss1998 grounded theory approach...

Part 4: Preview, Render, and Troubleshooting

Live Preview While Writing

Option 1: Quarto Preview (Recommended)

Open the integrated terminal in VS Code (Ctrl+` or Terminal → New Terminal):

quarto preview manuscript.qmd

This:

Opens a live preview in your browser
Auto-refreshes when you save changes
Shows formatted output with citations
Runs continuously until you press Ctrl+C

Option 2: VS Code Quarto Preview

Open manuscript.qmd
Click "Preview" button in the top-right (triangle icon)
OR press Cmd+Shift+K
Preview appears in VS Code panel

Rendering Final Documents

Render all formats specified in YAML:

quarto render manuscript.qmd

This creates:

manuscript.docx (Word)
manuscript.pdf (if LaTeX installed)
manuscript.html (web version)

Render specific format only:

quarto render manuscript.qmd --to docx
quarto render manuscript.qmd --to pdf
quarto render manuscript.qmd --to html

Common Issues and Solutions

Issue: "Bibliography not found"

Symptoms: Error message about missing references.bib

Solutions:

# Check if file exists
ls -la references.bib

# Verify it's in the correct location (same folder as manuscript.qmd)
pwd
# Should show your project directory

# Check Zotero auto-export is working
# In Zotero: Edit → Preferences → Better BibTeX → Automatic Export
# Verify your references.bib path is listed

Issue: "Citation key not found"

Symptoms: [@smith2023] appears literally in output instead of formatted citation

Causes and fixes:

Citation key doesn't exist in references.bib
- Open references.bib in VS Code
- Search for the key (e.g., smith2023)
- If not found, check the actual key in Zotero (Right-click → Show Better BibTeX Citation Key)
Typo in citation key
```
Wrong: [@smth2023]
Right: [@smith2023]
```

Missing @ symbol

Wrong: [smith2023]    # Appears as: [smith2023]
Right: [@smith2023]   # Appears as: (Smith, 2023)

Issue: PDF won't render

Symptoms: Error about LaTeX or pdflatex not found

Solution:

# Check if LaTeX is installed
which pdflatex

# If nothing appears, install:
brew install --cask mactex-no-gui

# After installation, close and reopen Terminal, then:
sudo tlmgr update --self
sudo tlmgr install apa7 booktabs

Issue: Citations not formatting correctly

Check these items:

Is csl: apa.csl in your YAML header?
Does apa.csl file exist in your project directory?
Try re-downloading the CSL file
Verify bibliography field points to correct file: bibliography: references.bib

Debugging with Claude Code

When encountering errors, use Claude Code to help debug:

# In VS Code terminal:
claude "I'm getting this Quarto error: [paste error message].
My project structure is: [paste output of 'ls -la'].
My YAML header is: [paste YAML].
What's wrong and how do I fix it?"

Claude Code can:

Diagnose YAML syntax errors
Check file paths and permissions
Suggest missing dependencies
Generate corrected configuration

Part 5: Using Claude Code with Zotero Integration

Claude Code Setup in VS Code

If you haven't already:

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# OR via brew
brew install anthropic/tap/claude-code

# Authenticate
claude auth login

In VS Code:

Open Command Palette (Cmd+Shift+P)
Type "Claude Code"
Configure API key if prompted

Install Zotero MCP Server for Claude Code

This MCP (Model Context Protocol) server gives Claude Code direct access to your Zotero library, enabling powerful research workflows:

# Install the Zotero MCP server
npm install -g zotero-mcp

# OR clone and install from source
cd ~/Projects
git clone https://github.com/54yyyu/zotero-mcp.git
cd zotero-mcp
npm install
npm run build

Configure MCP Server

For Claude Desktop (if you use it), add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zotero": {
      "command": "npx",
      "args": ["-y", "zotero-mcp"]
    }
  }
}

For Claude Code in VS Code, the MCP server should auto-detect when Zotero is running. Verify with:

# Start Zotero first
# Then test the connection
claude "Search my Zotero library for papers about AI in education"

If Claude Code can access Zotero, it will return actual results from your library. If not, you may need to configure the connection manually in your Claude Code settings.

Verify Zotero MCP Server Installation

# Ensure Zotero is running
# Then test individual MCP functions

# Search your library
claude "Use the Zotero MCP to search for papers by Hattie"

# Get recent items
claude "Show me my 5 most recent additions to Zotero"

# Search by tag
claude "Find all items in my Zotero library tagged with 'learning-analytics'"

If these work, you're ready to leverage Claude Code's full Zotero integration

Practical Use Cases for Claude Code with Zotero

1. Search Zotero and Insert Citations

The game-changer: Claude Code can now search your Zotero library and insert properly formatted citations:

claude "Search my Zotero library for meta-analyses about formative feedback.
Insert citations for the 3 most relevant papers in this paragraph using
APA format." --file manuscript.qmd --lines 45-48

Claude Code will:

Query your Zotero library using the MCP server
Find relevant sources
Insert properly formatted [@citekey] citations
Ensure the citation keys match your Better BibTeX keys

2. Literature Review Assistance

claude "Search my Zotero library for papers about self-regulated learning
published after 2020. Create a brief literature review paragraph synthesizing
the main findings. Include proper in-text citations."

Output example:

Recent research on self-regulated learning emphasizes the role of metacognitive
monitoring in academic achievement [@zimmerman2021; @panadero2022]. Studies
indicate that students who engage in regular self-assessment demonstrate
significantly higher performance outcomes [@chen2023], with effect sizes
ranging from d = 0.42 to d = 0.68. However, @winne2021 caution that
self-reported measures of self-regulation may not accurately capture actual
regulatory behaviors.

3. Find Sources for Specific Claims

When you need evidence for a specific point:

claude "I'm writing about how AI can provide personalized feedback at scale.
Search my Zotero library for relevant sources that discuss scalability of
personalized learning interventions. Suggest 2-3 citations I should use."

Claude Code returns:

Relevant papers from your library
Brief summaries of why they're relevant
The citation keys to use
Suggestions for how to cite them

4. Build Reference Sections

claude "Search my Zotero library for all papers tagged 'dissertation-lit-review'.
Generate a formatted list of these references in APA 7 style."

This creates a ready-to-review reference list from your tagged sources.

5. Generate Annotated Bibliographies

claude "Get the full text and metadata for these items from Zotero:
[@smith2023; @jones2024; @williams2022]. Create a 2-3 sentence annotation
for each describing their relevance to AI-assisted learning analytics."

6. Check Citation Coverage

claude "Scan my manuscript.qmd file and extract all citations. Then check
my Zotero library to verify all cited works are in my references.bib.
Report any missing items."

This catches missing references before you render your document.

7. Generate Thematic Summaries

claude "Search my Zotero library for papers with 'Universal Design for Learning'
in the title or tags. Group them by publication year and create a brief summary
of how the research focus has evolved over time."

8. Smart Citation Suggestions

While writing, ask for relevant sources:

claude "I'm writing about the effectiveness of immediate feedback in online
learning. What papers in my Zotero library would support this claim?
Suggest specific citations with the relevant findings."

9. Export Specific Collections

claude "Get all items from my Zotero collection named 'Dissertation - Chapter 2'.
Create a markdown file listing them with full citations and brief notes."

10. Generate Method Section Citations

claude "I used thematic analysis in my research. Search my Zotero library
for methodological papers about thematic analysis (Braun & Clarke preferred).
Write a proper methods paragraph citing the appropriate source."

Output:

We employed reflexive thematic analysis following the guidelines established
by @braun2006 and later refined by @braun2019. This approach emphasizes the
researcher's active role in identifying patterns and constructing themes from
the data rather than simply discovering pre-existing meanings.

Complete Workflow Summary

Daily Writing Routine

Start Zotero (required for MCP server access)
Open project in VS Code
Start preview: quarto preview manuscript.qmd
Research and write:
- Use Claude Code to search Zotero: claude "Find papers about [topic]"
- Claude Code inserts citations automatically
- Write in markdown with AI assistance
- Press Option+Z for manual citation insertion when preferred
- Save frequently (auto-refresh preview)
Use Claude Code for:
- Finding relevant sources from your library
- Converting notes to prose with proper citations
- Checking citation formatting
- Generating tables/figures
- Building literature review sections
Verify citations: Preview renders citations correctly
Render draft: quarto render manuscript.qmd when ready to share

Next Steps

Now that your environment is configured:

Verify Zotero MCP integration:

# With Zotero running
claude "Search my Zotero library for your 5 most recent items"
# Should return actual papers from your library

Create your first document using the templates above

Test the complete citation workflow:

claude "Search my Zotero library for papers about learning analytics.
Help me write a paragraph introducing this topic with 3-4 citations."

Add 5-10 key citations to Zotero and verify auto-export to references.bib
Render all three formats (DOCX, PDF, HTML) to verify setup:
```
quarto render manuscript.qmd
```
Experiment with Claude Code's Zotero integration:
- Search for papers by topic
- Generate literature review paragraphs
- Build annotated bibliographies
- Check citation coverage

Set up Git for version control:

git init
git add .
git commit -m "Initial dissertation setup with Quarto + Zotero MCP"

Organize your Zotero library with tags and collections that mirror your document structure
Practice the research-to-writing pipeline:
- Find papers → Add to Zotero → Tag appropriately
- Use Claude Code to search and cite
- Preview in Quarto
- Refine with AI assistance
- Render final output