format-citationsFormat citations across academic styles (APA 7, Chicago, Vancouver, IEEE) using CSL processors and R tooling. Convert between citation styles, generate in-text citations and reference lists, and validate formatting against style guides using citeproc, knitcitations, and Quarto's built-in citation engine. Use when rendering a Quarto or R Markdown document wi…
Independent GitHub snapshot · Automated classification · Original documentation governs
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.
apa, chicago-author-date, ieee)html, pdf, docx; default: inferred from document)en-US)# 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.
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.
# 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:
<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".<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-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>.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.
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).
# 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.
# 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.
# 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.
@key references in the document resolve to .bib entriesdiv#refs)link-citations: true)csl: explicitly for style consistency@Smtih2020 silently renders as
literal text. Enable Pandoc warnings with --verbose to catch theselang: in the YAML header to matchnocite: '@*' (all) or nocite: '@key1, @key2' to YAMLcite-method: citeproc by
default; R Markdown may need explicit pandoc_args: ["--citeproc"].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 causemanage-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