1pandoc-citeproc(1)                                          pandoc-citeproc(1)
2
3
4

NAME

6       pandoc-citeproc - filter to resolve citations in a pandoc document.
7

SYNOPSIS

9       pandoc-citeproc options [file..]
10

DESCRIPTION

12       The  pandoc-citeproc  executable has two modes, filter mode and convert
13       mode.
14
15   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
27       To process citations with pandoc, call pandoc-citeproc as a filter:
28
29              pandoc --filter pandoc-citeproc input.md -s -o output.html
30
31       pandoc-citeproc  will look for the following metadata fields in the in‐
32       put:
33
34       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
38              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
53              Note that .bib can generally be used with both BibTeX and BibLa‐
54              TeX files, but you can use .bibtex to force BibTeX.
55
56       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
60                     - 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
72              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
77       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
86       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
91       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
100              Here is a short example:
101
102                     { "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
111       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
118       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
124       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
130       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
138       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
143   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
151       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
155       This mode supersedes the old biblio2yaml program.
156
157   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
161              {{jats}}<ref>{{/jats}}
162
163       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
166       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

OPTIONS

171       -y, --bib2yaml
172              Convert bibliography to YAML suitable for  inclusion  in  pandoc
173              metadata.
174
175       -j, --bib2json
176              Convert  bibliography  to  CSL  JSON  suitable  for  import into
177              Zotero.
178
179       -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
184       -h, --help
185              Print usage information.
186
187       --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
191       --license
192              Print the license.
193
194       -q, --quiet
195              Silence all warnings.
196
197       -V, --version
198              Print version.
199

NOTES

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
205       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
214   Titles: Title vs. Sentence Case
215       If you are using a bibtex or biblatex bibliography,  then  observe  the
216       following rules:
217
218       · 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
224       · 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
228                title = {My Dinner with {Andre}}
229
230       · In addition, words that should remain lowercase (or camelCase) should
231         be protected:
232
233                title = {Spin Wave Dispersion on the {nm} Scale}
234
235         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
240       If you are using a CSL bibliography (either JSON or YAML), then observe
241       the following rules:
242
243       · All titles should be in sentence case.
244
245       · 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
249       · Protect words that should not be converted to title case  using  this
250         syntax:
251
252                Spin wave dispersion on the <span class="nocase">nm</span> scale
253
254   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
258       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
262       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

AUTHORS

272       Andrea Rossato and John MacFarlane.
273

SEE ALSO

275       pandoc (1), pandoc_markdown (5).
276
277       The pandoc-citeproc source code and all documentation may be downloaded
278       from <http://github.com/jgm/pandoc-citeproc/>.
279
280
281
282pandoc-citeproc 0.15.0.1          2018-11-27                pandoc-citeproc(1)
Impressum