# zoteR

An R interface to [Zotero](https://www.zotero.org/) via the [Better BibTeX](https://retorque.re/zotero-better-bibtex/) add-on. zoteR lets you insert citations, fetch bibliography data, and keep bibliography files in sync with your Zotero library — all from R, with RStudio addin support.

## Prerequisites

- [Zotero](https://www.zotero.org/download/) must be installed and running
- [Better BibTeX for Zotero](https://retorque.re/zotero-better-bibtex/installation/) must be installed

## Installation

```r
# install.packages("pak")
pak::pkg_install("sarcastic-scientist/zoteR")
```

## Usage

### Check connection

```r
zt_is_running()   # TRUE if Zotero + Better BibTeX are available
```

### Insert citations

Open the Better BibTeX cite-as-you-write picker and return a formatted citation:

```r
# Pandoc format: [@doe2020]
zt_cite(format = "pandoc", .action = zt_insert)

# LaTeX format: \cite{doe2020}
zt_cite(format = "latex", .action = zt_insert)
```

### Fetch bibliography data

```r
# For specific citation keys
zt_bib(c("doe2020", "smith2019"), format = "json")

# Interactively via CAYW picker
zt_bib_cayw(format = "biblatex")

# For currently selected items in Zotero
zt_bib_selected(format = "json")
```

**Format note:** `"json"` (CSL-JSON) is recommended for R Markdown and Quarto documents. Other formats undergo lossy conversion when pandoc processes the bibliography.

### Sync bibliography files

The primary use case is keeping a bibliography file up to date as you write. Add this to your document's YAML front matter:

```yaml
bibliography: "`r zoteR::zt_write_bib('refs.json', overwrite = TRUE)`"
```

Every time the document knits, `zt_write_bib()` detects all `@key` citations in the file and fetches the latest data from Zotero.

To update the bibliography file without knitting:

```r
zt_update_bib("paper.Rmd")   # reads bibliography path from YAML front matter
```

### Detect citations

```r
# Scan a file for pandoc-style citation keys
zt_detect_citations("paper.Rmd")

# Scan a string
zt_detect_citations_text("See [@doe2020] and @smith2019.")
```

Code chunks, inline R expressions, and URLs are excluded from detection to avoid false positives. To force a key to be included (e.g. cited only in a figure caption), add it to a `nocite` field in your YAML front matter or in an HTML comment.

### Library management

```r
zt_libraries()              # data frame of all available libraries

# Look up library ID by name (more portable than hardcoding IDs)
zt_bib(keys, library_id = zt_library_id("Group Library Name"))
```

### Output actions

All retrieval functions accept a `.action` argument that controls what happens to the result:

| Action | Behaviour |
|---|---|
| `zt_return` | return invisibly (default; assign to a variable) |
| `zt_print` | print to console |
| `zt_insert` | insert at cursor in RStudio |
| `zt_copy` | copy to clipboard |

## RStudio addins

Three addins are included (accessible via **Addins** menu or keyboard shortcuts):

| Addin | Function |
|---|---|
| Insert Zotero Citation | Opens CAYW picker; inserts citation at cursor |
| Insert Zotero Bibliography (Selected Items) | Inserts bibliography for items selected in Zotero |
| Update Bibliography for Current Document | Syncs bibliography file for the active `.Rmd` / `.qmd` |

Citation format (Pandoc vs. LaTeX) is detected automatically from the active file's extension.

## Package options

| Option | Default | Description |
|---|---|---|
| `zoter.default.format` | `"biblatex"` | Default bibliography format |
| `zoter.default.bib` | `"biblatex"` | Format for `.bib` files (`"biblatex"` or `"bibtex"`) |
| `zoter.default.library_id` | `1L` | Default Zotero library ID |

```r
options(zoter.default.format = "json")
```

## License

GPL (>= 3)
