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
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 consumesvalidate-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