format-citations

# 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 ```r # 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: ```yaml --- title: "My Document" bibliography: references.bib csl: apa.csl link-citations: true output: html_document: pandoc_args: ["--citeproc"] --- ``` For Quarto: ```yaml --- 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 ```r # 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: ```markdown <!-- 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 ```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 ```r # 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: ```bash 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 ```r # 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