1pandoc-citeproc(1) pandoc-citeproc(1)
2
6 pandoc-citeproc - filter to resolve citations in a pandoc document.
7
9 pandoc-citeproc options [file..]
10
12 The pandoc-citeproc executable has two modes, filter mode and convert
13 mode.
14 Filter mode
16 Run without options, it acts as a filter that takes a JSON-encoded Pan‐
17 doc document, formats citations and adds a bibliography, and returns a
18 JSON-encoded pandoc document. Citations will be resolved, and, assum‐
19 ing there are bibliography entries, a bibliography will be inserted in‐
20 to a Div element with id refs. If no such Div exists, one will be cre‐
21 ated and appended to the end of the document (unless the suppress-bib‐
22 liography metadata field is set to a true value). If you wish the bib‐
23 liography to have a section header, put the section header at the end
24 of your document. (See the pandoc_markdown (5) man page under “Cita‐
25 tions” for details on how to encode citations in pandoc’s markdown.)
26 To process citations with pandoc, call pandoc-citeproc as a filter:
28 pandoc --filter pandoc-citeproc input.md -s -o output.html
30 pandoc-citeproc will look for the following metadata fields in the in‐
32 put:
33 bibliography
35 A path, or YAML list of paths, of bibliography files to use.
36 These may be in any of the formats supported by bibutils.
37 Format File extension
39 ─────────────────────────────
40 BibLaTeX .bib
41 BibTeX .bibtex
42 Copac .copac
43 CSL JSON .json
44 CSL YAML .yaml
45 EndNote .enl
46 EndNote XML .xml
47 ISI .wos
48 MEDLINE .medline
49 MODS .mods
50 NBIB .nbib
51 RIS .ris
52 Note that .bib can generally be used with both BibTeX and BibLa‐
54 TeX files, but you can use .bibtex to force BibTeX.
55 references
57 A YAML list of references. Each reference is a YAML object.
58 The format is essentially CSL JSON format. Here is an example:
59 - id: doe2006
61 author:
62 family: Doe
63 given: [John, F.]
64 title: Article
65 page: 33-34
66 issued:
67 year: 2006
68 type: article-journal
69 volume: 6
70 container-title: Journal of Generic Studies
71 The contents of fields will be interpreted as markdown when ap‐
73 propriate: so, for example, emphasis and strong emphasis can be
74 used in title fields. Simple tex math will also be parsed and
75 rendered appropriately.
76 csl or citation-style
78 Path or URL of a CSL style file. If the file is not found rela‐
79 tive to the working directory, pandoc-citeproc will look in the
80 $HOME/.csl directory (or C:\Users\USERNAME\AppData\Roaming\csl
81 in Windows 7). If this is left off, pandoc-citeproc will look
82 for $HOME/.pandoc/default.csl, and if this is not present, it
83 will use chicago-author-date.csl, looking first in $HOME/.csl
84 and then in its own data files.
85 link-citations
87 If this has a true value, citations in author-date and numerical
88 styles will be hyperlinked to their corresponding bibliography
89 entries. The default is not to add hyperlinks.
90 citation-abbreviations
92 Path to a CSL abbreviations JSON file. If the file is not found
93 relative to the working directory, pandoc-citeproc will look in
94 the $HOME/.csl directory (or C:\Users\USERNAME\AppData\Roam‐
95 ing\csl in Windows 7). The format is described here (http://ci‐
96 tationstylist.org/2011/10/19/abbreviations-for-zotero-test-re‐
97 lease). Abbreviations are only output if, in the .csl file,
98 form="short" is set on the element that renders the variable.
99 Here is a short example:
101 { "default": {
103 "container-title": {
104 "Lloyd's Law Reports": "Lloyd's Rep",
105 "Estates Gazette": "EG",
106 "Scots Law Times": "SLT"
107 }
108 }
109 }
110 lang Locale to use in formatting citations. If this is not set, the
112 locale is taken from the default-locale attribute of the CSL
113 file. en-US is used if a locale is not specified in either the
114 metadata or the CSL file. (For backwards compatibility, the
115 field locale can be used instead of lang, but this lang should
116 be used going forward.)
117 suppress-bibliography
119 If this has a true value, the bibliography will be left off.
120 Otherwise a bibliography will be inserted into each Div element
121 with id refs. If there is no such Div, one will be created at
122 the end of the document.
123 reference-section-title
125 If this has a value, a section header with this title will be
126 added before the bibliography. If reference-section-title is
127 not specified and the document ends with a section header, this
128 final header will be treated as the bibliography header.
129 notes-after-punctuation
131 If true (the default), pandoc will put footnote citations after
132 following punctuation. For example, if the source contains blah
133 blah [@jones99]., the result will look like blah blah.[^1], with
134 the note moved after the period and the space collapsed. If
135 false, the space will still be collapsed, but the footnote will
136 not be moved after the punctuation.
137 The metadata must contain either references or bibliography or both as
139 a source of references. csl and citation-abbreviations are optional.
140 If csl is not provided, a default stylesheet will be used (either
141 ~/.pandoc/default.csl or a version of chicago-author-date.csl).
142 Convert mode
144 If the option --bib2yaml or --bib2json is used, pandoc-citeproc will
145 not process citations; instead, it will treat its input (from stdin or
146 files) as a bibliography and convert it either to a pandoc YAML metada‐
147 ta section, suitable for inclusion in a pandoc document (--bib2yaml),
148 or as a CSL JSON bibliography, suitable for import to zotero
149 (--bib2json).
150 The --format option can be used to specify the bibliography format,
152 though when files are used, pandoc-citeproc can generally guess this
153 from the extension.
154 This mode supersedes the old biblio2yaml program.
156 Raw content (pandoc-citeproc only)
158 To include raw content in a prefix, suffix, delimiter, or term, sur‐
159 round it with these tags indicating the format:
160 {{jats}}<ref>{{/jats}}
162 Without the tags, the string will be interpreted as a string and es‐
164 caped in the output, rather than being passed through raw.
165 This feature allows stylesheets to be customized to give different out‐
167 put for different output formats. However, stylesheets customized in
168 this way will not be useable by other CSL implementations.
169
171 -y, --bib2yaml
172 Convert bibliography to YAML suitable for inclusion in pandoc
173 metadata.
174 -j, --bib2json
176 Convert bibliography to CSL JSON suitable for import into
177 Zotero.
178 -f FORMAT, --format=FORMAT
180 Specify format of bibliography to be converted. Legal values
181 are biblatex, bibtex, ris, endnote, endnotexml, isi, medline,
182 copac, mods, nbib, and json.
183 -h, --help
185 Print usage information.
186 --man Print the man page in groff man format. To get a plain text
188 version, pandoc-citeproc --man | groff -mman -Tutf8. To pan‐
189 doc-citeproc --man | groff -mman -Thtml.
190 --license
192 Print the license.
193 -q, --quiet
195 Silence all warnings.
196 -V, --version
198 Print version.
199
201 General
202 If you use a biblatex database, closely follow the specifications in
203 the “Database Guide” section of the biblatex manual (currently 2.8a).
204 If you use a CSL-YAML or CSL-JSON database, or a CSL-YAML metadata sec‐
206 tion in your markdown document, follow the “Citation Style Language
207 1.0.1 Language Specification” (<http://citationstyles.org/down‐
208 loads/specification.html>). Particularly relevant are <http://cita‐
209 tionstyles.org/downloads/specification.html#appendix-iii-types> (which
210 neither comments on usage nor specifies required and optional fields)
211 and <http://citationstyles.org/downloads/specification.html#appendix-
212 iv-variables> (which does contain comments).
213 Titles: Title vs. Sentence Case
215 If you are using a bibtex or biblatex bibliography, then observe the
216 following rules:
217 · English titles should be in title case. Non-English titles should be
219 in sentence case, and the langid field in biblatex should be set to
220 the relevant language. (The following values are treated as English:
221 american, british, canadian, english, australian, newzealand, USen‐
222 glish, or UKenglish.)
223 · As is standard with bibtex/biblatex, proper names should be protected
225 with curly braces so that they won’t be lowercased in styles that
226 call for sentence case. For example:
227 title = {My Dinner with {Andre}}
229 · In addition, words that should remain lowercase (or camelCase) should
231 be protected:
232 title = {Spin Wave Dispersion on the {nm} Scale}
234 Though this is not necessary in bibtex/biblatex, it is necessary with
236 citeproc, which stores titles internally in sentence case, and con‐
237 verts to title case in styles that require it. Here we protect “nm”
238 so that it doesn’t get converted to “Nm” at this stage.
239 If you are using a CSL bibliography (either JSON or YAML), then observe
241 the following rules:
242 · All titles should be in sentence case.
244 · Use the language field for non-English titles to prevent their con‐
246 version to title case in styles that call for this. (Conversion hap‐
247 pens only if language begins with en or is left empty.)
248 · Protect words that should not be converted to title case using this
250 syntax:
251 Spin wave dispersion on the <span class="nocase">nm</span> scale
253 Conference Papers, Published vs. Unpublished
255 For a formally published conference paper, use the biblatex entry type
256 inproceedings (which will be mapped to CSL paper-conference).
257 For an unpublished manuscript, use the biblatex entry type unpublished
259 without an eventtitle field (this entry type will be mapped to CSL man‐
260 uscript).
261 For a talk, an unpublished conference paper, or a poster presentation,
263 use the biblatex entry type unpublished with an eventtitle field (this
264 entry type will be mapped to CSL speech). Use the biblatex type field
265 to indicate the type, e.g. “Paper”, or “Poster”. venue and eventdate
266 may be useful too, though eventdate will not be rendered by most CSL
267 styles. Note that venue is for the event’s venue, unlike location
268 which describes the publisher’s location; do not use the latter for an
269 unpublished conference paper.
270
272 Andrea Rossato and John MacFarlane.
273
275 pandoc (1), pandoc_markdown (5).
276 The pandoc-citeproc source code and all documentation may be downloaded
278 from <http://github.com/jgm/pandoc-citeproc/>.
279pandoc-citeproc 0.15.0.1 2018-11-27 pandoc-citeproc(1)