pandoc-citeproc(1)

📦 version 0.17.0.1, in ubuntu jammy

pandoc-citeproc(1) 💅

okay so bestie, welcome to the pandoc-citeproc manual page. it's a filter. it resolves citations. it's iconic. let's get into it 🫶

✨ NAME ✨

pandoc-citeproc — a filter that resolves citations in a pandoc document. that's the whole job. that's the vibe. 💖

✨ SYNOPSIS ✨

pandoc-citeproc options [file..]

✨ DESCRIPTION ✨

so the pandoc-citeproc executable has two modes, bestie: filter mode and convert mode. two modes, two moods, both slay.

🌸 Filter mode 🌸

Run it with no options and it acts as a filter. here's the tea: it takes a JSON-encoded Pandoc document, formats the citations, adds a bibliography, and hands you back a JSON-encoded pandoc document. literally that simple.

Citations get resolved, and — assuming there are bibliography entries — a bibliography gets inserted into a Div element with id refs. if no such Div exists, one will be created and appended to the end of the document (unless the suppress-bibliography metadata field is set to a true value, in which case, no Div for you 🙈). if the CSL style specifies hanging indent, the class hanging-indent will be added to this Div. cute.

if you want your bibliography to have a section header, put the section header at the end of your document (or at the beginning of the Div with id refs, if there is one). (peep the pandoc(1) man page under "Citations" for the deets on how to encode citations in pandoc's markdown.)

to process citations with pandoc, call pandoc-citeproc as a filter, like:

pandoc --filter pandoc-citeproc input.md -s -o output.html

pandoc-citeproc will look for the following metadata fields in the input. (for details on how to set metadata fields in pandoc's markdown, see the pandoc(1) man page under --metadata, --metadata-file, and Extension: yaml_metadata_block.)

bibliography — a path, or YAML list of paths, of bibliography files to use. these may be in any of the formats supported by bibutils:
- BibLaTeX — .bib
- BibTeX — .bibtex
- Copac — .copac
- CSL JSON — .json
- CSL YAML — .yaml
- EndNote — .enl
- EndNote XML — .xml
- ISI — .wos
- MEDLINE — .medline
- MODS — .mods
- NBIB — .nbib
- RIS — .ris

ngl, .bib can generally be used with both BibTeX and BibLaTeX files, but you can use .bibtex to force BibTeX. iykyk 💅

references — a YAML list of references. each reference is a YAML object. the format is essentially CSL JSON format. here's an example, bestie:

- id: doe2006
  author:
    family: Doe
    given: [John, F.]
  title: Article
  page: 33-34
  issued:
    year: 2006
  type: article-journal
  volume: 6
  container-title: Journal of Generic Studies

the contents of fields will be interpreted as markdown when appropriate: so, for example, emphasis and strong emphasis can be used in title fields. simple tex math will also be parsed and rendered appropriately. obsessed. ✨

csl or citation-style — path or URL of a CSL style file. if the file is not found relative to the working directory, pandoc-citeproc will look in the $HOME/.csl directory (or C:\Users\USERNAME\AppData\Roaming\csl in Windows 7). if this is left off, pandoc-citeproc will look for $HOME/.pandoc/default.csl, and if this is not present, it will use chicago-author-date.csl, looking first in $HOME/.csl and then in its own data files.
link-citations — if this has a true value, citations in author-date and numerical styles will be hyperlinked to their corresponding bibliography entries. the default is not to add hyperlinks. (so if you want them, say so.)
citation-abbreviations — path to a CSL abbreviations JSON file. if the file is not found relative to the working directory, pandoc-citeproc will look in the $HOME/.csl directory (or C:\Users\USERNAME\AppData\Roaming\csl in Windows 7). the format is described here: http://citationstylist.org/2011/10/19/abbreviations-for-zotero-test-release. abbreviations are only output if, in the .csl file, form="short" is set on the element that renders the variable. here's a short example:

{ "default": {
    "container-title": {
            "Lloyd's Law Reports": "Lloyd's Rep",
            "Estates Gazette": "EG",
            "Scots Law Times": "SLT"
    }
  }
}

lang — locale to use in formatting citations. if this is not set, the locale is taken from the default-locale attribute of the CSL file. en-US is used if a locale is not specified in either the metadata or the CSL file. (for backwards compatibility, the field locale can be used instead of lang, but this lang should be used going forward. bestie, use the new one, trust me.)
suppress-bibliography — if this has a true value, the bibliography will be left off. otherwise a bibliography will be inserted into each Div element with id refs. if there is no such Div, one will be created at the end of the document.
reference-section-title — if this has a value, a section header with this title will be added before the bibliography. if reference-section-title is not specified and the document ends with a section header, this final header will be treated as the bibliography header. note: reference-section-title has no effect when the bibliography is placed explicitly using a Div with id refs. 💀
notes-after-punctuation — if true (the default), pandoc will put footnote citations after following punctuation. for example, if the source contains blah blah [@jones99]., the result will look like blah blah.[^1], with the note moved after the period and the space collapsed. if false, the space will still be collapsed, but the footnote will not be moved after the punctuation.

the metadata must contain either references or bibliography or both as a source of references. csl and citation-abbreviations are optional. if csl is not provided, a default stylesheet will be used (either ~/.pandoc/default.csl or a version of chicago-author-date.csl).

🌈 Convert mode 🌈

if the option --bib2yaml or --bib2json is used, pandoc-citeproc will not process citations; instead, it will treat its input (from stdin or files) as a bibliography and convert it either to a pandoc YAML metadata section, suitable for inclusion in a pandoc document (--bib2yaml), or as a CSL JSON bibliography, suitable for import to zotero (--bib2json).

the --format option can be used to specify the bibliography format, though when files are used, pandoc-citeproc can generally guess this from the extension.

this mode supersedes the old biblio2yaml program. it's the glow-up, honestly. 👑

🦋 Raw content (pandoc-citeproc only) 🦋

to include raw content in a prefix, suffix, delimiter, or term, surround it with these tags indicating the format:

{{jats}}<ref>{{/jats}}

without the tags, the string will be interpreted as a string and escaped in the output, rather than being passed through raw.

this feature allows stylesheets to be customized to give different output for different output formats. however, stylesheets customized in this way will not be useable by other CSL implementations. so like, keep that in mind bestie.

✨ OPTIONS ✨

-y, --bib2yaml — convert bibliography to YAML suitable for inclusion in pandoc metadata.
-j, --bib2json — convert bibliography to CSL JSON suitable for import into Zotero.
-f FORMAT, --format=FORMAT — specify format of bibliography to be converted. legal values are biblatex, bibtex, ris, endnote, endnotexml, isi, medline, copac, mods, nbib, and json.
-c NUMBER, --columns=NUMBER — specify column to which to wrap YAML output produced using --bib2yaml. default is 80. to disable wrapping, set 0.
-h, --help — print usage information.
--man — print the man page in groff man format. to get a plain text version, pandoc-citeproc --man | groff -mman -Tutf8. to get an HTML version, pandoc-citeproc --man | groff -mman -Thtml.
--license — print the license.
-q, --quiet — silence all warnings.
-V, --version — print version.

and that's part one, bestie — stay tuned, there's more coming 👀

💖 NOTES 💖

🌸 General 🌸

okay so real talk bestie — if you're rolling with a biblatex database, you gotta closely follow the specs in the “Database Guide” section of the biblatex manual (currently 2.8a). No vibes-based guessing here, the manual is the manual. 💅

If instead you're using a CSL-YAML or CSL-JSON database, or a CSL-YAML metadata section inside your markdown document, then you follow the “Citation Style Language 1.0.1 Language Specification” (http://citationstyles.org/downloads/specification.html). A couple of spots in there are extra relevant:

http://citationstyles.org/downloads/specification.html#appendix-iii-types — and heads up, this one neither comments on usage nor specifies required and optional fields 😭 it's giving bare minimum.
http://citationstyles.org/downloads/specification.html#appendix-iv-variables — this one does contain comments, so it's the one that actually feeds you. 🍓

🎀 Titles: Title vs. Sentence Case 🎀

this is the section that ruins friendships, so lock in 🔥

If you're using a bibtex or biblatex bibliography, then observe the following rules:

English titles should be in title case. Non-English titles should be in sentence case, and the langid field in biblatex should be set to the relevant language. (The following values are treated as English: american, british, canadian, english, australian, newzealand, USenglish, or UKenglish.)
As is standard with bibtex/biblatex, proper names should be protected with curly braces so that they won’t be lowercased in styles that call for sentence case. For example:

title = {My Dinner with {Andre}}

In addition, words that should remain lowercase (or camelCase) should be protected:

title = {Spin Wave Dispersion on the {nm} Scale}

Though this is not necessary in bibtex/biblatex, it is necessary with citeproc, which stores titles internally in sentence case, and converts to title case in styles that require it. Here we protect “nm” so that it doesn’t get converted to “Nm” at this stage. sneaky little stage, that stage. 👑

If you're using a CSL bibliography (either JSON or YAML), then observe the following rules:

All titles should be in sentence case.
Use the language field for non-English titles to prevent their conversion to title case in styles that call for this. (Conversion happens only if language begins with en or is left empty.)
Protect words that should not be converted to title case using this syntax:

Spin wave dispersion on the <span class="nocase">nm</span> scale

bestie warning: mixing up your title-case strategy between bibtex/biblatex and CSL is how you end up with chaos titles. Pick your lane. 🫶

🦋 Conference Papers, Published vs. Unpublished 🦋

For a formally published conference paper, use the biblatex entry type inproceedings (which will be mapped to CSL paper-conference). ✨
For an unpublished manuscript, use the biblatex entry type unpublished without an eventtitle field (this entry type will be mapped to CSL manuscript).
For a talk, an unpublished conference paper, or a poster presentation, use the biblatex entry type unpublished with an eventtitle field (this entry type will be mapped to CSL speech). Use the biblatex type field to indicate the type, e.g. “Paper”, or “Poster”. venue and eventdate may be useful too, though eventdate will not be rendered by most CSL styles.

do not play yourself here: note that venue is for the event’s venue, unlike location which describes the publisher’s location; do not use the latter for an unpublished conference paper. 💀

👑 AUTHORS 👑

Andrea Rossato and John MacFarlane. absolute icons, fr fr. 💖

⭐ SEE ALSO ⭐

pandoc (1).

The pandoc-citeproc source code and all documentation may be downloaded from http://github.com/jgm/pandoc-citeproc/. 🌈

and that's the whole page bestie, you ate that 🎀✨ this was pandoc-citeproc version 0.16.3.1, dated 2019-11-19 — so yes, it's a lil vintage, but the knowledge still slays. go cite something pretty 💅🦋👑

📦 where this page comes from

ubuntu jammy: pandoc-citeproc 0.17.0.1-1build5 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms