Citations
Extension: citations
Using an external filter, pandoc-citeproc
, pandoc can automatically generate citations and a bibliography in a number of styles. Basic usage is
pandoc --filter pandoc-citeproc myinput.txt
In order to use this feature, you will need to specify a bibliography file using the bibliography
metadata field in a YAML metadata section, or --bibliography
command line argument. You can supply multiple --bibliography
arguments or set bibliography
metadata field to YAML array, if you want to use multiple bibliography files. The bibliography may have any of these formats:
BibLaTeX |
.bib |
BibTeX |
.bibtex |
Copac |
.copac |
CSL JSON |
.json |
CSL YAML |
.yaml |
EndNote |
.enl |
EndNote XML |
.xml |
ISI |
.wos |
MEDLINE |
.medline |
MODS |
.mods |
RIS |
.ris |
Note that .bib
can be used with both BibTeX and BibLaTeX files; use .bibtex
to force BibTeX.
Note that pandoc-citeproc --bib2json
and pandoc-citeproc --bib2yaml
can produce .json
and .yaml
files from any of the supported formats.
In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc parses a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown; and in CSL JSON databases, an HTML-like markup:
<i>...</i>
- italics
<b>...</b>
- bold
<span style="font-variant:small-caps;">...</span>
or <sc>...</sc>
- small capitals
<sub>...</sub>
- subscript
<sup>...</sup>
- superscript
<span class="nocase">...</span>
- prevent a phrase from being capitalized as title case
pandoc-citeproc -j
and -y
interconvert the CSL JSON and CSL YAML formats as far as possible.
As an alternative to specifying a bibliography file using --bibliography
or the YAML metadata field bibliography
, you can include the citation data directly in the references
field of the document’s YAML metadata. The field should contain an array of YAML-encoded references, for example:
---
references:
- type: article-journal
id: WatsonCrick1953
author:
- family: Watson
given: J. D.
- family: Crick
given: F. H. C.
issued:
date-parts:
- - 1953
- 4
- 25
title: 'Molecular structure of nucleic acids: a structure for deoxyribose
nucleic acid'
title-short: Molecular structure of nucleic acids
container-title: Nature
volume: 171
issue: 4356
page: 737-738
DOI: 10.1038/171737a0
URL: http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
language: en-GB
...
(pandoc-citeproc --bib2yaml
can produce these from a bibliography file in one of the supported formats.)
Citations and references can be formatted using any style supported by the Citation Style Language, listed in the Zotero Style Repository. These files are specified using the --csl
option or the csl
metadata field. By default, pandoc-citeproc
will use the Chicago Manual of Style author-date format. The CSL project provides further information on finding and editing styles.
To make your citations hyperlinks to the corresponding bibliography entries, add link-citations: true
to your YAML metadata.
Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of ‘@’ + the citation identifier from the database, and may optionally have a prefix, a locator, and a suffix. The citation key must begin with a letter, digit, or _
, and may contain alphanumerics, _
, and internal punctuation characters (:.#$%&-+?<>~/
). Here are some examples:
Blah blah [see @doe99, pp. 33-35; also @smith04, chap. 1].
Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
Blah blah [@smith04; @doe99].
pandoc-citeproc
detects locator terms in the CSL locale files. Either abbreviated or unabbreviated forms are accepted. In the en-US
locale, locator terms can be written in either singular or plural forms, as book
, bk.
/bks.
; chapter
, chap.
/chaps.
; column
, col.
/cols.
; figure
, fig.
/figs.
; folio
, fol.
/fols.
; number
, no.
/nos.
; line
, l.
/ll.
; note
, n.
/nn.
; opus
, op.
/opp.
; page
, p.
/pp.
; paragraph
, para.
/paras.
; part
, pt.
/pts.
; section
, sec.
/secs.
; sub verbo
, s.v.
/s.vv.
; verse
, v.
/vv.
; volume
, vol.
/vols.
; ¶
/¶¶
; §
/§§
. If no locator term is used, “page” is assumed.
pandoc-citeproc
will use heuristics to distinguish the locator from the suffix. In complex cases, the locator can be enclosed in curly braces (using pandoc-citeproc
0.15 and higher only):
[@smith{ii, A, D-Z}, with a suffix]
[@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
A minus sign (-
) before the @
will suppress mention of the author in the citation. This can be useful when the author is already mentioned in the text:
Smith says blah [-@smith04].
You can also write an in-text citation, as follows:
@smith04 says blah.
@smith04 [p. 33] says blah.
If the style calls for a list of works cited, it will be placed in a div with id refs
, if one exists:
::: {#refs}
:::
Otherwise, it will be placed at the end of the document. Generation of the bibliography can be suppressed by setting suppress-bibliography: true
in the YAML metadata.
If you wish the bibliography to have a section heading, you can set reference-section-title
in the metadata, or put the heading at the beginning of the div with id refs
(if you are using it) or at the end of your document:
last paragraph...
# References
The bibliography will be inserted after this heading. Note that the unnumbered
class will be added to this heading, so that the section will not be numbered.
If you want to include items in the bibliography without actually citing them in the body text, you can define a dummy nocite
metadata field and put the citations there:
---
nocite: |
@item1, @item2
...
@item3
In this example, the document will contain a citation for item3
only, but the bibliography will contain entries for item1
, item2
, and item3
.
It is possible to create a bibliography with all the citations, whether or not they appear in the document, by using a wildcard:
---
nocite: |
@*
...
For LaTeX output, you can also use natbib
or biblatex
to render the bibliography. In order to do so, specify bibliography files as outlined above, and add --natbib
or --biblatex
argument to pandoc
invocation. Bear in mind that bibliography files have to be in respective format (either BibTeX or BibLaTeX).
For more information, see the pandoc-citeproc man page.