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