format-citations

Format citations across academic styles using CSL (Citation Style Language) processors and R tooling. This skill covers converting BibTeX entries into properly formatted in-text citations and reference lists for APA 7, Chicago, Vancouver, IEEE, and custom styles. It leverages Pandoc's citeproc, the knitcitations package, and Quarto's native citation engine for reproducible document production.

When to Use

• Rendering an R Markdown or Quarto document with formatted citations
• Converting a bibliography from one citation style to another
• Generating a standalone reference list from a .bib file
• Validating that in-text citations match a specific style guide
• Setting up citation infrastructure for a multi-document project (book, thesis)

Inputs

• Required: A .bib file (or other bibliography source recognized by Pandoc)
• Required: Target citation style (e.g., apa, chicago-author-date, ieee)
• Optional: CSL file path (default: uses Pandoc built-in styles)
• Optional: Output format (html, pdf, docx; default: inferred from document)
• Optional: Locale for language-specific formatting (default: en-US)

Procedure

Step 1: Verify Citation Infrastructure

# Check Pandoc availability (required for citeproc)
pandoc_path <- Sys.which("pandoc")
if (!nzchar(pandoc_path)) {
  pandoc_path <- Sys.getenv("RSTUDIO_PANDOC")
}
stopifnot("Pandoc not found" = nzchar(pandoc_path))
message(sprintf("Pandoc: %s", system2(pandoc_path, "--version", stdout = TRUE)[1]))

# Check for citeproc support
citeproc_ok <- any(grepl("citeproc", system2(pandoc_path, "--list-extensions", stdout = TRUE)))
message(sprintf("Citeproc: %s", ifelse(citeproc_ok, "built-in", "external needed")))

Expected: Pandoc version 2.11+ detected with built-in citeproc support.

On failure: Install Pandoc or set RSTUDIO_PANDOC in .Renviron to point to the RStudio-bundled Pandoc. Quarto also ships its own Pandoc.

Step 2: Configure Document YAML for Citations

For R Markdown:

---
title: "My Document"
bibliography: references.bib
csl: apa.csl
link-citations: true
output:
  html_document:
    pandoc_args: ["--citeproc"]
---

For Quarto:

---
title: "My Document"
bibliography: references.bib
csl: apa.csl
link-citations: true
cite-method: citeproc
---

Expected: YAML header correctly references the .bib file and CSL style.

On failure: If the CSL file is not found, download it from the CSL repository (see Step 3) and place it in the project directory.

Step 3: Obtain and Customize CSL Style Files

# Common CSL styles and their repository names
csl_styles <- list(
  apa         = "apa.csl",
  chicago     = "chicago-author-date.csl",
  vancouver   = "vancouver.csl",
  ieee        = "ieee.csl",
  nature      = "nature.csl",
  harvard     = "harvard-cite-them-right.csl",
  mla         = "modern-language-association.csl"
)

download_csl <- function(style, dest_dir = ".") {
  base_url <- "https://raw.githubusercontent.com/citation-style-language/styles/master"
  filename <- csl_styles[[style]]
  if (is.null(filename)) stop(sprintf("Unknown style: %s", style))
  dest <- file.path(dest_dir, filename)
  utils::download.file(
    url = sprintf("%s/%s", base_url, filename),
    destfile = dest, quiet = TRUE
  )
  message(sprintf("Downloaded %s to %s", filename, dest))
  dest
}

# Download APA 7 style
download_csl("apa")

A downloaded style is rarely the last word — journals routinely deviate from the canonical style in small ways, and the fix is to edit the .csl file rather than to post-process the rendered output.

A CSL style is XML rooted in a <style> element that declares the CSL namespace as its default (xmlns="http://purl.org/net/xbiblio/csl"). Elements inside the file are therefore written unprefixed — <citation>, <bibliography>, <sort>. The CSL specification names the same elements as cs:style, cs:citation and so on; that prefix is the spec's notation for talking about them, not text you will find in apa.csl. Searching a downloaded style for <cs:citation> returns nothing.

Four parts account for nearly every journal-specific tweak:

• Where the two formats live. <citation> is required and appears exactly once; it controls the in-text citation or footnote. <bibliography> is optional and controls the reference list. Changing how a citation looks in the text and changing how it looks in the reference list are edits to different elements — this is the most common source of "I changed it and nothing happened".
• Sort order. Both <citation> and <bibliography> may carry a <sort> child, which must appear before <layout> and must contain one or more <key> elements. This is what switches a bibliography between author-alphabetical, by-year, and citation-order.
• "et al." thresholds. et-al-min and et-al-use-first together enable et-al abbreviation: once the author count reaches et-al-min, the list truncates after et-al-use-first names. Set them on <name>, or inherit them from <style>, <citation>, or <bibliography>.
• Localization. Set the default-locale attribute on the root <style> element to translate style-generated terms ("and", "et al.", "eds."). The attribute is default-locale — a bare locale attribute belongs on <locale> elements and will not do this.

Validate any edited style at https://validator.citationstyles.org/, which checks a file (by URL, upload, or paste) against the CSL schema and reports the offending line. Do this before rendering: Pandoc's failure mode for a malformed style is unhelpful.

Expected: CSL file downloaded to the project directory, and any journal-specific edits validate cleanly against the CSL schema.

On failure: Check network connectivity. The CSL GitHub repository contains 10,000+ styles. For offline use, bundle required CSL files in the project. If an edited style fails validation, the validator names the line — the usual causes are a <sort> placed after <layout> rather than before it, and a misspelled attribute, which the schema rejects rather than ignores.

Step 4: Write In-Text Citations

Use Pandoc citation syntax in your document body:

<!-- Single citation -->
According to @Smith2020, the method improves accuracy.

<!-- Parenthetical citation -->
The method improves accuracy [@Smith2020].

<!-- Multiple citations -->
Several studies confirm this [@Smith2020; @Jones2021; @Lee2022].

<!-- Citation with page number -->
As noted by @Smith2020 [p. 42], the results are significant.

<!-- Suppress author name -->
The results are significant [-@Smith2020].

<!-- Citation with prefix -->
[see @Smith2020, pp. 42-45; also @Jones2021, ch. 3]

Expected: Pandoc/Quarto renders these into properly formatted citations in the target style (e.g., (Smith, 2020) for APA, (Smith 2020) for Chicago).

Step 5: Generate Standalone Reference Lists with R

# Using RefManageR to print formatted references
library(RefManageR)
BibOptions(style = "text", bib.style = "authoryear", sorting = "nyt")
bib <- ReadBib("references.bib", check = FALSE)

# Print all entries in text format
print(bib)

# Format specific entries
print(bib[author = "Smith"])

# Generate markdown reference list programmatically
format_reference_list <- function(bib, style = "apa") {
  BibOptions(style = "text", bib.style = "authoryear")
  entries <- capture.output(print(bib))
  entries <- entries[nzchar(trimws(entries))]
  paste(sprintf("- %s", entries), collapse = "\n")
}

cat(format_reference_list(bib))

Expected: Formatted reference list printed to console or captured as character vector for further processing.

Step 6: Convert Between Citation Styles

# Render the same document in different styles
styles <- c("apa", "chicago", "ieee")

for (style in styles) {
  csl_file <- download_csl(style)
  output_file <- sprintf("output_%s.html", style)

  rmarkdown::render(
    input = "document.Rmd",
    output_file = output_file,
    params = list(csl = csl_file),
    quiet = TRUE
  )
  message(sprintf("Rendered %s with %s style", output_file, style))
}

For Quarto:

quarto render document.qmd --metadata csl:apa.csl -o output_apa.html
quarto render document.qmd --metadata csl:ieee.csl -o output_ieee.html

Expected: Multiple output files, each with the same content formatted in a different citation style.

On failure: If rendering fails, check that all citation keys in the document body exist in the .bib file. Missing keys produce warnings but may break formatting.

Step 7: Validate Citation Formatting

# Check for undefined citations in rendered output
validate_citations <- function(rmd_file, bib_file) {
  # Extract citation keys from document
  doc_text <- readLines(rmd_file, warn = FALSE)
  doc_keys <- unique(unlist(regmatches(
    doc_text,
    gregexpr("@([A-Za-z][A-Za-z0-9_:.#$%&+-?<>~/]*)", doc_text)
  )))
  doc_keys <- gsub("^@", "", doc_keys)
  # Remove false positives (email-like patterns)
  doc_keys <- doc_keys[!grepl("\\.", doc_keys)]

  # Extract keys from .bib file
  bib <- RefManageR::ReadBib(bib_file, check = FALSE)
  bib_keys <- names(bib)

  # Find mismatches
  undefined <- setdiff(doc_keys, bib_keys)
  unused <- setdiff(bib_keys, doc_keys)

  list(
    undefined = undefined,
    unused = unused,
    cited = intersect(doc_keys, bib_keys)
  )
}

result <- validate_citations("document.Rmd", "references.bib")
if (length(result$undefined) > 0) {
  warning(sprintf("Undefined citation keys: %s",
                  paste(result$undefined, collapse = ", ")))
}
if (length(result$unused) > 0) {
  message(sprintf("Unused .bib entries: %s",
                  paste(result$unused, collapse = ", ")))
}

Expected: Report of undefined keys (cited but not in .bib), unused entries (in .bib but never cited), and valid citations.

On failure: False positives may occur with email addresses or code containing @. Refine the regex or manually review flagged keys.

Validation

• [ ] Document renders without citation warnings from Pandoc/citeproc
• [ ] All @key references in the document resolve to .bib entries
• [ ] Reference list appears at the end of the document (or in div#refs)
• [ ] In-text citations match the target style format
• [ ] Citation sorting follows style rules (alphabetical for APA, numbered for IEEE)
• [ ] Hyperlinks from in-text citations to reference list entries work (if link-citations: true)

Common Pitfalls

• Missing CSL file: Pandoc falls back to Chicago author-date if no CSL is specified. Always set csl: explicitly for style consistency
• Citation key typos: A misspelled key like @Smtih2020 silently renders as literal text. Enable Pandoc warnings with --verbose to catch these
• Locale-dependent formatting: APA requires "and" between authors in English but "und" in German. Set lang: in the YAML header to match
• nocite for uncited entries: To include entries in the reference list without citing them in text, add nocite: '@*' (all) or nocite: '@key1, @key2' to YAML
• CSL version mismatch: Some older CSL 0.8 files are incompatible with modern Pandoc. Always use CSL 1.0+ from the official repository
• Quarto vs R Markdown differences: Quarto uses cite-method: citeproc by default; R Markdown may need explicit pandoc_args: ["--citeproc"]
• Confusing CSL styles with LaTeX bibliography styles: three separate formats answer to "APA style" and none is interchangeable with the others. .csl drives Pandoc, Quarto, and Zotero. Legacy BibTeX uses .bst files, selected with \bibliographystyle{} and processed by the bibtex program. Modern biblatex uses its own .bbx/.cbx styles, selected with \usepackage[style=apa]{biblatex} and processed by biber. Putting a .csl filename in a csl: field is right; putting one anywhere in a LaTeX preamble is not, and each of these tools fails on the others' files in ways that do not name the cause

Related Skills

• manage-bibliography - create and maintain the .bib files this skill consumes
• validate-references - verify .bib entry completeness before formatting
• ../reporting/format-apa-report - full APA report formatting beyond citations
• ../reporting/create-quarto-report - Quarto document setup with citation support