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