@@ -1,13 +1,13 @@
2−.\" Automatically generated by Pandoc 2.14.0.1
2+.\" Automatically generated by Pandoc 2.10.1
4−.TH "Pandoc User\[cq]s Guide" "" "June 20, 2021" "pandoc 2.14.0.3" ""
4+.TH "Pandoc User\[aq]s Guide" "" "July 23, 2020" "pandoc 2.10.1" ""
7pandoc - general markup converter
7pandoc - general markup converter
8.SH SYNOPSIS
8.SH SYNOPSIS
10−\f[C]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input-file\f[R]]\&...
10+\f[C]pandoc\f[R] [\f[I]options\f[R]] [\f[I]input-file\f[R]]...
11.SH DESCRIPTION
11.SH DESCRIPTION
13Pandoc is a Haskell library for converting from one markup format to
13Pandoc is a Haskell library for converting from one markup format to
@@ -20,10 +20,10 @@ For the full lists of input and output formats, see the \f[C]--from\f[R]
20and \f[C]--to\f[R] options below.
20and \f[C]--to\f[R] options below.
21Pandoc can also produce PDF output: see creating a PDF, below.
21Pandoc can also produce PDF output: see creating a PDF, below.
23−Pandoc\[cq]s enhanced version of Markdown includes syntax for tables,
23+Pandoc\[aq]s enhanced version of Markdown includes syntax for tables,
24definition lists, metadata blocks, footnotes, citations, math, and much
24definition lists, metadata blocks, footnotes, citations, math, and much
26−See below under Pandoc\[cq]s Markdown.
26+See below under Pandoc\[aq]s Markdown.
28Pandoc has a modular design: it consists of a set of readers, which
28Pandoc has a modular design: it consists of a set of readers, which
29parse text in a given format and produce a native representation of the
29parse text in a given format and produce a native representation of the
@@ -33,15 +33,15 @@ Thus, adding an input or output format requires only adding a reader or
34Users can also run custom pandoc filters to modify the intermediate AST.
34Users can also run custom pandoc filters to modify the intermediate AST.
36−Because pandoc\[cq]s intermediate representation of a document is less
36+Because pandoc\[aq]s intermediate representation of a document is less
37expressive than many of the formats it converts between, one should not
37expressive than many of the formats it converts between, one should not
38expect perfect conversions between every format and every other.
38expect perfect conversions between every format and every other.
39Pandoc attempts to preserve the structural elements of a document, but
39Pandoc attempts to preserve the structural elements of a document, but
40not formatting details such as margin size.
40not formatting details such as margin size.
41And some document elements, such as complex tables, may not fit into
41And some document elements, such as complex tables, may not fit into
42−pandoc\[cq]s simple document model.
42+pandoc\[aq]s simple document model.
43−While conversions from pandoc\[cq]s Markdown to all formats aspire to be
43+While conversions from pandoc\[aq]s Markdown to all formats aspire to be
44−perfect, conversions from formats more expressive than pandoc\[cq]s
44+perfect, conversions from formats more expressive than pandoc\[aq]s
45Markdown can be expected to be lossy.
45Markdown can be expected to be lossy.
46.SS Using pandoc
46.SS Using pandoc
@@ -57,9 +57,9 @@ pandoc -o output.html input.txt
59By default, pandoc produces a document fragment.
59By default, pandoc produces a document fragment.
60−To produce a standalone document (e.g.\ a valid HTML file including
60+To produce a standalone document (e.g.
61−\f[C]<head>\f[R] and \f[C]<body>\f[R]), use the \f[C]-s\f[R] or
61+a valid HTML file including \f[C]<head>\f[R] and \f[C]<body>\f[R]), use
62−\f[C]--standalone\f[R] flag:
62+the \f[C]-s\f[R] or \f[C]--standalone\f[R] flag:
@@ -115,10 +115,10 @@ pandoc -o hello.tex hello.txt
116will convert \f[C]hello.txt\f[R] from Markdown to LaTeX.
116will convert \f[C]hello.txt\f[R] from Markdown to LaTeX.
117If no output file is specified (so that output goes to
117If no output file is specified (so that output goes to
118−\f[I]stdout\f[R]), or if the output file\[cq]s extension is unknown, the
118+\f[I]stdout\f[R]), or if the output file\[aq]s extension is unknown, the
119output format will default to HTML.
119output format will default to HTML.
120If no input file is specified (so that input comes from
120If no input file is specified (so that input comes from
121−\f[I]stdin\f[R]), or if the input files\[cq] extensions are unknown, the
121+\f[I]stdin\f[R]), or if the input files\[aq] extensions are unknown, the
122input format will be assumed to be Markdown.
122input format will be assumed to be Markdown.
123.SS Character encoding
123.SS Character encoding
@@ -172,15 +172,15 @@ You can then test it with \f[C]pdflatex test.tex\f[R].
172When using LaTeX, the following packages need to be available (they are
172When using LaTeX, the following packages need to be available (they are
173included with all recent versions of TeX Live): \f[C]amsfonts\f[R],
173included with all recent versions of TeX Live): \f[C]amsfonts\f[R],
174\f[C]amsmath\f[R], \f[C]lm\f[R], \f[C]unicode-math\f[R],
174\f[C]amsmath\f[R], \f[C]lm\f[R], \f[C]unicode-math\f[R],
175−\f[C]iftex\f[R], \f[C]listings\f[R] (if the \f[C]--listings\f[R] option
175+\f[C]ifxetex\f[R], \f[C]ifluatex\f[R], \f[C]listings\f[R] (if the
176+\f[C]--listings\f[R] option is used), \f[C]fancyvrb\f[R],
176−is used), \f[C]fancyvrb\f[R], \f[C]longtable\f[R], \f[C]booktabs\f[R],
177+\f[C]longtable\f[R], \f[C]booktabs\f[R], \f[C]graphicx\f[R] (if the
177−\f[C]graphicx\f[R] (if the document contains images),
178+document contains images), \f[C]hyperref\f[R], \f[C]xcolor\f[R],
178−\f[C]hyperref\f[R], \f[C]xcolor\f[R], \f[C]ulem\f[R], \f[C]geometry\f[R]
179−(with the \f[C]geometry\f[R] variable set), \f[C]setspace\f[R] (with
179+\f[C]ulem\f[R], \f[C]geometry\f[R] (with the \f[C]geometry\f[R] variable
180+set), \f[C]setspace\f[R] (with \f[C]linestretch\f[R]), and
180−\f[C]linestretch\f[R]), and \f[C]babel\f[R] (with \f[C]lang\f[R]).
181+\f[C]babel\f[R] (with \f[C]lang\f[R]).
181The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the PDF engine
182The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the PDF engine
182requires \f[C]fontspec\f[R].
183requires \f[C]fontspec\f[R].
183−\f[C]lualatex\f[R] uses \f[C]selnolig\f[R].
184\f[C]xelatex\f[R] uses \f[C]polyglossia\f[R] (with \f[C]lang\f[R]),
184\f[C]xelatex\f[R] uses \f[C]polyglossia\f[R] (with \f[C]lang\f[R]),
185\f[C]xecjk\f[R], and \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable
185\f[C]xecjk\f[R], and \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable
@@ -227,18 +227,12 @@ Specify input format.
227\f[I]FORMAT\f[R] can be:
227\f[I]FORMAT\f[R] can be:
229.IP \[bu] 2
229.IP \[bu] 2
230−\f[C]bibtex\f[R] (BibTeX bibliography)
232−\f[C]biblatex\f[R] (BibLaTeX bibliography)
234\f[C]commonmark\f[R] (CommonMark Markdown)
230\f[C]commonmark\f[R] (CommonMark Markdown)
235.IP \[bu] 2
231.IP \[bu] 2
236\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)
232\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)
237.IP \[bu] 2
233.IP \[bu] 2
238\f[C]creole\f[R] (Creole 1.0)
234\f[C]creole\f[R] (Creole 1.0)
239.IP \[bu] 2
235.IP \[bu] 2
240−\f[C]csljson\f[R] (CSL JSON bibliography)
242\f[C]csv\f[R] (CSV table)
236\f[C]csv\f[R] (CSV table)
243.IP \[bu] 2
237.IP \[bu] 2
244\f[C]docbook\f[R] (DocBook)
238\f[C]docbook\f[R] (DocBook)
@@ -269,7 +263,7 @@ if you need extensions not supported in \f[C]gfm\f[R].
269.IP \[bu] 2
263.IP \[bu] 2
270\f[C]latex\f[R] (LaTeX)
264\f[C]latex\f[R] (LaTeX)
271.IP \[bu] 2
265.IP \[bu] 2
272−\f[C]markdown\f[R] (Pandoc\[cq]s Markdown)
266+\f[C]markdown\f[R] (Pandoc\[aq]s Markdown)
273.IP \[bu] 2
267.IP \[bu] 2
274\f[C]markdown_mmd\f[R] (MultiMarkdown)
268\f[C]markdown_mmd\f[R] (MultiMarkdown)
275.IP \[bu] 2
269.IP \[bu] 2
@@ -319,18 +313,12 @@ Specify output format.
319.IP \[bu] 2
313.IP \[bu] 2
320\f[C]beamer\f[R] (LaTeX beamer slide show)
314\f[C]beamer\f[R] (LaTeX beamer slide show)
321.IP \[bu] 2
315.IP \[bu] 2
322−\f[C]bibtex\f[R] (BibTeX bibliography)
324−\f[C]biblatex\f[R] (BibLaTeX bibliography)
326\f[C]commonmark\f[R] (CommonMark Markdown)
316\f[C]commonmark\f[R] (CommonMark Markdown)
327.IP \[bu] 2
317.IP \[bu] 2
328\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)
318\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)
329.IP \[bu] 2
319.IP \[bu] 2
330\f[C]context\f[R] (ConTeXt)
320\f[C]context\f[R] (ConTeXt)
331.IP \[bu] 2
321.IP \[bu] 2
332−\f[C]csljson\f[R] (CSL JSON bibliography)
334\f[C]docbook\f[R] or \f[C]docbook4\f[R] (DocBook 4)
322\f[C]docbook\f[R] or \f[C]docbook4\f[R] (DocBook 4)
335.IP \[bu] 2
323.IP \[bu] 2
336\f[C]docbook5\f[R] (DocBook 5)
324\f[C]docbook5\f[R] (DocBook 5)
@@ -351,8 +339,8 @@ if you need extensions not supported in \f[C]gfm\f[R].
351.IP \[bu] 2
339.IP \[bu] 2
352\f[C]haddock\f[R] (Haddock markup)
340\f[C]haddock\f[R] (Haddock markup)
353.IP \[bu] 2
341.IP \[bu] 2
354−\f[C]html\f[R] or \f[C]html5\f[R] (HTML, i.e.\ HTML5/XHTML polyglot
342+\f[C]html\f[R] or \f[C]html5\f[R] (HTML, i.e.
355−markup)
343+HTML5/XHTML polyglot markup)
356.IP \[bu] 2
344.IP \[bu] 2
357\f[C]html4\f[R] (XHTML 1.0 Transitional)
345\f[C]html4\f[R] (XHTML 1.0 Transitional)
358.IP \[bu] 2
346.IP \[bu] 2
@@ -376,7 +364,7 @@ markup)
376.IP \[bu] 2
364.IP \[bu] 2
377\f[C]man\f[R] (roff man)
365\f[C]man\f[R] (roff man)
378.IP \[bu] 2
366.IP \[bu] 2
379−\f[C]markdown\f[R] (Pandoc\[cq]s Markdown)
367+\f[C]markdown\f[R] (Pandoc\[aq]s Markdown)
380.IP \[bu] 2
368.IP \[bu] 2
381\f[C]markdown_mmd\f[R] (MultiMarkdown)
369\f[C]markdown_mmd\f[R] (MultiMarkdown)
382.IP \[bu] 2
370.IP \[bu] 2
@@ -457,15 +445,16 @@ On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory
457of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],
445of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],
458overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment
446overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment
459variable).
447variable).
460−If that directory does not exist and \f[C]$HOME/.pandoc\f[R] exists, it
448+If that directory does not exist, \f[C]$HOME/.pandoc\f[R] will be used
461−will be used (for backwards compatibility).
449+(for backwards compatibility).
462−On Windows the default user data directory is
450+In Windows the default user data directory is
463\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].
451\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].
464You can find the default user data directory on your system by looking
452You can find the default user data directory on your system by looking
465at the output of \f[C]pandoc --version\f[R].
453at the output of \f[C]pandoc --version\f[R].
466−Data files placed in this directory (for example,
467−\f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
454+A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
455+\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or
456+\f[C]s5\f[R] directory placed in this directory will override
468−\f[C]templates\f[R]) will override pandoc\[cq]s normal defaults.
457+pandoc\[aq]s normal defaults.
470\f[B]\f[CB]-d\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--defaults=\f[B]\f[R]\f[I]FILE\f[R]
459\f[B]\f[CB]-d\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--defaults=\f[B]\f[R]\f[I]FILE\f[R]
471Specify a set of default option settings.
460Specify a set of default option settings.
@@ -518,7 +507,7 @@ List supported output formats, one per line.
518List supported extensions for \f[I]FORMAT\f[R], one per line, preceded
507List supported extensions for \f[I]FORMAT\f[R], one per line, preceded
519by a \f[C]+\f[R] or \f[C]-\f[R] indicating whether it is enabled by
508by a \f[C]+\f[R] or \f[C]-\f[R] indicating whether it is enabled by
520default in \f[I]FORMAT\f[R].
509default in \f[I]FORMAT\f[R].
521−If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[cq]s Markdown
510+If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[aq]s Markdown
522are given.
511are given.
524\f[B]\f[CB]--list-highlight-languages\f[B]\f[R]
513\f[B]\f[CB]--list-highlight-languages\f[B]\f[R]
@@ -563,7 +552,7 @@ This option is useful for converting word processing documents where
563users have used empty paragraphs to create inter-paragraph space.
552users have used empty paragraphs to create inter-paragraph space.
565\f[B]\f[CB]--indented-code-classes=\f[B]\f[R]\f[I]CLASSES\f[R]
554\f[B]\f[CB]--indented-code-classes=\f[B]\f[R]\f[I]CLASSES\f[R]
566−Specify classes to use for indented code blocks\[en]for example,
555+Specify classes to use for indented code blocks--for example,
567\f[C]perl,numberLines\f[R] or \f[C]haskell\f[R].
556\f[C]perl,numberLines\f[R] or \f[C]haskell\f[R].
568Multiple classes may be separated by spaces or commas.
557Multiple classes may be separated by spaces or commas.
@@ -585,7 +574,7 @@ Reading binary files (docx, odt, epub) implies \f[C]--file-scope\f[R].
585Specify an executable to be used as a filter transforming the pandoc AST
574Specify an executable to be used as a filter transforming the pandoc AST
586after the input is parsed and before the output is written.
575after the input is parsed and before the output is written.
587The executable should read JSON from stdin and write JSON to stdout.
576The executable should read JSON from stdin and write JSON to stdout.
588−The JSON must be formatted like pandoc\[cq]s own JSON input and output.
577+The JSON must be formatted like pandoc\[aq]s own JSON input and output.
589The name of the output format will be passed to the filter as the first
578The name of the output format will be passed to the filter as the first
@@ -625,13 +614,13 @@ above).
625.IP "3." 3
614.IP "3." 3
626\f[C]$PATH\f[R] (executable only)
615\f[C]$PATH\f[R] (executable only)
628−Filters, Lua-filters, and citeproc processing are applied in the order
617+Filters and Lua-filters are applied in the order specified on the
629−specified on the command line.
618+command line.
632\f[B]\f[CB]-L\f[B]\f[R] \f[I]SCRIPT\f[R], \f[B]\f[CB]--lua-filter=\f[B]\f[R]\f[I]SCRIPT\f[R]
621\f[B]\f[CB]-L\f[B]\f[R] \f[I]SCRIPT\f[R], \f[B]\f[CB]--lua-filter=\f[B]\f[R]\f[I]SCRIPT\f[R]
633Transform the document in a similar fashion as JSON filters (see
622Transform the document in a similar fashion as JSON filters (see
634−\f[C]--filter\f[R]), but use pandoc\[cq]s built-in Lua filtering system.
623+\f[C]--filter\f[R]), but use pandoc\[aq]s build-in Lua filtering system.
635The given Lua script is expected to return a list of Lua filters which
624The given Lua script is expected to return a list of Lua filters which
636will be applied in order.
625will be applied in order.
637Each Lua filter must contain element-transforming functions indexed by
626Each Lua filter must contain element-transforming functions indexed by
@@ -641,19 +630,31 @@ applied.
642The \f[C]pandoc\f[R] Lua module provides helper functions for element
631The \f[C]pandoc\f[R] Lua module provides helper functions for element
644−It is always loaded into the script\[cq]s Lua environment.
633+It is always loaded into the script\[aq]s Lua environment.
646−See the Lua filters documentation for further details.
635+The following is an example Lua script for macro-expansion:
639+function expand_hello_world(inline)
640+ if inline.c == \[aq]{{helloworld}}\[aq] then
641+ return pandoc.Emph{ pandoc.Str \[dq]Hello, World\[dq] }
647+return {{Str = expand_hello_world}}
648In order of preference, pandoc will look for Lua filters in
651In order of preference, pandoc will look for Lua filters in
649.IP "1." 3
652.IP "1." 3
650−a specified full or relative path
653+a specified full or relative path (executable or non-executable)
651.IP "2." 3
654.IP "2." 3
652−\f[C]$DATADIR/filters\f[R] where \f[C]$DATADIR\f[R] is the user data
655+\f[C]$DATADIR/filters\f[R] (executable or non-executable) where
653−directory (see \f[C]--data-dir\f[R], above).
656+\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
655−Filters, Lua filters, and citeproc processing are applied in the order
656−specified on the command line.
659\f[B]\f[CB]-M\f[B]\f[R] \f[I]KEY\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]VAL\f[R]], \f[B]\f[CB]--metadata=\f[B]\f[R]\f[I]KEY\f[R][\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]]
660\f[B]\f[CB]-M\f[B]\f[R] \f[I]KEY\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]VAL\f[R]], \f[B]\f[CB]--metadata=\f[B]\f[R]\f[I]KEY\f[R][\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]]
@@ -693,13 +694,13 @@ Specify the number of spaces per tab (default is 4).
694\f[B]\f[CB]--track-changes=accept\f[B]\f[R]|\f[B]\f[CB]reject\f[B]\f[R]|\f[B]\f[CB]all\f[B]\f[R]
695\f[B]\f[CB]--track-changes=accept\f[B]\f[R]|\f[B]\f[CB]reject\f[B]\f[R]|\f[B]\f[CB]all\f[B]\f[R]
695Specifies what to do with insertions, deletions, and comments produced
696Specifies what to do with insertions, deletions, and comments produced
696−by the MS Word \[lq]Track Changes\[rq] feature.
697+by the MS Word \[dq]Track Changes\[dq] feature.
697−\f[C]accept\f[R] (the default) processes all the insertions and
698+\f[C]accept\f[R] (the default), inserts all insertions, and ignores all
698deletions.
699deletions.
699−\f[C]reject\f[R] ignores them.
700+\f[C]reject\f[R] inserts all deletions and ignores insertions.
700Both \f[C]accept\f[R] and \f[C]reject\f[R] ignore comments.
701Both \f[C]accept\f[R] and \f[C]reject\f[R] ignore comments.
701−\f[C]all\f[R] includes all insertions, deletions, and comments, wrapped
702+\f[C]all\f[R] puts in insertions, deletions, and comments, wrapped in
702−in spans with \f[C]insertion\f[R], \f[C]deletion\f[R],
703+spans with \f[C]insertion\f[R], \f[C]deletion\f[R],
703\f[C]comment-start\f[R], and \f[C]comment-end\f[R] classes,
704\f[C]comment-start\f[R], and \f[C]comment-end\f[R] classes,
704respectively.
705respectively.
705The author and time of change is included.
706The author and time of change is included.
@@ -716,11 +717,11 @@ Extract images and other media contained in or linked from the source
716document to the path \f[I]DIR\f[R], creating it if necessary, and adjust
717document to the path \f[I]DIR\f[R], creating it if necessary, and adjust
717the images references in the document so they point to the extracted
718the images references in the document so they point to the extracted
719−Media are downloaded, read from the file system, or extracted from a
720−binary container (e.g.\ docx), as needed.
720+If the source format is a binary container (docx, epub, or odt), the
721−The original file paths are used if they are relative paths not
721+media is extracted from the container and the original filenames are
722−containing \f[C]..\f[R].
722+used.
723+Otherwise the media is read from the file system or downloaded, and new
723−Otherwise filenames are constructed from the SHA1 hash of the contents.
724+filenames are constructed based on SHA1 hashes of the contents.
725\f[B]\f[CB]--abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
726\f[B]\f[CB]--abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
726Specifies a custom abbreviations file, with abbreviations one to a line.
727Specifies a custom abbreviations file, with abbreviations one to a line.
@@ -730,14 +731,14 @@ system default.
730To see the system default, use
731To see the system default, use
731\f[C]pandoc --print-default-data-file=abbreviations\f[R].
732\f[C]pandoc --print-default-data-file=abbreviations\f[R].
732The only use pandoc makes of this list is in the Markdown reader.
733The only use pandoc makes of this list is in the Markdown reader.
733−Strings found in this list will be followed by a nonbreaking space, and
734+Strings ending in a period that are found in this list will be followed
735+by a nonbreaking space, so that the period will not produce
734−the period will not produce sentence-ending space in formats like LaTeX.
736+sentence-ending space in formats like LaTeX.
735−The strings may not contain spaces.
736.SS General writer options
737.SS General writer options
738\f[B]\f[CB]-s\f[B]\f[R], \f[B]\f[CB]--standalone\f[B]\f[R]
739\f[B]\f[CB]-s\f[B]\f[R], \f[B]\f[CB]--standalone\f[B]\f[R]
739−Produce output with an appropriate header and footer (e.g.\ a standalone
740+Produce output with an appropriate header and footer (e.g.
740−HTML, LaTeX, TEI, or RTF file, not a fragment).
741+a standalone HTML, LaTeX, TEI, or RTF file, not a fragment).
741This option is set automatically for \f[C]pdf\f[R], \f[C]epub\f[R],
742This option is set automatically for \f[C]pdf\f[R], \f[C]epub\f[R],
742\f[C]epub3\f[R], \f[C]fb2\f[R], \f[C]docx\f[R], and \f[C]odt\f[R]
743\f[C]epub3\f[R], \f[C]fb2\f[R], \f[C]docx\f[R], and \f[C]odt\f[R]
@@ -897,7 +898,8 @@ Implies \f[C]--standalone\f[R].
898\f[B]\f[CB]-B\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-before-body=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
899\f[B]\f[CB]-B\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--include-before-body=\f[B]\f[R]\f[I]FILE\f[R]|\f[I]URL\f[R]
899Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the
900Include contents of \f[I]FILE\f[R], verbatim, at the beginning of the
900−document body (e.g.\ after the \f[C]<body>\f[R] tag in HTML, or the
902+after the \f[C]<body>\f[R] tag in HTML, or the
901\f[C]\[rs]begin{document}\f[R] command in LaTeX).
903\f[C]\[rs]begin{document}\f[R] command in LaTeX).
902This can be used to include navigation bars or banners in HTML
904This can be used to include navigation bars or banners in HTML
903documents.
905documents.
@@ -923,17 +925,19 @@ Note that, if \f[C]--resource-path\f[R] is specified, the working
923directory must be explicitly listed or it will not be searched.
925directory must be explicitly listed or it will not be searched.
924For example: \f[C]--resource-path=.:test\f[R] will search the working
926For example: \f[C]--resource-path=.:test\f[R] will search the working
925directory and the \f[C]test\f[R] subdirectory, in that order.
927directory and the \f[C]test\f[R] subdirectory, in that order.
926−This option can be used repeatedly.
928+.RS
927−Search path components that come later on the command line will be
929+.PP
928−searched before those that come earlier, so
930+\f[C]--resource-path\f[R] only has an effect if (a) the output format
929−\f[C]--resource-path foo:bar --resource-path baz:bim\f[R] is equivalent
931+embeds images (for example, \f[C]docx\f[R], \f[C]pdf\f[R], or
930−to \f[C]--resource-path baz:bim:foo:bar\f[R].
932+\f[C]html\f[R] with \f[C]--self-contained\f[R]) or (b) it is used
933+together with \f[C]--extract-media\f[R].
932\f[B]\f[CB]--request-header=\f[B]\f[R]\f[I]NAME\f[R]\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]
936\f[B]\f[CB]--request-header=\f[B]\f[R]\f[I]NAME\f[R]\f[B]\f[CB]:\f[B]\f[R]\f[I]VAL\f[R]
933Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when
937Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when
934making HTTP requests (for example, when a URL is given on the command
938making HTTP requests (for example, when a URL is given on the command
935line, or when resources used in a document must be downloaded).
939line, or when resources used in a document must be downloaded).
936−If you\[cq]re behind a proxy, you also need to set the environment
940+If you\[aq]re behind a proxy, you also need to set the environment
937variable \f[C]http_proxy\f[R] to \f[C]http://...\f[R].
941variable \f[C]http_proxy\f[R] to \f[C]http://...\f[R].
939\f[B]\f[CB]--no-check-certificate\f[B]\f[R]
943\f[B]\f[CB]--no-check-certificate\f[B]\f[R]
@@ -947,7 +951,7 @@ Produce a standalone HTML file with no external dependencies, using
947\f[C]data:\f[R] URIs to incorporate the contents of linked scripts,
951\f[C]data:\f[R] URIs to incorporate the contents of linked scripts,
948stylesheets, images, and videos.
952stylesheets, images, and videos.
949Implies \f[C]--standalone\f[R].
953Implies \f[C]--standalone\f[R].
950−The resulting file should be \[lq]self-contained,\[rq] in the sense that
954+The resulting file should be \[dq]self-contained,\[dq] in the sense that
951it needs no external files and no net access to be displayed properly by
955it needs no external files and no net access to be displayed properly by
952a browser.
956a browser.
953This option works only with HTML output formats, including
957This option works only with HTML output formats, including
@@ -963,14 +967,12 @@ left alone; the documents they link to will not be incorporated in the
964Limitation: resources that are loaded dynamically through JavaScript
968Limitation: resources that are loaded dynamically through JavaScript
965cannot be incorporated; as a result, \f[C]--self-contained\f[R] does not
969cannot be incorporated; as a result, \f[C]--self-contained\f[R] does not
966−work with \f[C]--mathjax\f[R], and some advanced features (e.g.\ zoom or
970+work with \f[C]--mathjax\f[R], and some advanced features (e.g.
967−speaker notes) may not work in an offline \[lq]self-contained\[rq]
971+zoom or speaker notes) may not work in an offline
968−\f[C]reveal.js\f[R] slide show.
972+\[dq]self-contained\[dq] \f[C]reveal.js\f[R] slide show.
970\f[B]\f[CB]--html-q-tags\f[B]\f[R]
974\f[B]\f[CB]--html-q-tags\f[B]\f[R]
971Use \f[C]<q>\f[R] tags for quotes in HTML.
975Use \f[C]<q>\f[R] tags for quotes in HTML.
972−(This option only has an effect if the \f[C]smart\f[R] extension is
973−enabled for the input format used.)
975\f[B]\f[CB]--ascii\f[B]\f[R]
977\f[B]\f[CB]--ascii\f[B]\f[R]
976Use only ASCII characters in output.
978Use only ASCII characters in output.
@@ -988,24 +990,21 @@ By default inline links are used.
988The placement of link references is affected by the
990The placement of link references is affected by the
989\f[C]--reference-location\f[R] option.
991\f[C]--reference-location\f[R] option.
991−\f[B]\f[CB]--reference-location=block\f[B]\f[R]|\f[B]\f[CB]section\f[B]\f[R]|\f[B]\f[CB]document\f[B]\f[R]
993+\f[B]\f[CB]--reference-location = block\f[B]\f[R]|\f[B]\f[CB]section\f[B]\f[R]|\f[B]\f[CB]document\f[B]\f[R]
992Specify whether footnotes (and references, if \f[C]reference-links\f[R]
994Specify whether footnotes (and references, if \f[C]reference-links\f[R]
993is set) are placed at the end of the current (top-level) block, the
995is set) are placed at the end of the current (top-level) block, the
994current section, or the document.
996current section, or the document.
995The default is \f[C]document\f[R].
997The default is \f[C]document\f[R].
996Currently only affects the markdown writer.
998Currently only affects the markdown writer.
998−\f[B]\f[CB]--markdown-headings=setext\f[B]\f[R]|\f[B]\f[CB]atx\f[B]\f[R]
999−Specify whether to use ATX-style (\f[C]#\f[R]-prefixed) or Setext-style
1000−(underlined) headings for level 1 and 2 headings in Markdown output.
1001−(The default is \f[C]atx\f[R].) ATX-style headings are always used for
1003−This option also affects Markdown cells in \f[C]ipynb\f[R] output.
1005\f[B]\f[CB]--atx-headers\f[B]\f[R]
1000\f[B]\f[CB]--atx-headers\f[B]\f[R]
1006−\f[I]Deprecated synonym for \f[CI]--markdown-headings=atx\f[I].\f[R]
1001+Use ATX-style headings in Markdown output.
1002+The default is to use setext-style headings for levels 1 to 2, and then
1004+(Note: for \f[C]gfm\f[R] output, ATX headings are always used.) This
1005+option also affects markdown cells in \f[C]ipynb\f[R] output.
1008−\f[B]\f[CB]--top-level-division=default\f[B]\f[R]|\f[B]\f[CB]section\f[B]\f[R]|\f[B]\f[CB]chapter\f[B]\f[R]|\f[B]\f[CB]part\f[B]\f[R]
1007+\f[B]\f[CB]--top-level-division=[default|section|chapter|part]\f[B]\f[R]
1009Treat top-level headings as the given division type in LaTeX, ConTeXt,
1008Treat top-level headings as the given division type in LaTeX, ConTeXt,
1010DocBook, and TEI output.
1009DocBook, and TEI output.
1011The hierarchy order is part, chapter, then section; all headings are
1010The hierarchy order is part, chapter, then section; all headings are
@@ -1022,22 +1021,21 @@ become \f[C]\[rs]part{..}\f[R], while second-level headings remain as
1022their default type.
1021their default type.
1024\f[B]\f[CB]-N\f[B]\f[R], \f[B]\f[CB]--number-sections\f[B]\f[R]
1023\f[B]\f[CB]-N\f[B]\f[R], \f[B]\f[CB]--number-sections\f[B]\f[R]
1025−Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB
1024+Number section headings in LaTeX, ConTeXt, HTML, Docx, or EPUB output.
1027By default, sections are not numbered.
1025By default, sections are not numbered.
1028Sections with class \f[C]unnumbered\f[R] will never be numbered, even if
1026Sections with class \f[C]unnumbered\f[R] will never be numbered, even if
1029\f[C]--number-sections\f[R] is specified.
1027\f[C]--number-sections\f[R] is specified.
1031−\f[B]\f[CB]--number-offset=\f[B]\f[R]\f[I]NUMBER\f[R][\f[B]\f[CB],\f[B]\f[R]\f[I]NUMBER\f[R]\f[B]\f[CB],\f[B]\f[R]\f[I]\&...\f[R]]
1029+\f[B]\f[CB]--number-offset=\f[B]\f[R]\f[I]NUMBER\f[R][\f[B]\f[CB],\f[B]\f[R]\f[I]NUMBER\f[R]\f[B]\f[CB],\f[B]\f[R]\f[I]...\f[R]]
1032Offset for section headings in HTML output (ignored in other output
1030Offset for section headings in HTML output (ignored in other output
1033formats).
1031formats).
1034The first number is added to the section number for top-level headings,
1032The first number is added to the section number for top-level headings,
1035the second for second-level headings, and so on.
1033the second for second-level headings, and so on.
1036So, for example, if you want the first top-level heading in your
1034So, for example, if you want the first top-level heading in your
1037−document to be numbered \[lq]6\[rq], specify
1035+document to be numbered \[dq]6\[dq], specify
1038\f[C]--number-offset=5\f[R].
1036\f[C]--number-offset=5\f[R].
1039If your document starts with a level-2 heading which you want to be
1037If your document starts with a level-2 heading which you want to be
1040−numbered \[lq]1.5\[rq], specify \f[C]--number-offset=1,4\f[R].
1038+numbered \[dq]1.5\[dq], specify \f[C]--number-offset=1,4\f[R].
1041Offsets are 0 by default.
1039Offsets are 0 by default.
1042Implies \f[C]--number-sections\f[R].
1040Implies \f[C]--number-sections\f[R].
@@ -1336,7 +1334,7 @@ body { font-family: \[dq]DejaVuSans\[dq]; }
1337\f[B]\f[CB]--epub-chapter-level=\f[B]\f[R]\f[I]NUMBER\f[R]
1335\f[B]\f[CB]--epub-chapter-level=\f[B]\f[R]\f[I]NUMBER\f[R]
1338Specify the heading level at which to split the EPUB into separate
1336Specify the heading level at which to split the EPUB into separate
1339−\[lq]chapter\[rq] files.
1337+\[dq]chapter\[dq] files.
1340The default is to split into chapters at level-1 headings.
1338The default is to split into chapters at level-1 headings.
1341This option only affects the internal composition of the EPUB, not the
1339This option only affects the internal composition of the EPUB, not the
1342way chapters and sections are displayed to users.
1340way chapters and sections are displayed to users.
@@ -1388,69 +1386,47 @@ introduction to PDF generation from HTML/CSS.)
1388Use the given string as a command-line argument to the
1386Use the given string as a command-line argument to the
1389\f[C]pdf-engine\f[R].
1387\f[C]pdf-engine\f[R].
1390For example, to use a persistent directory \f[C]foo\f[R] for
1388For example, to use a persistent directory \f[C]foo\f[R] for
1391−\f[C]latexmk\f[R]\[cq]s auxiliary files, use
1389+\f[C]latexmk\f[R]\[aq]s auxiliary files, use
1392\f[C]--pdf-engine-opt=-outdir=foo\f[R].
1390\f[C]--pdf-engine-opt=-outdir=foo\f[R].
1393Note that no check for duplicate options is done.
1391Note that no check for duplicate options is done.
1394.SS Citation rendering
1392.SS Citation rendering
1396−\f[B]\f[CB]-C\f[B]\f[R], \f[B]\f[CB]--citeproc\f[B]\f[R]
1397−Process the citations in the file, replacing them with rendered
1398−citations and adding a bibliography.
1399−Citation processing will not take place unless bibliographic data is
1400−supplied, either through an external file specified using the
1401−\f[C]--bibliography\f[R] option or the \f[C]bibliography\f[R] field in
1402−metadata, or via a \f[C]references\f[R] section in metadata containing a
1403−list of citations in CSL YAML format with Markdown formatting.
1404−The style is controlled by a CSL stylesheet specified using the
1405−\f[C]--csl\f[R] option or the \f[C]csl\f[R] field in metadata.
1406−(If no stylesheet is specified, the \f[C]chicago-author-date\f[R] style
1407−will be used by default.) The citation processing transformation may be
1408−applied before or after filters or Lua filters (see \f[C]--filter\f[R],
1409−\f[C]--lua-filter\f[R]): these transformations are applied in the order
1410−they appear on the command line.
1411−For more information, see the section on Citations.
1413\f[B]\f[CB]--bibliography=\f[B]\f[R]\f[I]FILE\f[R]
1394\f[B]\f[CB]--bibliography=\f[B]\f[R]\f[I]FILE\f[R]
1414−Set the \f[C]bibliography\f[R] field in the document\[cq]s metadata to
1395+Set the \f[C]bibliography\f[R] field in the document\[aq]s metadata to
1415−\f[I]FILE\f[R], overriding any value set in the metadata.
1396+\f[I]FILE\f[R], overriding any value set in the metadata, and process
1397+citations using \f[C]pandoc-citeproc\f[R].
1398+(This is equivalent to
1399+\f[C]--metadata bibliography=FILE --filter pandoc-citeproc\f[R].) If
1400+\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] is also supplied,
1401+\f[C]pandoc-citeproc\f[R] is not used, making this equivalent to
1402+\f[C]--metadata bibliography=FILE\f[R].
1416If you supply this argument multiple times, each \f[I]FILE\f[R] will be
1403If you supply this argument multiple times, each \f[I]FILE\f[R] will be
1417added to bibliography.
1404added to bibliography.
1418−If \f[I]FILE\f[R] is a URL, it will be fetched via HTTP.
1419−If \f[I]FILE\f[R] is not found relative to the working directory, it
1420−will be sought in the resource path (see \f[C]--resource-path\f[R]).
1422\f[B]\f[CB]--csl=\f[B]\f[R]\f[I]FILE\f[R]
1406\f[B]\f[CB]--csl=\f[B]\f[R]\f[I]FILE\f[R]
1423−Set the \f[C]csl\f[R] field in the document\[cq]s metadata to
1407+Set the \f[C]csl\f[R] field in the document\[aq]s metadata to
1424\f[I]FILE\f[R], overriding any value set in the metadata.
1408\f[I]FILE\f[R], overriding any value set in the metadata.
1425−(This is equivalent to \f[C]--metadata csl=FILE\f[R].) If \f[I]FILE\f[R]
1409+(This is equivalent to \f[C]--metadata csl=FILE\f[R].) This option is
1426−is a URL, it will be fetched via HTTP.
1410+only relevant with \f[C]pandoc-citeproc\f[R].
1427−If \f[I]FILE\f[R] is not found relative to the working directory, it
1428−will be sought in the resource path (see \f[C]--resource-path\f[R]) and
1429−finally in the \f[C]csl\f[R] subdirectory of the pandoc user data
1432\f[B]\f[CB]--citation-abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
1412\f[B]\f[CB]--citation-abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
1433−Set the \f[C]citation-abbreviations\f[R] field in the document\[cq]s
1413+Set the \f[C]citation-abbreviations\f[R] field in the document\[aq]s
1434metadata to \f[I]FILE\f[R], overriding any value set in the metadata.
1414metadata to \f[I]FILE\f[R], overriding any value set in the metadata.
1435(This is equivalent to
1415(This is equivalent to
1436−\f[C]--metadata citation-abbreviations=FILE\f[R].) If \f[I]FILE\f[R] is
1416+\f[C]--metadata citation-abbreviations=FILE\f[R].) This option is only
1437−a URL, it will be fetched via HTTP.
1417+relevant with \f[C]pandoc-citeproc\f[R].
1438−If \f[I]FILE\f[R] is not found relative to the working directory, it
1439−will be sought in the resource path (see \f[C]--resource-path\f[R]) and
1440−finally in the \f[C]csl\f[R] subdirectory of the pandoc user data
1443\f[B]\f[CB]--natbib\f[B]\f[R]
1419\f[B]\f[CB]--natbib\f[B]\f[R]
1444Use \f[C]natbib\f[R] for citations in LaTeX output.
1420Use \f[C]natbib\f[R] for citations in LaTeX output.
1445−This option is not for use with the \f[C]--citeproc\f[R] option or with
1421+This option is not for use with the \f[C]pandoc-citeproc\f[R] filter or
1446−PDF output.
1422+with PDF output.
1447It is intended for use in producing a LaTeX file that can be processed
1423It is intended for use in producing a LaTeX file that can be processed
1448with \f[C]bibtex\f[R].
1424with \f[C]bibtex\f[R].
1450\f[B]\f[CB]--biblatex\f[B]\f[R]
1426\f[B]\f[CB]--biblatex\f[B]\f[R]
1451Use \f[C]biblatex\f[R] for citations in LaTeX output.
1427Use \f[C]biblatex\f[R] for citations in LaTeX output.
1452−This option is not for use with the \f[C]--citeproc\f[R] option or with
1428+This option is not for use with the \f[C]pandoc-citeproc\f[R] filter or
1453−PDF output.
1429+with PDF output.
1454It is intended for use in producing a LaTeX file that can be processed
1430It is intended for use in producing a LaTeX file that can be processed
1455with \f[C]bibtex\f[R] or \f[C]biber\f[R].
1431with \f[C]bibtex\f[R] or \f[C]biber\f[R].
1456.SS Math rendering in HTML
1432.SS Math rendering in HTML
@@ -1491,7 +1467,7 @@ For SVG images you can for example use
1491If no URL is specified, the CodeCogs URL generating PNGs will be used
1467If no URL is specified, the CodeCogs URL generating PNGs will be used
1492(\f[C]https://latex.codecogs.com/png.latex?\f[R]).
1468(\f[C]https://latex.codecogs.com/png.latex?\f[R]).
1493Note: the \f[C]--webtex\f[R] option will affect Markdown output as well
1469Note: the \f[C]--webtex\f[R] option will affect Markdown output as well
1494−as HTML, which is useful if you\[cq]re targeting a version of Markdown
1470+as HTML, which is useful if you\[aq]re targeting a version of Markdown
1495without native math support.
1471without native math support.
1497\f[B]\f[CB]--katex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
1473\f[B]\f[CB]--katex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
@@ -1504,16 +1480,16 @@ inserted.
1505\f[B]\f[CB]--gladtex\f[B]\f[R]
1481\f[B]\f[CB]--gladtex\f[B]\f[R]
1506Enclose TeX math in \f[C]<eq>\f[R] tags in HTML output.
1482Enclose TeX math in \f[C]<eq>\f[R] tags in HTML output.
1507−The resulting HTML can then be processed by GladTeX to produce SVG
1483+The resulting HTML can then be processed by GladTeX to produce images of
1508−images of the typeset formulas and an HTML file with these images
1484+the typeset formulas and an HTML file with links to these images.
1509−embedded.
1485+So, the procedure is:
1514pandoc -s --gladtex input.md -o myfile.htex
1490pandoc -s --gladtex input.md -o myfile.htex
1515−gladtex -d image_dir myfile.htex
1491+gladtex -d myfile-images myfile.htex
1516−# produces myfile.html and images in image_dir
1492+# produces myfile.html and images in myfile-images
@@ -1602,11 +1578,6 @@ T}@T{
1602PandocUnsupportedExtensionError
1578PandocUnsupportedExtensionError
1612PandocEpubSubdirectoryError
1583PandocEpubSubdirectoryError
@@ -1617,11 +1588,6 @@ T}@T{
1617PandocPDFError
1588PandocPDFError
1627PandocPDFProgramNotFoundError
1593PandocPDFProgramNotFoundError
@@ -1682,11 +1648,6 @@ T}@T{
1682PandocIpynbDecodingError
1648PandocIpynbDecodingError
1687−PandocUnsupportedCharsetError
1692PandocCouldNotFindDataFileError
1653PandocCouldNotFindDataFileError
@@ -1719,16 +1680,6 @@ input-files:
1719- content.md
1680- content.md
1720# or you may use input-file: with a single value
1681# or you may use input-file: with a single value
1722−# Include options from the specified defaults files.
1723−# The files will be searched for first in the working directory
1724−# and then in the defaults subdirectory of the user data directory.
1725−# The files are included in the same order in which they appear in
1726−# the list. Options specified in this defaults file always have
1727−# priority over the included ones.
1732template: letter
1683template: letter
1733standalone: true
1684standalone: true
1734self-contained: false
1685self-contained: false
@@ -1756,24 +1707,11 @@ include-after-body: []
1756include-in-header: []
1707include-in-header: []
1757resource-path: [\[dq].\[dq]]
1708resource-path: [\[dq].\[dq]]
1759−# turn on built-in citation processing. Note that if you need
1760−# control over when the citeproc processing is done relative
1761−# to other filters, you should instead use \[ga]citeproc\[ga] in the
1762−# list of \[ga]filters\[ga] (see below).
1768−citation-abbreviations: abbrevs.json
1770−# Filters will be assumed to be Lua filters if they have
1710+# filters will be assumed to be Lua filters if they have
1771# the .lua extension, and json filters otherwise. But
1711# the .lua extension, and json filters otherwise. But
1772−# the filter type can also be specified explicitly, as shown.
1712+# the filter type can also be specified explicitly, as shown:
1773−# Filters are run in the order specified.
1774−# To include the built-in citeproc filter, use either \[ga]citeproc\[ga]
1775−# or \[ga]{type: citeproc}\[ga].
1777- wordcount.lua
1715- wordcount.lua
1778- type: json
1716- type: json
1779 path: foo.lua
1717 path: foo.lua
@@ -1786,11 +1724,8 @@ data-dir:
1786verbosity: INFO
1724verbosity: INFO
1787log-file: log.json
1725log-file: log.json
1789−# citeproc, natbib, or biblatex. This only affects LaTeX
1727+# citeproc, natbib, or biblatex
1790−# output. If you want to use citeproc to format citations,
1791−# you should also set \[aq]citeproc: true\[aq] (see above).
1792cite-method: citeproc
1728cite-method: citeproc
1794# part, chapter, section, or default:
1729# part, chapter, section, or default:
1795top-level-division: chapter
1730top-level-division: chapter
1796abbreviations:
1731abbreviations:
@@ -1859,7 +1794,7 @@ epub-cover-image: cover.jpg
1859reference-links: true
1794reference-links: true
1860# block, section, or document
1795# block, section, or document
1861reference-location: block
1796reference-location: block
1862−markdown-headings: setext
1797+atx-headers: false
1864# accept, reject, or all
1799# accept, reject, or all
1865track-changes: accept
1800track-changes: accept
@@ -1891,38 +1826,6 @@ verbosity: INFO
1894−In fields that expect a file path (or list of file paths), the following
1895−syntax may be used to interpolate environment variables:
1899−csl: ${HOME}/mycsldir/special.csl
1903−\f[C]${USERDATA}\f[R] may also be used; this will always resolve to the
1904−user data directory that is current when the defaults file is parsed,
1905−regardless of the setting of the environment variable
1908−\f[C]${.}\f[R] will resolve to the directory containing the default file
1910−This allows you to refer to resources contained in that directory:
1914−epub-cover-image: ${.}/cover.jpg
1915−epub-metadata: ${.}/meta.xml
1917−- . # the working directory from which pandoc is run
1918−- ${.}/images # the images subdirectory of the directory
1919− # containing this defaults file
1923−This environment variable interpolation syntax \f[I]only\f[R] works in
1924−fields that expect file paths.
1926Default files can be placed in the \f[C]defaults\f[R] subdirectory of
1829Default files can be placed in the \f[C]defaults\f[R] subdirectory of
1927the user data directory and used from any directory.
1830the user data directory and used from any directory.
1928For example, one could create a file specifying defaults for writing
1831For example, one could create a file specifying defaults for writing
@@ -1979,10 +1882,10 @@ arbitrary information at any point in the file.
1979They may be set at the command line using the \f[C]-V/--variable\f[R]
1882They may be set at the command line using the \f[C]-V/--variable\f[R]
1981If a variable is not set, pandoc will look for the key in the
1884If a variable is not set, pandoc will look for the key in the
1982−document\[cq]s metadata, which can be set using either YAML metadata
1885+document\[aq]s metadata, which can be set using either YAML metadata
1983blocks or with the \f[C]-M/--metadata\f[R] option.
1886blocks or with the \f[C]-M/--metadata\f[R] option.
1984In addition, some variables are given default values by pandoc.
1887In addition, some variables are given default values by pandoc.
1985−See Variables below for a list of variables used in pandoc\[cq]s default
1888+See Variables below for a list of variables used in pandoc\[aq]s default
1986templates.
1889templates.
1988If you use custom templates, you may need to revise them as pandoc
1891If you use custom templates, you may need to revise them as pandoc
@@ -1999,8 +1902,8 @@ be treated as a comment and omitted from the output.
1999.SS Delimiters
1902.SS Delimiters
2001To mark variables and control structures in the template, either
1904To mark variables and control structures in the template, either
2002−\f[C]$\f[R]\&...\f[C]$\f[R] or \f[C]${\f[R]\&...\f[C]}\f[R] may be used
1905+\f[C]$\f[R]...\f[C]$\f[R] or \f[C]${\f[R]...\f[C]}\f[R] may be used as
2003−as delimiters.
1906+delimiters.
2004The styles may also be mixed in the same template, but the opening and
1907The styles may also be mixed in the same template, but the opening and
2005closing delimiter must match in each case.
1908closing delimiter must match in each case.
2006The opening delimiter may be followed by one or more spaces or tabs,
1909The opening delimiter may be followed by one or more spaces or tabs,
@@ -2182,9 +2085,9 @@ ${ styles.html() }
2185−(If a partial is not found in the directory of the template and the
2088+(If a partial is not found in the directory of the template, it will
2186−template path is given as a relative path, it will also be sought in the
2187−\f[C]templates\f[R] subdirectory of the user data directory.)
2089+also be sought in the \f[C]templates\f[R] subdirectory of the user data
2189Partials may optionally be applied to variables using a colon:
2092Partials may optionally be applied to variables using a colon:
@@ -2233,7 +2136,7 @@ an explicit \f[C]for\f[R] loop) cannot contain interpolated variables or
2233other template directives.
2136other template directives.
2234.SS Nesting
2137.SS Nesting
2236−To ensure that content is \[lq]nested,\[rq] that is, subsequent lines
2139+To ensure that content is \[dq]nested,\[dq] that is, subsequent lines
2237indented, use the \f[C]\[ha]\f[R] directive:
2140indented, use the \f[C]\[ha]\f[R] directive:
@@ -2275,7 +2178,7 @@ will produce
2276If a variable occurs by itself on a line, preceded by whitespace and not
2179If a variable occurs by itself on a line, preceded by whitespace and not
2277followed by further text or directives on the same line, and the
2180followed by further text or directives on the same line, and the
2278−variable\[cq]s value contains multiple lines, it will be nested
2181+variable\[aq]s value contains multiple lines, it will be nested
2279automatically.
2182automatically.
2280.SS Breakable spaces
2183.SS Breakable spaces
@@ -2417,8 +2320,7 @@ including a title block in the document itself, you can set the
2417\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]
2320\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]
2418variables.
2321variables.
2419(By default these are set automatically, based on \f[C]title\f[R],
2322(By default these are set automatically, based on \f[C]title\f[R],
2420−\f[C]author\f[R], and \f[C]date\f[R].) The page title in HTML is set by
2323+\f[C]author\f[R], and \f[C]date\f[R].)
2421−\f[C]pagetitle\f[R], which is equal to \f[C]title\f[R] by default.
2424\f[B]\f[CB]subtitle\f[B]\f[R]
2326\f[B]\f[CB]subtitle\f[B]\f[R]
@@ -2508,81 +2410,13 @@ For bidirectional documents, native pandoc \f[C]span\f[R]s and
2508\f[C]div\f[R]s with the \f[C]dir\f[R] attribute (value \f[C]rtl\f[R] or
2410\f[C]div\f[R]s with the \f[C]dir\f[R] attribute (value \f[C]rtl\f[R] or
2509\f[C]ltr\f[R]) can be used to override the base direction in some output
2411\f[C]ltr\f[R]) can be used to override the base direction in some output
2511−This may not always be necessary if the final renderer (e.g.\ the
2413+This may not always be necessary if the final renderer (e.g.
2512−browser, when generating HTML) supports the Unicode Bidirectional
2414+the browser, when generating HTML) supports the Unicode Bidirectional
2513Algorithm.
2415Algorithm.
2515When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]
2417When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]
2516engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).
2418engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).
2518−.SS Variables for HTML
2520−\f[B]\f[CB]document-css\f[B]\f[R]
2521−Enables inclusion of most of the CSS in the \f[C]styles.html\f[R]
2522−partial (have a look with
2523−\f[C]pandoc --print-default-data-file=templates/styles.html\f[R]).
2524−Unless you use \f[C]--css\f[R], this variable is set to \f[C]true\f[R]
2526−You can disable it with e.g.\ \f[C]pandoc -M document-css=false\f[R].
2528−\f[B]\f[CB]mainfont\f[B]\f[R]
2529−sets the CSS \f[C]font-family\f[R] property on the \f[C]html\f[R]
2532−\f[B]\f[CB]fontsize\f[B]\f[R]
2533−sets the base CSS \f[C]font-size\f[R], which you\[cq]d usually set to
2534−e.g.\ \f[C]20px\f[R], but it also accepts \f[C]pt\f[R] (12pt = 16px in
2537−\f[B]\f[CB]fontcolor\f[B]\f[R]
2538−sets the CSS \f[C]color\f[R] property on the \f[C]html\f[R] element.
2540−\f[B]\f[CB]linkcolor\f[B]\f[R]
2541−sets the CSS \f[C]color\f[R] property on all links.
2543−\f[B]\f[CB]monofont\f[B]\f[R]
2544−sets the CSS \f[C]font-family\f[R] property on \f[C]code\f[R] elements.
2546−\f[B]\f[CB]monobackgroundcolor\f[B]\f[R]
2547−sets the CSS \f[C]background-color\f[R] property on \f[C]code\f[R]
2548−elements and adds extra padding.
2550−\f[B]\f[CB]linestretch\f[B]\f[R]
2551−sets the CSS \f[C]line-height\f[R] property on the \f[C]html\f[R]
2552−element, which is preferred to be unitless.
2554−\f[B]\f[CB]backgroundcolor\f[B]\f[R]
2555−sets the CSS \f[C]background-color\f[R] property on the \f[C]html\f[R]
2558−\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]
2559−sets the corresponding CSS \f[C]padding\f[R] properties on the
2560−\f[C]body\f[R] element.
2562−To override or extend some CSS for just one document, include for
2571− font-style: italic;
2574− background-color: #f0f0f0;
2577− padding: 0.5em 2em 0.5em 0.5em;
2580− border-bottom: none;
2586.SS Variables for HTML math
2420.SS Variables for HTML math
2588\f[B]\f[CB]classoption\f[B]\f[R]
2422\f[B]\f[CB]classoption\f[B]\f[R]
@@ -2590,10 +2424,11 @@ when using KaTeX, you can render display math equations flush left using
2590YAML metadata or with \f[C]-M classoption=fleqn\f[R].
2424YAML metadata or with \f[C]-M classoption=fleqn\f[R].
2591.SS Variables for HTML slides
2425.SS Variables for HTML slides
2593−These affect HTML output when [producing slide shows with pandoc].
2427+These affect HTML output when producing slide shows with pandoc.
2595−\f[B]\f[CB]institute\f[B]\f[R]
2429+All reveal.js configuration options are available as variables.
2596−author affiliations: can be a list when there are multiple authors
2430+To turn off boolean flags that default to true in reveal.js, use
2598\f[B]\f[CB]revealjs-url\f[B]\f[R]
2433\f[B]\f[CB]revealjs-url\f[B]\f[R]
2599base URL for reveal.js documents (defaults to
2434base URL for reveal.js documents (defaults to
@@ -2612,10 +2447,6 @@ base URL for Slideous documents (defaults to \f[C]slideous\f[R])
2612\f[B]\f[CB]title-slide-attributes\f[B]\f[R]
2447\f[B]\f[CB]title-slide-attributes\f[B]\f[R]
2613additional attributes for the title slide of reveal.js slide shows.
2448additional attributes for the title slide of reveal.js slide shows.
2614See background in reveal.js and beamer for an example.
2449See background in reveal.js and beamer for an example.
2616−All reveal.js configuration options are available as variables.
2617−To turn off boolean flags that default to true in reveal.js, use
2619.SS Variables for Beamer slides
2450.SS Variables for Beamer slides
2621These variables change the appearance of PDF slides using
2452These variables change the appearance of PDF slides using
@@ -2644,7 +2475,7 @@ navigation symbols; other valid values are \f[C]frame\f[R],
2644\f[C]vertical\f[R], and \f[C]horizontal\f[R])
2475\f[C]vertical\f[R], and \f[C]horizontal\f[R])
2646\f[B]\f[CB]section-titles\f[B]\f[R]
2477\f[B]\f[CB]section-titles\f[B]\f[R]
2647−enables \[lq]title pages\[rq] for new sections (default is true)
2478+enables \[dq]title pages\[dq] for new sections (default is true)
2649\f[B]\f[CB]theme\f[B]\f[R], \f[B]\f[CB]colortheme\f[B]\f[R], \f[B]\f[CB]fonttheme\f[B]\f[R], \f[B]\f[CB]innertheme\f[B]\f[R], \f[B]\f[CB]outertheme\f[B]\f[R]
2480\f[B]\f[CB]theme\f[B]\f[R], \f[B]\f[CB]colortheme\f[B]\f[R], \f[B]\f[CB]fonttheme\f[B]\f[R], \f[B]\f[CB]innertheme\f[B]\f[R], \f[B]\f[CB]outertheme\f[B]\f[R]
2650beamer themes
2481beamer themes
@@ -2696,8 +2527,8 @@ header-includes: |
2698\f[B]\f[CB]classoption\f[B]\f[R]
2529\f[B]\f[CB]classoption\f[B]\f[R]
2530+option for document class, e.g.
2699−option for document class, e.g.\ \f[C]oneside\f[R]; repeat for multiple
2531+\f[C]oneside\f[R]; repeat for multiple options:
@@ -2718,8 +2549,8 @@ document class: usually one of the standard classes, \f[C]article\f[R],
2718default to smaller margins; or \f[C]memoir\f[R]
2549default to smaller margins; or \f[C]memoir\f[R]
2720\f[B]\f[CB]geometry\f[B]\f[R]
2551\f[B]\f[CB]geometry\f[B]\f[R]
2721−option for \f[C]geometry\f[R] package, e.g.\ \f[C]margin=1in\f[R];
2552+option for \f[C]geometry\f[R] package, e.g.
2722−repeat for multiple options:
2553+\f[C]margin=1in\f[R]; repeat for multiple options:
@@ -2735,8 +2566,8 @@ geometry:
2737\f[B]\f[CB]hyperrefoptions\f[B]\f[R]
2568\f[B]\f[CB]hyperrefoptions\f[B]\f[R]
2738−option for \f[C]hyperref\f[R] package, e.g.\ \f[C]linktoc=all\f[R];
2569+option for \f[C]hyperref\f[R] package, e.g.
2739−repeat for multiple options:
2570+\f[C]linktoc=all\f[R]; repeat for multiple options:
@@ -2752,13 +2583,12 @@ hyperrefoptions:
2754\f[B]\f[CB]indent\f[B]\f[R]
2585\f[B]\f[CB]indent\f[B]\f[R]
2755−if true, pandoc will use document class settings for indentation (the
2586+uses document class settings for indentation (the default LaTeX template
2756−default LaTeX template otherwise removes indentation and adds space
2587+otherwise removes indentation and adds space between paragraphs)
2759\f[B]\f[CB]linestretch\f[B]\f[R]
2589\f[B]\f[CB]linestretch\f[B]\f[R]
2760−adjusts line spacing using the \f[C]setspace\f[R] package,
2590+adjusts line spacing using the \f[C]setspace\f[R] package, e.g.
2761−e.g.\ \f[C]1.25\f[R], \f[C]1.5\f[R]
2591+\f[C]1.25\f[R], \f[C]1.5\f[R]
2763\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]
2593\f[B]\f[CB]margin-left\f[B]\f[R], \f[B]\f[CB]margin-right\f[B]\f[R], \f[B]\f[CB]margin-top\f[B]\f[R], \f[B]\f[CB]margin-bottom\f[B]\f[R]
2764sets margins if \f[C]geometry\f[R] is not used (otherwise
2594sets margins if \f[C]geometry\f[R] is not used (otherwise
@@ -2770,7 +2600,8 @@ control \f[C]\[rs]pagestyle{}\f[R]: the default article class supports
2770numbers), and \f[C]headings\f[R] (section titles in running heads)
2600numbers), and \f[C]headings\f[R] (section titles in running heads)
2772\f[B]\f[CB]papersize\f[B]\f[R]
2602\f[B]\f[CB]papersize\f[B]\f[R]
2773−paper size, e.g.\ \f[C]letter\f[R], \f[C]a4\f[R]
2604+\f[C]letter\f[R], \f[C]a4\f[R]
2775\f[B]\f[CB]secnumdepth\f[B]\f[R]
2606\f[B]\f[CB]secnumdepth\f[B]\f[R]
2776numbering depth for sections (with \f[C]--number-sections\f[R] option or
2607numbering depth for sections (with \f[C]--number-sections\f[R] option or
@@ -2895,32 +2726,35 @@ list of options for natbib
2895Pandoc uses these variables when creating a PDF with ConTeXt.
2726Pandoc uses these variables when creating a PDF with ConTeXt.
2897\f[B]\f[CB]fontsize\f[B]\f[R]
2728\f[B]\f[CB]fontsize\f[B]\f[R]
2898−font size for body text (e.g.\ \f[C]10pt\f[R], \f[C]12pt\f[R])
2729+font size for body text (e.g.
2730+\f[C]10pt\f[R], \f[C]12pt\f[R])
2900\f[B]\f[CB]headertext\f[B]\f[R], \f[B]\f[CB]footertext\f[B]\f[R]
2732\f[B]\f[CB]headertext\f[B]\f[R], \f[B]\f[CB]footertext\f[B]\f[R]
2901text to be placed in running header or footer (see ConTeXt Headers and
2733text to be placed in running header or footer (see ConTeXt Headers and
2902Footers); repeat up to four times for different placement
2734Footers); repeat up to four times for different placement
2904\f[B]\f[CB]indenting\f[B]\f[R]
2736\f[B]\f[CB]indenting\f[B]\f[R]
2905−controls indentation of paragraphs, e.g.\ \f[C]yes,small,next\f[R] (see
2737+controls indentation of paragraphs, e.g.
2906−ConTeXt Indentation); repeat for multiple options
2738+\f[C]yes,small,next\f[R] (see ConTeXt Indentation); repeat for multiple
2908\f[B]\f[CB]interlinespace\f[B]\f[R]
2741\f[B]\f[CB]interlinespace\f[B]\f[R]
2909−adjusts line spacing, e.g.\ \f[C]4ex\f[R] (using
2742+adjusts line spacing, e.g.
2910−\f[C]setupinterlinespace\f[R]); repeat for multiple options
2743+\f[C]4ex\f[R] (using \f[C]setupinterlinespace\f[R]); repeat for multiple
2912\f[B]\f[CB]layout\f[B]\f[R]
2746\f[B]\f[CB]layout\f[B]\f[R]
2913options for page margins and text arrangement (see ConTeXt Layout);
2747options for page margins and text arrangement (see ConTeXt Layout);
2914repeat for multiple options
2748repeat for multiple options
2916\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]contrastcolor\f[B]\f[R]
2750\f[B]\f[CB]linkcolor\f[B]\f[R], \f[B]\f[CB]contrastcolor\f[B]\f[R]
2917−color for links outside and inside a page, e.g.\ \f[C]red\f[R],
2751+color for links outside and inside a page, e.g.
2918−\f[C]blue\f[R] (see ConTeXt Color)
2752+\f[C]red\f[R], \f[C]blue\f[R] (see ConTeXt Color)
2920\f[B]\f[CB]linkstyle\f[B]\f[R]
2754\f[B]\f[CB]linkstyle\f[B]\f[R]
2921−typeface style for links, e.g.\ \f[C]normal\f[R], \f[C]bold\f[R],
2755+typeface style for links, e.g.
2756+\f[C]normal\f[R], \f[C]bold\f[R], \f[C]slanted\f[R],
2922−\f[C]slanted\f[R], \f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R],
2757+\f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R], \f[C]small\f[R]
2925\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]
2759\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]
2926include list of figures, list of tables
2760include list of figures, list of tables
@@ -2938,13 +2772,16 @@ page number style and location (using \f[C]setuppagenumbering\f[R]);
2938repeat for multiple options
2772repeat for multiple options
2940\f[B]\f[CB]papersize\f[B]\f[R]
2774\f[B]\f[CB]papersize\f[B]\f[R]
2941−paper size, e.g.\ \f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R]
2776+\f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R] (see ConTeXt Paper
2942−(see ConTeXt Paper Setup); repeat for multiple options
2777+Setup); repeat for multiple options
2944\f[B]\f[CB]pdfa\f[B]\f[R]
2779\f[B]\f[CB]pdfa\f[B]\f[R]
2945adds to the preamble the setup necessary to generate PDF/A of the type
2780adds to the preamble the setup necessary to generate PDF/A of the type
2946−specified, e.g.\ \f[C]1a:2005\f[R], \f[C]2a\f[R].
2782+\f[C]1a:2005\f[R], \f[C]2a\f[R].
2783+If no type is specified (i.e.
2947−If no type is specified (i.e.\ the value is set to True, by e.g.
2784+the value is set to True, by e.g.
2948\f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML metadata
2785\f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML metadata
2949block), \f[C]1b:2005\f[R] will be used as default, for reasons of
2786block), \f[C]1b:2005\f[R] will be used as default, for reasons of
2950backwards compatibility.
2787backwards compatibility.
@@ -2959,7 +2796,8 @@ See also ConTeXt PDFA for more details.
2960\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]
2797\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]
2961when used in conjunction with \f[C]pdfa\f[R], specifies the ICC profile
2798when used in conjunction with \f[C]pdfa\f[R], specifies the ICC profile
2962−to use in the PDF, e.g.\ \f[C]default.cmyk\f[R].
2799+to use in the PDF, e.g.
2800+\f[C]default.cmyk\f[R].
2963If left unspecified, \f[C]sRGB.icc\f[R] is used as default.
2801If left unspecified, \f[C]sRGB.icc\f[R] is used as default.
2964May be repeated to include multiple profiles.
2802May be repeated to include multiple profiles.
2965Note that the profiles have to be available on the system.
2803Note that the profiles have to be available on the system.
@@ -2967,17 +2805,17 @@ They can be obtained from ConTeXt ICC Profiles.
2968\f[B]\f[CB]pdfaintent\f[B]\f[R]
2806\f[B]\f[CB]pdfaintent\f[B]\f[R]
2969when used in conjunction with \f[C]pdfa\f[R], specifies the output
2807when used in conjunction with \f[C]pdfa\f[R], specifies the output
2970−intent for the colors,
2808+intent for the colors, e.g.
2971−e.g.\ \f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If
2809+\f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If left
2972−left unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.
2810+unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.
2974\f[B]\f[CB]toc\f[B]\f[R]
2812\f[B]\f[CB]toc\f[B]\f[R]
2975include table of contents (can also be set using
2813include table of contents (can also be set using
2976\f[C]--toc/--table-of-contents\f[R])
2814\f[C]--toc/--table-of-contents\f[R])
2978\f[B]\f[CB]whitespace\f[B]\f[R]
2816\f[B]\f[CB]whitespace\f[B]\f[R]
2979−spacing between paragraphs, e.g.\ \f[C]none\f[R], \f[C]small\f[R] (using
2817+spacing between paragraphs, e.g.
2980−\f[C]setupwhitespace\f[R])
2818+\f[C]none\f[R], \f[C]small\f[R] (using \f[C]setupwhitespace\f[R])
2982\f[B]\f[CB]includesource\f[B]\f[R]
2820\f[B]\f[CB]includesource\f[B]\f[R]
2983include all source documents as file attachments in the PDF file
2821include all source documents as file attachments in the PDF file
@@ -3015,16 +2853,20 @@ section number in man pages
3015.SS Variables for ms
2853.SS Variables for ms
3017\f[B]\f[CB]fontfamily\f[B]\f[R]
2855\f[B]\f[CB]fontfamily\f[B]\f[R]
3018−font family (e.g.\ \f[C]T\f[R] or \f[C]P\f[R])
2856+font family (e.g.
2857+\f[C]T\f[R] or \f[C]P\f[R])
3020\f[B]\f[CB]indent\f[B]\f[R]
2859\f[B]\f[CB]indent\f[B]\f[R]
3021−paragraph indent (e.g.\ \f[C]2m\f[R])
2860+paragraph indent (e.g.
3023\f[B]\f[CB]lineheight\f[B]\f[R]
2863\f[B]\f[CB]lineheight\f[B]\f[R]
3024−line height (e.g.\ \f[C]12p\f[R])
2864+line height (e.g.
3026\f[B]\f[CB]pointsize\f[B]\f[R]
2867\f[B]\f[CB]pointsize\f[B]\f[R]
3027−point size (e.g.\ \f[C]10p\f[R])
2868+point size (e.g.
3028.SS Variables set automatically
2870.SS Variables set automatically
3030Pandoc sets these variables automatically in response to options or
2872Pandoc sets these variables automatically in response to options or
@@ -3040,9 +2882,10 @@ in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,
3040s5, slideous, slidy).
2882s5, slideous, slidy).
3041The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],
2883The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],
3042\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),
2884\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),
2885+\f[C]dd MM yyyy\f[R] (e.g.
3043−\f[C]dd MM yyyy\f[R] (e.g.\ either \f[C]02 Apr 2018\f[R] or
2886+either \f[C]02 Apr 2018\f[R] or \f[C]02 April 2018\f[R]),
3044−\f[C]02 April 2018\f[R]), \f[C]MM dd, yyyy\f[R]
2887+\f[C]MM dd, yyyy\f[R] (e.g.
3045−(e.g.\ \f[C]Apr. 02, 2018\f[R] or
2888+\f[C]Apr. 02, 2018\f[R] or
3046\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,
2889\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,
3047\f[C]201804\f[R] or \f[C]2018\f[R]).
2890\f[C]201804\f[R] or \f[C]2018\f[R]).
@@ -3059,7 +2902,7 @@ contents specified by \f[C]-A/--include-after-body\f[R] (may have
3059multiple values)
2902multiple values)
3061\f[B]\f[CB]meta-json\f[B]\f[R]
2904\f[B]\f[CB]meta-json\f[B]\f[R]
3062−JSON representation of all of the document\[cq]s metadata.
2905+JSON representation of all of the document\[aq]s metadata.
3063Field values are transformed to the selected output format.
2906Field values are transformed to the selected output format.
3065\f[B]\f[CB]numbersections\f[B]\f[R]
2908\f[B]\f[CB]numbersections\f[B]\f[R]
@@ -3087,7 +2930,8 @@ $endif$
3087Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the
2930Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the
3088terminal.
2931terminal.
3090−If you need absolute paths, use e.g.\ \f[C]$curdir$/$sourcefile$\f[R].
2933+If you need absolute paths, use e.g.
2934+\f[C]$curdir$/$sourcefile$\f[R].
3093\f[B]\f[CB]curdir\f[B]\f[R]
2937\f[B]\f[CB]curdir\f[B]\f[R]
@@ -3108,12 +2952,12 @@ An extension can be enabled by adding \f[C]+EXTENSION\f[R] to the format
3108name and disabled by adding \f[C]-EXTENSION\f[R].
2952name and disabled by adding \f[C]-EXTENSION\f[R].
3109For example, \f[C]--from markdown_strict+footnotes\f[R] is strict
2953For example, \f[C]--from markdown_strict+footnotes\f[R] is strict
3110Markdown with footnotes enabled, while
2954Markdown with footnotes enabled, while
3111−\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[cq]s Markdown
2955+\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[aq]s Markdown
3112without footnotes or pipe tables.
2956without footnotes or pipe tables.
3114The markdown reader and writer make by far the most use of extensions.
2958The markdown reader and writer make by far the most use of extensions.
3115Extensions only used by them are therefore covered in the section
2959Extensions only used by them are therefore covered in the section
3116−Pandoc\[cq]s Markdown below (See Markdown variants for
2960+Pandoc\[aq]s Markdown below (See Markdown variants for
3117\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions
2961\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions
3118that also work for other formats are covered.
2962that also work for other formats are covered.
@@ -3126,7 +2970,7 @@ Markdown cells in Jupyter notebooks (as do command-line options like
3126Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,
2970Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,
3127\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.
2971\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.
3128Nonbreaking spaces are inserted after certain abbreviations, such as
2972Nonbreaking spaces are inserted after certain abbreviations, such as
3129−\[lq]Mr.\[rq]
2973+\[dq]Mr.\[dq]
3131This extension can be enabled/disabled for the following formats:
2975This extension can be enabled/disabled for the following formats:
@@ -3276,7 +3120,7 @@ letters are omitted.
3276.SS Extension: \f[C]gfm_auto_identifiers\f[R]
3120.SS Extension: \f[C]gfm_auto_identifiers\f[R]
3278Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to
3122Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to
3279−GitHub\[cq]s method.
3123+GitHub\[aq]s method.
3280Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to
3124Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to
3281lowercase characters, and punctuation characters other than \f[C]-\f[R]
3125lowercase characters, and punctuation characters other than \f[C]-\f[R]
3282and \f[C]_\f[R] are removed.
3126and \f[C]_\f[R] are removed.
@@ -3286,7 +3130,7 @@ Emojis are replaced by their names.
3286The extensions \f[C]tex_math_dollars\f[R],
3130The extensions \f[C]tex_math_dollars\f[R],
3287\f[C]tex_math_single_backslash\f[R], and
3131\f[C]tex_math_single_backslash\f[R], and
3288\f[C]tex_math_double_backslash\f[R] are described in the section about
3132\f[C]tex_math_double_backslash\f[R] are described in the section about
3289−Pandoc\[cq]s Markdown.
3133+Pandoc\[aq]s Markdown.
3291However, they can also be used with HTML input.
3135However, they can also be used with HTML input.
3292This is handy for reading web pages formatted using MathJax, for
3136This is handy for reading web pages formatted using MathJax, for
@@ -3294,10 +3138,10 @@ example.
3294.SS Raw HTML/TeX
3138.SS Raw HTML/TeX
3296The following extensions are described in more detail in their
3140The following extensions are described in more detail in their
3297−respective sections of Pandoc\[cq]s Markdown:
3141+respective sections of Pandoc\[aq]s Markdown:
3298.IP \[bu] 2
3142.IP \[bu] 2
3299\f[C]raw_html\f[R] allows HTML elements which are not representable in
3143\f[C]raw_html\f[R] allows HTML elements which are not representable in
3300−pandoc\[cq]s AST to be parsed as raw HTML.
3144+pandoc\[aq]s AST to be parsed as raw HTML.
3301By default, this is disabled for HTML input.
3145By default, this is disabled for HTML input.
3302.IP \[bu] 2
3146.IP \[bu] 2
3303\f[C]raw_tex\f[R] allows raw LaTeX, TeX, and ConTeXt to be included in a
3147\f[C]raw_tex\f[R] allows raw LaTeX, TeX, and ConTeXt to be included in a
@@ -3307,8 +3151,9 @@ addition to \f[C]markdown\f[R]):
3309input formats
3153input formats
3310−\f[C]latex\f[R], \f[C]textile\f[R], \f[C]html\f[R] (environments,
3154+\f[C]latex\f[R], \f[C]org\f[R], \f[C]textile\f[R], \f[C]html\f[R]
3311−\f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only), \f[C]ipynb\f[R]
3155+(environments, \f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only),
3313output formats
3158output formats
3314\f[C]textile\f[R], \f[C]commonmark\f[R]
3159\f[C]textile\f[R], \f[C]commonmark\f[R]
@@ -3319,7 +3164,7 @@ with mime type \f[C]text/html\f[R] in output cells.
3319Since the \f[C]ipynb\f[R] reader attempts to preserve the richest
3164Since the \f[C]ipynb\f[R] reader attempts to preserve the richest
3320possible outputs when several options are given, you will get best
3165possible outputs when several options are given, you will get best
3321results if you disable \f[C]raw_html\f[R] and \f[C]raw_tex\f[R] when
3166results if you disable \f[C]raw_html\f[R] and \f[C]raw_tex\f[R] when
3322−converting to formats like \f[C]docx\f[R] which don\[cq]t allow raw
3167+converting to formats like \f[C]docx\f[R] which don\[aq]t allow raw
3323\f[C]html\f[R] or \f[C]tex\f[R].
3168\f[C]html\f[R] or \f[C]tex\f[R].
3325.IP \[bu] 2
3170.IP \[bu] 2
@@ -3353,22 +3198,23 @@ the formats above, pandoc will treat the document as literate Haskell
3354This means that
3199This means that
3355.IP \[bu] 2
3200.IP \[bu] 2
3356−In Markdown input, \[lq]bird track\[rq] sections will be parsed as
3201+In Markdown input, \[dq]bird track\[dq] sections will be parsed as
3357Haskell code rather than block quotations.
3202Haskell code rather than block quotations.
3358Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]
3203Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]
3359will also be treated as Haskell code.
3204will also be treated as Haskell code.
3360−For ATX-style headings the character `=' will be used instead of `#'.
3205+For ATX-style headings the character \[aq]=\[aq] will be used instead of
3361.IP \[bu] 2
3207.IP \[bu] 2
3362In Markdown output, code blocks with classes \f[C]haskell\f[R] and
3208In Markdown output, code blocks with classes \f[C]haskell\f[R] and
3363\f[C]literate\f[R] will be rendered using bird tracks, and block
3209\f[C]literate\f[R] will be rendered using bird tracks, and block
3364quotations will be indented one space, so they will not be treated as
3210quotations will be indented one space, so they will not be treated as
3365Haskell code.
3211Haskell code.
3366In addition, headings will be rendered setext-style (with underlines)
3212In addition, headings will be rendered setext-style (with underlines)
3367−rather than ATX-style (with `#' characters).
3213+rather than ATX-style (with \[aq]#\[aq] characters).
3368−(This is because ghc treats `#' characters in column 1 as introducing
3214+(This is because ghc treats \[aq]#\[aq] characters in column 1 as
3369−line numbers.)
3215+introducing line numbers.)
3370.IP \[bu] 2
3216.IP \[bu] 2
3371−In restructured text input, \[lq]bird track\[rq] sections will be parsed
3217+In restructured text input, \[dq]bird track\[dq] sections will be parsed
3372as Haskell code.
3218as Haskell code.
3373.IP \[bu] 2
3219.IP \[bu] 2
3374In restructured text output, code blocks with class \f[C]haskell\f[R]
3220In restructured text output, code blocks with class \f[C]haskell\f[R]
@@ -3404,8 +3250,9 @@ writes HTML with the Haskell code in bird tracks, so it can be copied
3404and pasted as literate Haskell source.
3250and pasted as literate Haskell source.
3406Note that GHC expects the bird tracks in the first column, so indented
3252Note that GHC expects the bird tracks in the first column, so indented
3253+literate code blocks (e.g.
3407−literate code blocks (e.g.\ inside an itemized environment) will not be
3254+inside an itemized environment) will not be picked up by the Haskell
3408−picked up by the Haskell compiler.
3255+compiler.
3409.SS Other extensions
3256.SS Other extensions
3410.SS Extension: \f[C]empty_paragraphs\f[R]
3257.SS Extension: \f[C]empty_paragraphs\f[R]
@@ -3428,44 +3275,7 @@ This extension can be enabled/disabled for the following formats:
3429output formats
3276output formats
3430\f[C]odt\f[R], \f[C]opendocument\f[R]
3277\f[C]odt\f[R], \f[C]opendocument\f[R]
3431−.SS Extension: \f[C]xrefs_name\f[R]
3278+.SS Extension: \f[C]styles\f[R] {#ext-styles}
3433−Links to headings, figures and tables inside the document are
3434−substituted with cross-references that will use the name or caption of
3435−the referenced item.
3436−The original link text is replaced once the generated document is
3438−This extension can be combined with \f[C]xrefs_number\f[R] in which case
3439−numbers will appear before the name.
3441−Text in cross-references is only made consistent with the referenced
3442−item once the document has been refreshed.
3444−This extension can be enabled/disabled for the following formats:
3447−\f[C]odt\f[R], \f[C]opendocument\f[R]
3448−.SS Extension: \f[C]xrefs_number\f[R]
3450−Links to headings, figures and tables inside the document are
3451−substituted with cross-references that will use the number of the
3453−The original link text is discarded.
3454−This extension can be combined with \f[C]xrefs_name\f[R] in which case
3455−the name or caption numbers will appear after the number.
3457−For the \f[C]xrefs_number\f[R] to be useful heading numbers must be
3458−enabled in the generated document, also table and figure captions must
3459−be enabled using for example the \f[C]native_numbering\f[R] extension.
3461−Numbers in cross-references are only visible in the final document once
3462−it has been refreshed.
3464−This extension can be enabled/disabled for the following formats:
3467−\f[C]odt\f[R], \f[C]opendocument\f[R]
3468−.SS Extension: \f[C]styles\f[R]
3470When converting from docx, read all docx styles as divs (for paragraph
3280When converting from docx, read all docx styles as divs (for paragraph
3471styles) and spans (for character styles) regardless of whether pandoc
3281styles) and spans (for character styles) regardless of whether pandoc
@@ -3484,28 +3294,22 @@ to Emacs Muse markup.
3484In the \f[C]ipynb\f[R] input format, this causes Markdown cells to be
3294In the \f[C]ipynb\f[R] input format, this causes Markdown cells to be
3485included as raw Markdown blocks (allowing lossless round-tripping)
3295included as raw Markdown blocks (allowing lossless round-tripping)
3486rather than being parsed.
3296rather than being parsed.
3487−Use this only when you are targeting \f[C]ipynb\f[R] or a markdown-based
3297+Use this only when you are targetting \f[C]ipynb\f[R] or a
3488−output format.
3298+markdown-based output format.
3489.SS Extension: \f[C]citations\f[R]
3299.SS Extension: \f[C]citations\f[R]
3491−Some aspects of Pandoc\[cq]s Markdown citation syntax are also accepted
3301+Some aspects of Pandoc\[aq]s Markdown citation syntax are also accepted
3492in \f[C]org\f[R] input.
3302in \f[C]org\f[R] input.
3493−.SS Extension: \f[C]element_citations\f[R]
3495−In the \f[C]jats\f[R] output formats, this causes reference items to be
3496−replaced with \f[C]<element-citation>\f[R] elements.
3497−These elements are not influenced by CSL styles, but all information on
3498−the item is included in tags.
3499.SS Extension: \f[C]ntb\f[R]
3303.SS Extension: \f[C]ntb\f[R]
3501In the \f[C]context\f[R] output format this enables the use of Natural
3305In the \f[C]context\f[R] output format this enables the use of Natural
3502Tables (TABLE) instead of the default Extreme Tables (xtables).
3306Tables (TABLE) instead of the default Extreme Tables (xtables).
3503Natural tables allow more fine-grained global customization but come at
3307Natural tables allow more fine-grained global customization but come at
3504a performance penalty compared to extreme tables.
3308a performance penalty compared to extreme tables.
3505−.SH PANDOC\[cq]S MARKDOWN
3309+.SH PANDOC\[aq]S MARKDOWN
3507Pandoc understands an extended and slightly revised version of John
3311Pandoc understands an extended and slightly revised version of John
3508−Gruber\[cq]s Markdown syntax.
3312+Gruber\[aq]s Markdown syntax.
3509This document explains the syntax, noting differences from standard
3313This document explains the syntax, noting differences from standard
3510Markdown.
3314Markdown.
3511Except where noted, these differences can be suppressed by using the
3315Except where noted, these differences can be suppressed by using the
@@ -3522,15 +3326,15 @@ easy to read:
3524A Markdown-formatted document should be publishable as-is, as plain
3328A Markdown-formatted document should be publishable as-is, as plain
3525−text, without looking like it\[cq]s been marked up with tags or
3329+text, without looking like it\[aq]s been marked up with tags or
3526formatting instructions.
3330formatting instructions.
3527−\[en] John Gruber
3331+-- John Gruber
3530−This principle has guided pandoc\[cq]s decisions in finding syntax for
3334+This principle has guided pandoc\[aq]s decisions in finding syntax for
3531tables, footnotes, and other extensions.
3335tables, footnotes, and other extensions.
3533−There is, however, one respect in which pandoc\[cq]s aims are different
3337+There is, however, one respect in which pandoc\[aq]s aims are different
3534from the original aims of Markdown.
3338from the original aims of Markdown.
3535Whereas Markdown was originally designed with HTML generation in mind,
3339Whereas Markdown was originally designed with HTML generation in mind,
3536pandoc is designed for multiple output formats.
3340pandoc is designed for multiple output formats.
@@ -3555,7 +3359,7 @@ a hard line break, since trailing spaces in the cells are ignored.
3555There are two kinds of headings: Setext and ATX.
3359There are two kinds of headings: Setext and ATX.
3556.SS Setext-style headings
3360.SS Setext-style headings
3558−A setext-style heading is a line of text \[lq]underlined\[rq] with a row
3362+A setext-style heading is a line of text \[dq]underlined\[dq] with a row
3559of \f[C]=\f[R] signs (for a level-one heading) or \f[C]-\f[R] signs (for
3363of \f[C]=\f[R] signs (for a level-one heading) or \f[C]-\f[R] signs (for
3560a level-two heading):
3364a level-two heading):
@@ -3646,7 +3450,7 @@ My other heading {#foo}
3646(This syntax is compatible with PHP Markdown Extra.)
3450(This syntax is compatible with PHP Markdown Extra.)
3648Note that although this syntax allows assignment of classes and
3452Note that although this syntax allows assignment of classes and
3649−key/value attributes, writers generally don\[cq]t use all of this
3453+key/value attributes, writers generally don\[aq]t use all of this
3650information.
3454information.
3651Identifiers, classes, and key/value attributes are used in HTML and
3455Identifiers, classes, and key/value attributes are used in HTML and
3652HTML-based formats such as EPUB and slidy.
3456HTML-based formats such as EPUB and slidy.
@@ -3761,7 +3565,7 @@ indented more than three spaces.)
3764−A \[lq]lazy\[rq] form, which requires the \f[C]>\f[R] character only on
3568+A \[dq]lazy\[dq] form, which requires the \f[C]>\f[R] character only on
3765the first line of each block, is also allowed:
3569the first line of each block, is also allowed:
@@ -3979,9 +3783,6 @@ begin with a space.
3982−Inline formatting (such as emphasis) is allowed in the content, but not
3983−block-level formatting (such as block quotes or lists).
3985This syntax is borrowed from reStructuredText.
3786This syntax is borrowed from reStructuredText.
3986.SS Lists
3787.SS Lists
3987.SS Bullet lists
3788.SS Bullet lists
@@ -3999,8 +3800,8 @@ Here is a simple example:
4002−This will produce a \[lq]compact\[rq] list.
3803+This will produce a \[dq]compact\[dq] list.
4003−If you want a \[lq]loose\[rq] list, in which each item is formatted as a
3804+If you want a \[dq]loose\[dq] list, in which each item is formatted as a
4004paragraph, put spaces between the items:
3805paragraph, put spaces between the items:
@@ -4028,7 +3829,7 @@ List items look best if subsequent lines are flush with the first line
4031−But Markdown also allows a \[lq]lazy\[rq] format:
3832+But Markdown also allows a \[dq]lazy\[dq] format:
@@ -4091,7 +3892,7 @@ character after the list marker of the containing list item.
4093As noted above, Markdown allows you to write list items
3894As noted above, Markdown allows you to write list items
4094−\[lq]lazily,\[rq] instead of indenting continuation lines.
3895+\[dq]lazily,\[dq] instead of indenting continuation lines.
4095However, if there are multiple paragraphs or other blocks in a list
3896However, if there are multiple paragraphs or other blocks in a list
4096item, the first line of each must be indented.
3897item, the first line of each must be indented.
@@ -4145,8 +3946,8 @@ They must be separated from the text that follows by at least one space,
4145and, if the list marker is a capital letter with a period, by at least
3946and, if the list marker is a capital letter with a period, by at least
4146two spaces.
3947two spaces.
4148−The \f[C]fancy_lists\f[R] extension also allows `\f[C]#\f[R]' to be used
3949+The \f[C]fancy_lists\f[R] extension also allows \[aq]\f[C]#\f[R]\[aq] to
4149−as an ordered list marker in place of a numeral:
3950+be used as an ordered list marker in place of a numeral:
@@ -4239,7 +4040,7 @@ one or more block elements (paragraph, code block, list, etc.), each
4239indented four spaces or one tab stop.
4040indented four spaces or one tab stop.
4240The body of the definition (including the first line, aside from the
4041The body of the definition (including the first line, aside from the
4241colon or tilde) should be indented four spaces.
4042colon or tilde) should be indented four spaces.
4242−However, as with other Markdown lists, you can \[lq]lazily\[rq] omit
4043+However, as with other Markdown lists, you can \[dq]lazily\[dq] omit
4243indentation except at the beginning of a paragraph or other block
4044indentation except at the beginning of a paragraph or other block
@@ -4273,16 +4074,16 @@ Term 2
4275Note that space between items in a definition list is required.
4076Note that space between items in a definition list is required.
4276−(A variant that loosens this requirement, but disallows \[lq]lazy\[rq]
4077+(A variant that loosens this requirement, but disallows \[dq]lazy\[dq]
4277hard wrapping, can be activated with \f[C]compact_definition_lists\f[R]:
4078hard wrapping, can be activated with \f[C]compact_definition_lists\f[R]:
4278−see Non-default extensions, below.)
4079+see Non-pandoc extensions, below.)
4279.SS Numbered example lists
4080.SS Numbered example lists
4280.SS Extension: \f[C]example_lists\f[R]
4081.SS Extension: \f[C]example_lists\f[R]
4282The special list marker \f[C]\[at]\f[R] can be used for sequentially
4083The special list marker \f[C]\[at]\f[R] can be used for sequentially
4283numbered examples.
4084numbered examples.
4284−The first list item with a \f[C]\[at]\f[R] marker will be numbered `1',
4085+The first list item with a \f[C]\[at]\f[R] marker will be numbered
4285−the next `2', and so on, throughout the document.
4086+\[aq]1\[aq], the next \[aq]2\[aq], and so on, throughout the document.
4286The numbered examples need not occur in a single list; each new list
4087The numbered examples need not occur in a single list; each new list
4287using \f[C]\[at]\f[R] will take up where the last stopped.
4088using \f[C]\[at]\f[R] will take up where the last stopped.
4288So, for example:
4089So, for example:
@@ -4318,6 +4119,39 @@ That is, example lists always behave as if the \f[C]four_space_rule\f[R]
4318extension is set.
4119extension is set.
4319This is because example labels tend to be long, and indenting content to
4120This is because example labels tend to be long, and indenting content to
4320the first non-space character after the label would be awkward.
4121the first non-space character after the label would be awkward.
4122+.SS Compact and loose lists
4124+Pandoc behaves differently from \f[C]Markdown.pl\f[R] on some \[dq]edge
4125+cases\[dq] involving lists.
4126+Consider this source:
4140+Pandoc transforms this into a \[dq]compact list\[dq] (with no
4141+\f[C]<p>\f[R] tags around \[dq]First\[dq], \[dq]Second\[dq], or
4142+\[dq]Third\[dq]), while Markdown puts \f[C]<p>\f[R] tags around
4143+\[dq]Second\[dq] and \[dq]Third\[dq] (but not \[dq]First\[dq]), because
4144+of the blank space around \[dq]Third\[dq].
4145+Pandoc follows a simple rule: if the text is followed by a blank line,
4146+it is treated as a paragraph.
4147+Since \[dq]Second\[dq] is followed by a list, and not a blank line, it
4148+isn\[aq]t treated as a paragraph.
4149+The fact that the list is followed by a blank line is irrelevant.
4150+(Note: Pandoc works this way even when the \f[C]markdown_strict\f[R]
4151+format is specified.
4152+This behavior is consistent with the official Markdown syntax
4153+description, even though it is different from that of
4154+\f[C]Markdown.pl\f[R].)
4321.SS Ending a list
4155.SS Ending a list
4323What if you want to put an indented code block after a list?
4157What if you want to put an indented code block after a list?
@@ -4335,8 +4169,8 @@ Trouble! Here pandoc (like other Markdown implementations) will treat
4335\f[C]{ my code block }\f[R] as the second paragraph of item two, and not
4169\f[C]{ my code block }\f[R] as the second paragraph of item two, and not
4336as a code block.
4170as a code block.
4338−To \[lq]cut off\[rq] the list after item two, you can insert some
4172+To \[dq]cut off\[dq] the list after item two, you can insert some
4339−non-indented content, like an HTML comment, which won\[cq]t produce
4173+non-indented content, like an HTML comment, which won\[aq]t produce
4340visible output in any format:
4174visible output in any format:
@@ -4532,7 +4366,7 @@ can be omitted for a headerless table.
4532The cells of grid tables may contain arbitrary block elements (multiple
4366The cells of grid tables may contain arbitrary block elements (multiple
4533paragraphs, code blocks, lists, etc.).
4367paragraphs, code blocks, lists, etc.).
4534Cells that span multiple columns or rows are not supported.
4368Cells that span multiple columns or rows are not supported.
4535−Grid tables can be created easily using Emacs\[cq] table-mode
4369+Grid tables can be created easily using Emacs\[aq] table-mode
4536(\f[C]M-x table-insert\f[R]).
4370(\f[C]M-x table-insert\f[R]).
4538Alignments can be specified as with pipe tables, by putting colons at
4372Alignments can be specified as with pipe tables, by putting colons at
@@ -4616,7 +4450,7 @@ lines are wider than column width, then cell contents will not be
4616wrapped, and the cells will be sized to their contents.
4450wrapped, and the cells will be sized to their contents.
4618Note: pandoc also recognizes pipe tables of the following form, as can
4452Note: pandoc also recognizes pipe tables of the following form, as can
4619−be produced by Emacs\[cq] orgtbl-mode:
4453+be produced by Emacs\[aq] orgtbl-mode:
@@ -4629,7 +4463,7 @@ be produced by Emacs\[cq] orgtbl-mode:
4630The difference is that \f[C]+\f[R] is used instead of \f[C]|\f[R].
4464The difference is that \f[C]+\f[R] is used instead of \f[C]|\f[R].
4631Other orgtbl features are not supported.
4465Other orgtbl features are not supported.
4632−In particular, to get non-default column alignment, you\[cq]ll need to
4466+In particular, to get non-default column alignment, you\[aq]ll need to
4633add colons as above.
4467add colons as above.
4634.SS Metadata blocks
4468.SS Metadata blocks
4635.SS Extension: \f[C]pandoc_title_block\f[R]
4469.SS Extension: \f[C]pandoc_title_block\f[R]
@@ -4707,13 +4541,13 @@ All three metadata fields may contain standard inline formatting
4708Title blocks will always be parsed, but they will affect the output only
4542Title blocks will always be parsed, but they will affect the output only
4709when the \f[C]--standalone\f[R] (\f[C]-s\f[R]) option is chosen.
4543when the \f[C]--standalone\f[R] (\f[C]-s\f[R]) option is chosen.
4710−In HTML output, titles will appear twice: once in the document head
4544+In HTML output, titles will appear twice: once in the document head --
4711−\[en] this is the title that will appear at the top of the window in a
4545+this is the title that will appear at the top of the window in a browser
4712−browser \[en] and once at the beginning of the document body.
4546+-- and once at the beginning of the document body.
4713The title in the document head can have an optional prefix attached
4547The title in the document head can have an optional prefix attached
4714(\f[C]--title-prefix\f[R] or \f[C]-T\f[R] option).
4548(\f[C]--title-prefix\f[R] or \f[C]-T\f[R] option).
4715The title in the body appears as an H1 element with class
4549The title in the body appears as an H1 element with class
4716−\[lq]title\[rq], so it can be suppressed or reformatted with CSS.
4550+\[dq]title\[dq], so it can be suppressed or reformatted with CSS.
4717If a title prefix is specified with \f[C]-T\f[R] and no title block
4551If a title prefix is specified with \f[C]-T\f[R] and no title block
4718appears in the document, the title prefix will be used by itself as the
4552appears in the document, the title prefix will be used by itself as the
4719HTML title.
4553HTML title.
@@ -4742,7 +4576,7 @@ will yield a man page with the title \f[C]PANDOC\f[R] and section 1.
4745−will also have \[lq]Pandoc User Manuals\[rq] in the footer.
4579+will also have \[dq]Pandoc User Manuals\[dq] in the footer.
@@ -4750,7 +4584,7 @@ will also have \[lq]Pandoc User Manuals\[rq] in the footer.
4753−will also have \[lq]Version 4.0\[rq] in the header.
4587+will also have \[dq]Version 4.0\[dq] in the header.
4754.SS Extension: \f[C]yaml_metadata_block\f[R]
4588.SS Extension: \f[C]yaml_metadata_block\f[R]
4756A YAML metadata block is a valid YAML object, delimited by a line of
4590A YAML metadata block is a valid YAML object, delimited by a line of
@@ -4796,9 +4630,7 @@ All of the metadata will appear in a single block at the beginning of
4796the document.
4630the document.
4798Note that YAML escaping rules must be followed.
4632Note that YAML escaping rules must be followed.
4799−Thus, for example, if a title contains a colon, it must be quoted, and
4633+Thus, for example, if a title contains a colon, it must be quoted.
4800−if it contains a backslash escape, then it must be ensured that it is
4801−not treated as a YAML escape sequence.
4802The pipe character (\f[C]|\f[R]) can be used to begin an indented block
4634The pipe character (\f[C]|\f[R]) can be used to begin an indented block
4803that will be interpreted literally, without need for escaping.
4635that will be interpreted literally, without need for escaping.
4804This form is necessary when the field contains blank lines or
4636This form is necessary when the field contains blank lines or
@@ -4820,13 +4652,6 @@ abstract: |
4823−The literal block after the \f[C]|\f[R] must be indented relative to the
4824−line containing the \f[C]|\f[R].
4825−If it is not, the YAML will be invalid and pandoc will not interpret it
4827−For an overview of the complex rules governing YAML, see the Wikipedia
4828−entry on YAML syntax.
4830Template variables will be set automatically from the metadata.
4655Template variables will be set automatically from the metadata.
4831Thus, for example, in writing HTML, the variable \f[C]abstract\f[R] will
4656Thus, for example, in writing HTML, the variable \f[C]abstract\f[R] will
4832be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[R]
4657be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[R]
@@ -4875,7 +4700,7 @@ $endfor$
4878−Raw content to include in the document\[cq]s header may be specified
4703+Raw content to include in the document\[aq]s header may be specified
4879using \f[C]header-includes\f[R]; however, it is important to mark up
4704using \f[C]header-includes\f[R]; however, it is important to mark up
4880this content as raw code for a particular output format, using the
4705this content as raw code for a particular output format, using the
4881\f[C]raw_attribute\f[R] extension), or it will be interpreted as
4706\f[C]raw_attribute\f[R] extension), or it will be interpreted as
@@ -4892,21 +4717,6 @@ header-includes:
4892 \[ga]\[ga]\[ga]
4717 \[ga]\[ga]\[ga]
4896−Note: the \f[C]yaml_metadata_block\f[R] extension works with
4897−\f[C]commonmark\f[R] as well as \f[C]markdown\f[R] (and it is enabled by
4898−default in \f[C]gfm\f[R] and \f[C]commonmark_x\f[R]).
4899−However, in these formats the following restrictions apply:
4901−The YAML metadata block must occur at the beginning of the document (and
4902−there can be only one).
4903−If multiple files are given as arguments to pandoc, only the first can
4904−be a YAML metadata block.
4906−The leaf nodes of the YAML structure are parsed in isolation from each
4907−other and from the rest of the document.
4908−So, for example, you can\[cq]t use a reference link in these contexts if
4909−the link definition is somewhere else in the document.
4910.SS Backslash escapes
4720.SS Backslash escapes
4911.SS Extension: \f[C]all_symbols_escapable\f[R]
4721.SS Extension: \f[C]all_symbols_escapable\f[R]
@@ -4937,7 +4747,7 @@ instead of
4940−This rule is easier to remember than standard Markdown\[cq]s rule, which
4750+This rule is easier to remember than standard Markdown\[aq]s rule, which
4941allows only the following characters to be backslash-escaped:
4751allows only the following characters to be backslash-escaped:
@@ -4953,15 +4763,16 @@ A backslash-escaped space is parsed as a nonbreaking space.
4953In TeX output, it will appear as \f[C]\[ti]\f[R].
4763In TeX output, it will appear as \f[C]\[ti]\f[R].
4954In HTML and XML output, it will appear as a literal unicode nonbreaking
4764In HTML and XML output, it will appear as a literal unicode nonbreaking
4955space character (note that it will thus actually look
4765space character (note that it will thus actually look
4956−\[lq]invisible\[rq] in the generated HTML source; you can still use the
4766+\[dq]invisible\[dq] in the generated HTML source; you can still use the
4957\f[C]--ascii\f[R] command-line option to make it appear as an explicit
4767\f[C]--ascii\f[R] command-line option to make it appear as an explicit
4960−A backslash-escaped newline (i.e.\ a backslash occurring at the end of a
4770+A backslash-escaped newline (i.e.
4961−line) is parsed as a hard line break.
4771+a backslash occurring at the end of a line) is parsed as a hard line
4962It will appear in TeX output as \f[C]\[rs]\[rs]\f[R] and in HTML as
4773It will appear in TeX output as \f[C]\[rs]\[rs]\f[R] and in HTML as
4963\f[C]<br />\f[R].
4774\f[C]<br />\f[R].
4964−This is a nice alternative to Markdown\[cq]s \[lq]invisible\[rq] way of
4775+This is a nice alternative to Markdown\[aq]s \[dq]invisible\[dq] way of
4965indicating hard line breaks using two trailing spaces on a line.
4776indicating hard line breaks using two trailing spaces on a line.
4967Backslash escapes do not work in verbatim contexts.
4778Backslash escapes do not work in verbatim contexts.
@@ -5038,8 +4849,8 @@ If the superscripted or subscripted text contains spaces, these spaces
5038must be escaped with backslashes.
4849must be escaped with backslashes.
5039(This is to prevent accidental superscripting and subscripting through
4850(This is to prevent accidental superscripting and subscripting through
5040the ordinary use of \f[C]\[ti]\f[R] and \f[C]\[ha]\f[R], and also bad
4851the ordinary use of \f[C]\[ti]\f[R] and \f[C]\[ha]\f[R], and also bad
5041−interactions with footnotes.) Thus, if you want the letter P with `a
4852+interactions with footnotes.) Thus, if you want the letter P with \[aq]a
5042−cat' in subscripts, use \f[C]P\[ti]a\[rs] cat\[ti]\f[R], not
4853+cat\[aq] in subscripts, use \f[C]P\[ti]a\[rs] cat\[ti]\f[R], not
5043\f[C]P\[ti]a cat\[ti]\f[R].
4854\f[C]P\[ti]a cat\[ti]\f[R].
5044.SS Verbatim
4855.SS Verbatim
@@ -5119,16 +4930,14 @@ The opening \f[C]$\f[R] must have a non-space character immediately to
5119its right, while the closing \f[C]$\f[R] must have a non-space character
4930its right, while the closing \f[C]$\f[R] must have a non-space character
5120immediately to its left, and must not be followed immediately by a
4931immediately to its left, and must not be followed immediately by a
5122−Thus, \f[C]$20,000 and $30,000\f[R] won\[cq]t parse as math.
4933+Thus, \f[C]$20,000 and $30,000\f[R] won\[aq]t parse as math.
5123If for some reason you need to enclose text in literal \f[C]$\f[R]
4934If for some reason you need to enclose text in literal \f[C]$\f[R]
5124−characters, backslash-escape them and they won\[cq]t be treated as math
4935+characters, backslash-escape them and they won\[aq]t be treated as math
5125delimiters.
4936delimiters.
5127For display math, use \f[C]$$\f[R] delimiters.
4938For display math, use \f[C]$$\f[R] delimiters.
5128(In this case, the delimiters may be separated from the formula by
4939(In this case, the delimiters may be separated from the formula by
5129−whitespace.
4940+whitespace.)
5130−However, there can be no blank lines betwen the opening and closing
5131−\f[C]$$\f[R] delimiters.)
5133TeX math will be printed in all output formats.
4942TeX math will be printed in all output formats.
5134How it is rendered depends on the output format:
4943How it is rendered depends on the output format:
@@ -5159,7 +4968,7 @@ Texinfo
5159It will be rendered inside a \f[C]\[at]math\f[R] command.
4968It will be rendered inside a \f[C]\[at]math\f[R] command.
5161roff man, Jira markup
4970roff man, Jira markup
5162−It will be rendered verbatim without \f[C]$\f[R]\[cq]s.
4971+It will be rendered verbatim without \f[C]$\f[R]\[aq]s.
5164MediaWiki, DokuWiki
4973MediaWiki, DokuWiki
5165It will be rendered inside \f[C]<math>\f[R] tags.
4974It will be rendered inside \f[C]<math>\f[R] tags.
@@ -5217,7 +5026,7 @@ Note that even if \f[C]raw_html\f[R] is disabled, tables will be
5217rendered with HTML syntax if they cannot use pipe syntax.
5026rendered with HTML syntax if they cannot use pipe syntax.
5218.SS Extension: \f[C]markdown_in_html_blocks\f[R]
5027.SS Extension: \f[C]markdown_in_html_blocks\f[R]
5220−Standard Markdown allows you to include HTML \[lq]blocks\[rq]: blocks of
5029+Standard Markdown allows you to include HTML \[dq]blocks\[dq]: blocks of
5221HTML between balanced tags that are separated from the surrounding text
5030HTML between balanced tags that are separated from the surrounding text
5222with blank lines, and start and end at the left margin.
5031with blank lines, and start and end at the left margin.
5223Within these blocks, everything is interpreted as HTML, not Markdown; so
5032Within these blocks, everything is interpreted as HTML, not Markdown; so
@@ -5254,9 +5063,8 @@ into
5255whereas \f[C]Markdown.pl\f[R] will preserve it as is.
5064whereas \f[C]Markdown.pl\f[R] will preserve it as is.
5257−There is one exception to this rule: text between \f[C]<script>\f[R],
5066+There is one exception to this rule: text between \f[C]<script>\f[R] and
5258−\f[C]<style>\f[R], and \f[C]<textarea>\f[R] tags is not interpreted as
5067+\f[C]<style>\f[R] tags is not interpreted as Markdown.
5261This departure from standard Markdown should make it easier to mix
5069This departure from standard Markdown should make it easier to mix
5262Markdown with HTML block elements.
5070Markdown with HTML block elements.
@@ -5556,7 +5364,7 @@ slide shows and EPUB), LaTeX, and ConTeXt.
5557A link immediately preceded by a \f[C]!\f[R] will be treated as an
5365A link immediately preceded by a \f[C]!\f[R] will be treated as an
5559−The link text will be used as the image\[cq]s alt text:
5367+The link text will be used as the image\[aq]s alt text:
@@ -5571,7 +5379,7 @@ The link text will be used as the image\[cq]s alt text:
5572An image with nonempty alt text, occurring by itself in a paragraph,
5380An image with nonempty alt text, occurring by itself in a paragraph,
5573will be rendered as a figure with a caption.
5381will be rendered as a figure with a caption.
5574−The image\[cq]s alt text will be used as the caption.
5382+The image\[aq]s alt text will be used as the caption.
@@ -5580,8 +5388,9 @@ The image\[cq]s alt text will be used as the caption.
5582How this is rendered depends on the output format.
5390How this is rendered depends on the output format.
5391+Some output formats (e.g.
5583−Some output formats (e.g.\ RTF) do not yet support figures.
5392+RTF) do not yet support figures.
5584−In those formats, you\[cq]ll just get an image in a paragraph by itself,
5393+In those formats, you\[aq]ll just get an image in a paragraph by itself,
5585with no caption.
5394with no caption.
5587If you just want a regular inline image, just make sure it is not the
5396If you just want a regular inline image, just make sure it is not the
@@ -5652,7 +5461,7 @@ HTML:
5652.IP \[bu] 2
5461.IP \[bu] 2
5654\f[C]\[rs]includegraphics[width=0.5\[rs]textwidth,height=\[rs]textheight]{file.jpg}\f[R]
5463\f[C]\[rs]includegraphics[width=0.5\[rs]textwidth,height=\[rs]textheight]{file.jpg}\f[R]
5655−(If you\[cq]re using a custom template, you need to configure
5464+(If you\[aq]re using a custom template, you need to configure
5656\f[C]graphicx\f[R] as in the default template.)
5465\f[C]graphicx\f[R] as in the default template.)
5657.IP \[bu] 2
5466.IP \[bu] 2
@@ -5735,7 +5544,7 @@ immediately by attributes:
5735.SS Footnotes
5544.SS Footnotes
5736.SS Extension: \f[C]footnotes\f[R]
5545.SS Extension: \f[C]footnotes\f[R]
5738−Pandoc\[cq]s Markdown allows footnotes, using the following syntax:
5547+Pandoc\[aq]s Markdown allows footnotes, using the following syntax:
@@ -5784,73 +5593,198 @@ note.]
5786Inline and regular footnotes may be mixed freely.
5595Inline and regular footnotes may be mixed freely.
5787−.SS Citation syntax
5596+.SS Citations
5788.SS Extension: \f[C]citations\f[R]
5597.SS Extension: \f[C]citations\f[R]
5790−To cite a bibliographic item with an identifier foo, use the syntax
5599+Using an external filter, \f[C]pandoc-citeproc\f[R], pandoc can
5791−\f[C]\[at]foo\f[R].
5600+automatically generate citations and a bibliography in a number of
5792−Normal citations should be included in square brackets, with semicolons
5601+styles.
5793−separating distinct items:
5602+Basic usage is
5797−Blah blah [\[at]doe99; \[at]smith2000; \[at]smith2004].
5606+pandoc --filter pandoc-citeproc myinput.txt
5801−How this is rendered depends on the citation style.
5610+In order to use this feature, you will need to specify a bibliography
5802−In an author-date style, it might render as
5611+file using the \f[C]bibliography\f[R] metadata field in a YAML metadata
5803−.IP
5612+section, or \f[C]--bibliography\f[R] command line argument.
5804−.nf
5613+You can supply multiple \f[C]--bibliography\f[R] arguments or set
5805−\f[C]
5614+\f[C]bibliography\f[R] metadata field to YAML array, if you want to use
5806−Blah blah (Doe 1999, Smith 2000, 2004).
5615+multiple bibliography files.
5807−\f[R]
5616+The bibliography may have any of these formats:
5684+Note that \f[C].bib\f[R] can be used with both BibTeX and BibLaTeX
5685+files; use \f[C].bibtex\f[R] to force BibTeX.
5687+Note that \f[C]pandoc-citeproc --bib2json\f[R] and
5688+\f[C]pandoc-citeproc --bib2yaml\f[R] can produce \f[C].json\f[R] and
5689+\f[C].yaml\f[R] files from any of the supported formats.
5691+In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc
5692+parses a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown;
5693+and in CSL JSON databases, an HTML-like markup:
5695+\f[B]\f[CB]<i>...</i>\f[B]\f[R]
5698+\f[B]\f[CB]<b>...</b>\f[B]\f[R]
5701+\f[B]\f[CB]<span style=\[dq]font-variant:small-caps;\[dq]>...</span>\f[B]\f[R] or \f[B]\f[CB]<sc>...</sc>\f[B]\f[R]
5704+\f[B]\f[CB]<sub>...</sub>\f[B]\f[R]
5707+\f[B]\f[CB]<sup>...</sup>\f[B]\f[R]
5710+\f[B]\f[CB]<span class=\[dq]nocase\[dq]>...</span>\f[B]\f[R]
5711+prevent a phrase from being capitalized as title case
5810−In a footnote style, it might render as
5713+\f[C]pandoc-citeproc -j\f[R] and \f[C]-y\f[R] interconvert the CSL JSON
5714+and CSL YAML formats as far as possible.
5716+As an alternative to specifying a bibliography file using
5717+\f[C]--bibliography\f[R] or the YAML metadata field
5718+\f[C]bibliography\f[R], you can include the citation data directly in
5719+the \f[C]references\f[R] field of the document\[aq]s YAML metadata.
5720+The field should contain an array of YAML-encoded references, for
5814−Blah blah.[\[ha]1]
5725+---
5816−[\[ha]1]: John Doe, \[dq]Frogs,\[dq] *Journal of Amphibians* 44 (1999);
5727+- type: article-journal
5817−Susan Smith, \[dq]Flies,\[dq] *Journal of Insects* (2000);
5728+ id: WatsonCrick1953
5818−Susan Smith, \[dq]Bees,\[dq] *Journal of Insects* (2004).
5729+ author:
5739+ title: \[aq]Molecular structure of nucleic acids: a structure for deoxyribose
5741+ title-short: Molecular structure of nucleic acids
5742+ container-title: Nature
5746+ DOI: 10.1038/171737a0
5747+ URL: https://www.nature.com/articles/171737a0
5822−See the CSL user documentation for more information about CSL styles and
5753+(\f[C]pandoc-citeproc --bib2yaml\f[R] can produce these from a
5823−how they affect rendering.
5754+bibliography file in one of the supported formats.)
5756+Citations and references can be formatted using any style supported by
5757+the Citation Style Language, listed in the Zotero Style Repository.
5758+These files are specified using the \f[C]--csl\f[R] option or the
5759+\f[C]csl\f[R] metadata field.
5760+By default, \f[C]pandoc-citeproc\f[R] will use the Chicago Manual of
5761+Style author-date format.
5762+The CSL project provides further information on finding and editing
5765+To make your citations hyperlinks to the corresponding bibliography
5766+entries, add \f[C]link-citations: true\f[R] to your YAML metadata.
5768+Citations go inside square brackets and are separated by semicolons.
5769+Each citation must have a key, composed of \[aq]\[at]\[aq] + the
5770+citation identifier from the database, and may optionally have a prefix,
5771+a locator, and a suffix.
5825−Unless a citation key start with a letter, digit, or \f[C]_\f[R], and
5772+The citation key must begin with a letter, digit, or \f[C]_\f[R], and
5826−contains only alphanumerics and internal punctuation characters
5773+may contain alphanumerics, \f[C]_\f[R], and internal punctuation
5827−(\f[C]:.#$%&-+?<>\[ti]/\f[R]), it must be surrounded by curly braces,
5774+characters (\f[C]:.#$%&-+?<>\[ti]/\f[R]).
5828−which are not considered part of the key.
5775+Here are some examples:
5829−In \f[C]\[at]Foo_bar.baz.\f[R], the key is \f[C]Foo_bar.baz\f[R].
5830−The final period is not \f[I]internal\f[R] punctuation, so it is not
5831−included in the key.
5832−In \f[C]\[at]{Foo_bar.baz.}\f[R], the key is \f[C]Foo_bar.baz.\f[R],
5833−including the final period.
5834−The curly braces are recommended if you use URLs as keys:
5835−\f[C][\[at]{https://example.com/bib?name=foobar&date=2000}, p. 33]\f[R].
5837−Citation items may optionally include a prefix, a locator, and a suffix.
5842−Blah blah [see \[at]doe99, pp. 33-35 and *passim*; \[at]smith04, chap. 1].
5779+Blah blah [see \[at]doe99, pp. 33-35; also \[at]smith04, chap. 1].
5781+Blah blah [\[at]doe99, pp. 33-35, 38-39 and *passim*].
5783+Blah blah [\[at]smith04; \[at]doe99].
5846−The first item (\f[C]doe99\f[R]) has prefix \f[C]see\f[R], locator
5847−\f[C]pp. 33-35\f[R], and suffix \f[C]and *passim*\f[R].
5848−The second item (\f[C]smith04\f[R]) has locator \f[C]chap. 1\f[R] and no
5851−Pandoc uses some heuristics to separate the locator from the rest of the
5853−It is sensitive to the locator terms defined in the CSL locale files.
5787+\f[C]pandoc-citeproc\f[R] detects locator terms in the CSL locale files.
5854Either abbreviated or unabbreviated forms are accepted.
5788Either abbreviated or unabbreviated forms are accepted.
5855In the \f[C]en-US\f[R] locale, locator terms can be written in either
5789In the \f[C]en-US\f[R] locale, locator terms can be written in either
5856singular or plural forms, as \f[C]book\f[R],
5790singular or plural forms, as \f[C]book\f[R],
@@ -5870,17 +5804,17 @@ singular or plural forms, as \f[C]book\f[R],
5870\f[C]v.\f[R]/\f[C]vv.\f[R]; \f[C]volume\f[R],
5804\f[C]v.\f[R]/\f[C]vv.\f[R]; \f[C]volume\f[R],
5871\f[C]vol.\f[R]/\f[C]vols.\f[R]; \f[C]\[ps]\f[R]/\f[C]\[ps]\[ps]\f[R];
5805\f[C]vol.\f[R]/\f[C]vols.\f[R]; \f[C]\[ps]\f[R]/\f[C]\[ps]\[ps]\f[R];
5872\f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].
5806\f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].
5873−If no locator term is used, \[lq]page\[rq] is assumed.
5807+If no locator term is used, \[dq]page\[dq] is assumed.
5875−In complex cases, you can force something to be treated as a locator by
5809+\f[C]pandoc-citeproc\f[R] will use heuristics to distinguish the locator
5876−enclosing it in curly braces or prevent parsing the suffix as locator by
5810+from the suffix.
5877−prepending curly braces:
5811+In complex cases, the locator can be enclosed in curly braces (using
5812+\f[C]pandoc-citeproc\f[R] 0.15 and higher only):
5881[\[at]smith{ii, A, D-Z}, with a suffix]
5816[\[at]smith{ii, A, D-Z}, with a suffix]
5882[\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
5817[\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
5883−[\[at]smith{}, 99 years later]
@@ -5894,8 +5828,7 @@ Smith says blah [-\[at]smith04].
5897−You can also write an author-in-text citation, by omitting the square
5831+You can also write an in-text citation, as follows:
@@ -5905,63 +5838,84 @@ brackets:
5908−This will cause the author\[cq]s name to be rendered, followed by the
5841+If the style calls for a list of works cited, it will be placed in a div
5909−bibliographical details.
5842+with id \f[C]refs\f[R], if one exists:
5910−Use this form when you want to make the citation the subject of a
5913−When you are using a note style, it is usually better to let citeproc
5914−create the footnotes from citations rather than writing an explicit
5916−If you do write an explicit note that contains a citation, note that
5917−normal citations will be put in parentheses, while author-in-text
5919−For this reason, it is sometimes preferable to use the author-in-text
5920−style inside notes when using a note style.
5921−.SS Non-default extensions
5923−The following Markdown syntax extensions are not enabled by default in
5924−pandoc, but may be enabled by adding \f[C]+EXTENSION\f[R] to the format
5925−name, where \f[C]EXTENSION\f[R] is the name of the extension.
5926−Thus, for example, \f[C]markdown+hard_line_breaks\f[R] is Markdown with
5928−.SS Extension: \f[C]rebase_relative_paths\f[R]
5930−Rewrite relative paths for Markdown links and images, depending on the
5931−path of the file containing the link or image link.
5932−For each link or image, pandoc will compute the directory of the
5933−containing file, relative to the working directory, and prepend the
5934−resulting path to the link or image path.
5936−The use of this extension is best understood by example.
5937−Suppose you have a a subdirectory for each chapter of a book,
5938−\f[C]chap1\f[R], \f[C]chap2\f[R], \f[C]chap3\f[R].
5939−Each contains a file \f[C]text.md\f[R] and a number of images used in
5941−You would like to have \f[C]\f[R] in
5942−\f[C]chap1/text.md\f[R] refer to \f[C]chap1/spider.jpg\f[R] and
5943−\f[C]\f[R] in \f[C]chap2/text.md\f[R] refer to
5944−\f[C]chap2/spider.jpg\f[R].
5949−pandoc chap*/*.md -f markdown+rebase_relative_paths
5846+::: {#refs}
5953−Without this extension, you would have to use
5851+Otherwise, it will be placed at the end of the document.
5954−\f[C]\f[R] in \f[C]chap1/text.md\f[R] and
5852+Generation of the bibliography can be suppressed by setting
5955−\f[C]\f[R] in \f[C]chap2/text.md\f[R].
5853+\f[C]suppress-bibliography: true\f[R] in the YAML metadata.
5956−Links with relative paths will be rewritten in the same way as images.
5958−Absolute paths and URLs are not changed.
5855+If you wish the bibliography to have a section heading, you can set
5959−Neither are empty paths or paths consisting entirely of a fragment,
5856+\f[C]reference-section-title\f[R] in the metadata, or put the heading at
5960−e.g., \f[C]#foo\f[R].
5857+the beginning of the div with id \f[C]refs\f[R] (if you are using it) or
5858+at the end of your document:
5868+The bibliography will be inserted after this heading.
5869+Note that the \f[C]unnumbered\f[R] class will be added to this heading,
5870+so that the section will not be numbered.
5872+If you want to include items in the bibliography without actually citing
5873+them in the body text, you can define a dummy \f[C]nocite\f[R] metadata
5874+field and put the citations there:
5880+ \[at]item1, \[at]item2
5887+In this example, the document will contain a citation for
5888+\f[C]item3\f[R] only, but the bibliography will contain entries for
5889+\f[C]item1\f[R], \f[C]item2\f[R], and \f[C]item3\f[R].
5891+It is possible to create a bibliography with all the citations, whether
5892+or not they appear in the document, by using a wildcard:
5903+For LaTeX output, you can also use \f[C]natbib\f[R] or
5904+\f[C]biblatex\f[R] to render the bibliography.
5905+In order to do so, specify bibliography files as outlined above, and add
5906+\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] argument to \f[C]pandoc\f[R]
5908+Bear in mind that bibliography files have to be in respective format
5909+(either BibTeX or BibLaTeX).
5911+For more information, see the pandoc-citeproc man page.
5912+.SS Non-pandoc extensions
5962−Note that relative paths in reference links and images will be rewritten
5914+The following Markdown syntax extensions are not enabled by default in
5963−relative to the file containing the link reference definition, not the
5915+pandoc, but may be enabled by adding \f[C]+EXTENSION\f[R] to the format
5964−file containing the reference link or image itself, if these differ.
5916+name, where \f[C]EXTENSION\f[R] is the name of the extension.
5917+Thus, for example, \f[C]markdown+hard_line_breaks\f[R] is Markdown with
5965.SS Extension: \f[C]attributes\f[R]
5919.SS Extension: \f[C]attributes\f[R]
5967Allows attributes to be attached to any inline or block-level element.
5921Allows attributes to be attached to any inline or block-level element.
@@ -5992,7 +5946,7 @@ affect the code block element.
5992Attributes that occur at the end of a reference link definition affect
5946Attributes that occur at the end of a reference link definition affect
5993links that refer to that definition.
5947links that refer to that definition.
5995−Note that pandoc\[cq]s AST does not currently allow attributes to be
5949+Note that pandoc\[aq]s AST does not currently allow attributes to be
5996attached to arbitrary elements.
5950attached to arbitrary elements.
5997Hence a Span or Div container will be added if needed.
5951Hence a Span or Div container will be added if needed.
5998.SS Extension: \f[C]old_dashes\f[R]
5952.SS Extension: \f[C]old_dashes\f[R]
@@ -6006,7 +5960,7 @@ It is selected automatically for \f[C]textile\f[R] input.
6007Allow \f[C]<\f[R] and \f[C]>\f[R] to be backslash-escaped, as they can
5961Allow \f[C]<\f[R] and \f[C]>\f[R] to be backslash-escaped, as they can
6008be in GitHub flavored Markdown but not original Markdown.
5962be in GitHub flavored Markdown but not original Markdown.
6009−This is implied by pandoc\[cq]s default \f[C]all_symbols_escapable\f[R].
5963+This is implied by pandoc\[aq]s default \f[C]all_symbols_escapable\f[R].
6010.SS Extension: \f[C]lists_without_preceding_blankline\f[R]
5964.SS Extension: \f[C]lists_without_preceding_blankline\f[R]
6012Allow a list to occur right after a paragraph, with no intervening blank
5966Allow a list to occur right after a paragraph, with no intervening blank
@@ -6130,7 +6084,7 @@ in several respects:
6130No blank line is required between consecutive items of the definition
6084No blank line is required between consecutive items of the definition
6132.IP \[bu] 2
6086.IP \[bu] 2
6133−To get a \[lq]tight\[rq] or \[lq]compact\[rq] list, omit space between
6087+To get a \[dq]tight\[dq] or \[dq]compact\[dq] list, omit space between
6134consecutive items; the space between a term and its definition does not
6088consecutive items; the space between a term and its definition does not
6135affect anything.
6089affect anything.
6136.IP \[bu] 2
6090.IP \[bu] 2
@@ -6141,489 +6095,65 @@ be indented four spaces.
6141Use Project Gutenberg conventions for \f[C]plain\f[R] output: all-caps
6095Use Project Gutenberg conventions for \f[C]plain\f[R] output: all-caps
6142for strong emphasis, surround by underscores for regular emphasis, add
6096for strong emphasis, surround by underscores for regular emphasis, add
6143extra blank space around headings.
6097extra blank space around headings.
6144−.SS Extension: \f[C]sourcepos\f[R]
6146−Include source position attributes when parsing \f[C]commonmark\f[R].
6147−For elements that accept attributes, a \f[C]data-pos\f[R] attribute is
6148−added; other elements are placed in a surrounding Div or Span elemnet
6149−with a \f[C]data-pos\f[R] attribute.
6150.SS Markdown variants
6098.SS Markdown variants
6152−In addition to pandoc\[cq]s extended Markdown, the following Markdown
6100+In addition to pandoc\[aq]s extended Markdown, the following Markdown
6153variants are supported:
6101variants are supported:
6155−\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)
6157−\f[C]markdown_github\f[R] (deprecated GitHub-Flavored Markdown)
6159−\f[C]markdown_mmd\f[R] (MultiMarkdown)
6161−\f[C]markdown_strict\f[R] (Markdown.pl)
6163−\f[C]commonmark\f[R] (CommonMark)
6165−\f[C]gfm\f[R] (Github-Flavored Markdown)
6167−\f[C]commonmark_x\f[R] (CommonMark with many pandoc extensions)
6169−To see which extensions are supported for a given format, and which are
6170−enabled by default, you can use the command
6174−pandoc --list-extensions=FORMAT
6178−where \f[C]FORMAT\f[R] is replaced with the name of the format.
6180−Note that the list of extensions for \f[C]commonmark\f[R],
6181−\f[C]gfm\f[R], and \f[C]commonmark_x\f[R] are defined relative to
6183−So, for example, \f[C]backtick_code_blocks\f[R] does not appear as an
6184−extension, since it is enabled by default and cannot be disabled.
6187−When the \f[C]--citeproc\f[R] option is used, pandoc can automatically
6188−generate citations and a bibliography in a number of styles.
6193−pandoc --citeproc myinput.txt
6197−To use this feature, you will need to have
6199−a document containing citations (see Extension: \f[C]citations\f[R]);
6201−a source of bibliographic data: either an external bibliography file or
6202−a list of \f[C]references\f[R] in the document\[cq]s YAML metadata
6204−optionally, a CSL citation style.
6205−.SS Specifying bibliographic data
6207−You can specify an external bibliography using the
6208−\f[C]bibliography\f[R] metadata field in a YAML metadata section or the
6209−\f[C]--bibliography\f[R] command line argument.
6210−If you want to use multiple bibliography files, you can supply multiple
6211−\f[C]--bibliography\f[R] arguments or set \f[C]bibliography\f[R]
6212−metadata field to YAML array.
6213−A bibliography may have any of these formats:
6246−Note that \f[C].bib\f[R] can be used with both BibTeX and BibLaTeX
6247−files; use the extension \f[C].bibtex\f[R] to force interpretation as
6250−In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup inside
6251−fields such as \f[C]title\f[R]; in CSL YAML databases, pandoc Markdown;
6252−and in CSL JSON databases, an HTML-like markup:
6254−\f[B]\f[CB]<i>...</i>\f[B]\f[R]
6257−\f[B]\f[CB]<b>...</b>\f[B]\f[R]
6260−\f[B]\f[CB]<span style=\[dq]font-variant:small-caps;\[dq]>...</span>\f[B]\f[R] or \f[B]\f[CB]<sc>...</sc>\f[B]\f[R]
6263−\f[B]\f[CB]<sub>...</sub>\f[B]\f[R]
6103+\f[B]\f[CB]markdown_phpextra\f[B]\f[R] (PHP Markdown Extra)
6264−subscript
6104+\f[C]footnotes\f[R], \f[C]pipe_tables\f[R], \f[C]raw_html\f[R],
6105+\f[C]markdown_attribute\f[R], \f[C]fenced_code_blocks\f[R],
6106+\f[C]definition_lists\f[R], \f[C]intraword_underscores\f[R],
6107+\f[C]header_attributes\f[R], \f[C]link_attributes\f[R],
6108+\f[C]abbreviations\f[R], \f[C]shortcut_reference_links\f[R],
6109+\f[C]spaced_reference_links\f[R].
6266−\f[B]\f[CB]<sup>...</sup>\f[B]\f[R]
6111+\f[B]\f[CB]markdown_github\f[B]\f[R] (deprecated GitHub-Flavored Markdown)
6112+\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
6113+\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
6114+\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
6115+\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
6116+\f[C]strikeout\f[R], \f[C]task_lists\f[R], \f[C]emoji\f[R],
6117+\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
6118+\f[C]lists_without_preceding_blankline\f[R].
6120+\f[B]\f[CB]markdown_mmd\f[B]\f[R] (MultiMarkdown)
6121+\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]markdown_attribute\f[R],
6122+\f[C]mmd_link_attributes\f[R], \f[C]tex_math_double_backslash\f[R],
6123+\f[C]intraword_underscores\f[R], \f[C]mmd_title_block\f[R],
6124+\f[C]footnotes\f[R], \f[C]definition_lists\f[R],
6125+\f[C]all_symbols_escapable\f[R], \f[C]implicit_header_references\f[R],
6126+\f[C]auto_identifiers\f[R], \f[C]mmd_header_identifiers\f[R],
6127+\f[C]shortcut_reference_links\f[R], \f[C]implicit_figures\f[R],
6267−superscript
6128+\f[C]superscript\f[R], \f[C]subscript\f[R],
6268−.TP
6129+\f[C]backtick_code_blocks\f[R], \f[C]spaced_reference_links\f[R],
6269−\f[B]\f[CB]<span class=\[dq]nocase\[dq]>...</span>\f[B]\f[R]
6130+\f[C]raw_attribute\f[R].
6270−prevent a phrase from being capitalized as title case
6131+.TP
6271−.PP
6132+\f[B]\f[CB]markdown_strict\f[B]\f[R] (Markdown.pl)
6272−As an alternative to specifying a bibliography file using
6133+\f[C]raw_html\f[R], \f[C]shortcut_reference_links\f[R],
6273−\f[C]--bibliography\f[R] or the YAML metadata field
6134+\f[C]spaced_reference_links\f[R].
6274−\f[C]bibliography\f[R], you can include the citation data directly in
6135+.PP
6275−the \f[C]references\f[R] field of the document\[cq]s YAML metadata.
6136+We also support \f[C]commonmark\f[R] and \f[C]gfm\f[R] (GitHub-Flavored
6276−The field should contain an array of YAML-encoded references, for
6137+Markdown, which is implemented as a set of extensions on
6277−example:
6138+\f[C]commonmark\f[R]).
6279−.nf
6140+Note, however, that \f[C]commonmark\f[R] and \f[C]gfm\f[R] have limited
6280−\f[C]
6141+support for extensions.
6281−---
6142+Only those listed below (and \f[C]smart\f[R], \f[C]raw_tex\f[R], and
6282−references:
6143+\f[C]hard_line_breaks\f[R]) will work.
6283−- type: article-journal
6144+The extensions can, however, all be individually disabled.
6284− id: WatsonCrick1953
6145+Also, \f[C]raw_tex\f[R] only affects \f[C]gfm\f[R] output, not input.
6286− - family: Watson
6147+\f[B]\f[CB]gfm\f[B]\f[R] (GitHub-Flavored Markdown)
6287− given: J. D.
6148+\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]native_divs\f[R],
6288− - family: Crick
6149+\f[C]fenced_code_blocks\f[R], \f[C]auto_identifiers\f[R],
6289− given: F. H. C.
6150+\f[C]gfm_auto_identifiers\f[R], \f[C]backtick_code_blocks\f[R],
6290− issued:
6151+\f[C]autolink_bare_uris\f[R], \f[C]space_in_atx_header\f[R],
6291− date-parts:
6152+\f[C]intraword_underscores\f[R], \f[C]strikeout\f[R],
6292− - - 1953
6153+\f[C]task_lists\f[R], \f[C]emoji\f[R],
6293− - 4
6154+\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
6294− - 25
6155+\f[C]lists_without_preceding_blankline\f[R].
6295− title: \[aq]Molecular structure of nucleic acids: a structure for
6296− deoxyribose nucleic acid\[aq]
6297− title-short: Molecular structure of nucleic acids
6298− container-title: Nature
6302− DOI: 10.1038/171737a0
6303− URL: https://www.nature.com/articles/171737a0
6309−If both an external bibliography and inline (YAML metadata) references
6310−are provided, both will be used.
6311−In case of conflicting \f[C]id\f[R]s, the inline references will take
6314−Note that \f[C]pandoc\f[R] can be used to produce such a YAML metadata
6315−section from a BibTeX, BibLaTeX, or CSL JSON bibliography:
6319−pandoc chem.bib -s -f biblatex -t markdown
6320−pandoc chem.json -s -f csljson -t markdown
6324−Indeed, \f[C]pandoc\f[R] can convert between any of these citation
6329−pandoc chem.bib -s -f biblatex -t csljson
6330−pandoc chem.yaml -s -f markdown -t biblatex
6334−Running pandoc on a bibliography file with the \f[C]--citeproc\f[R]
6335−option will create a formatted bibliography in the format of your
6340−pandoc chem.bib -s --citeproc -o chem.html
6341−pandoc chem.bib -s --citeproc -o chem.pdf
6344−.SS Capitalization in titles
6346−If you are using a bibtex or biblatex bibliography, then observe the
6349−English titles should be in title case.
6350−Non-English titles should be in sentence case, and the \f[C]langid\f[R]
6351−field in biblatex should be set to the relevant language.
6352−(The following values are treated as English: \f[C]american\f[R],
6353−\f[C]british\f[R], \f[C]canadian\f[R], \f[C]english\f[R],
6354−\f[C]australian\f[R], \f[C]newzealand\f[R], \f[C]USenglish\f[R], or
6355−\f[C]UKenglish\f[R].)
6357−As is standard with bibtex/biblatex, proper names should be protected
6358−with curly braces so that they won\[cq]t be lowercased in styles that
6359−call for sentence case.
6365−title = {My Dinner with {Andre}}
6370−In addition, words that should remain lowercase (or camelCase) should be
6376−title = {Spin Wave Dispersion on the {nm} Scale}
6380−Though this is not necessary in bibtex/biblatex, it is necessary with
6381−citeproc, which stores titles internally in sentence case, and converts
6382−to title case in styles that require it.
6383−Here we protect \[lq]nm\[rq] so that it doesn\[cq]t get converted to
6384−\[lq]Nm\[rq] at this stage.
6387−If you are using a CSL bibliography (either JSON or YAML), then observe
6388−the following rules:
6390−All titles should be in sentence case.
6392−Use the \f[C]language\f[R] field for non-English titles to prevent their
6393−conversion to title case in styles that call for this.
6394−(Conversion happens only if \f[C]language\f[R] begins with \f[C]en\f[R]
6397−Protect words that should not be converted to title case using this
6403−Spin wave dispersion on the <span class=\[dq]nocase\[dq]>nm</span> scale
6407−.SS Conference Papers, Published vs.\ Unpublished
6409−For a formally published conference paper, use the biblatex entry type
6410−\f[C]inproceedings\f[R] (which will be mapped to CSL
6411−\f[C]paper-conference\f[R]).
6413−For an unpublished manuscript, use the biblatex entry type
6414−\f[C]unpublished\f[R] without an \f[C]eventtitle\f[R] field (this entry
6415−type will be mapped to CSL \f[C]manuscript\f[R]).
6417−For a talk, an unpublished conference paper, or a poster presentation,
6418−use the biblatex entry type \f[C]unpublished\f[R] with an
6419−\f[C]eventtitle\f[R] field (this entry type will be mapped to CSL
6421−Use the biblatex \f[C]type\f[R] field to indicate the type,
6422−e.g.\ \[lq]Paper\[rq], or \[lq]Poster\[rq].
6423−\f[C]venue\f[R] and \f[C]eventdate\f[R] may be useful too, though
6424−\f[C]eventdate\f[R] will not be rendered by most CSL styles.
6425−Note that \f[C]venue\f[R] is for the event\[cq]s venue, unlike
6426−\f[C]location\f[R] which describes the publisher\[cq]s location; do not
6427−use the latter for an unpublished conference paper.
6428−.SS Specifying a citation style
6430−Citations and references can be formatted using any style supported by
6431−the Citation Style Language, listed in the Zotero Style Repository.
6432−These files are specified using the \f[C]--csl\f[R] option or the
6433−\f[C]csl\f[R] (or \f[C]citation-style\f[R]) metadata field.
6434−By default, pandoc will use the Chicago Manual of Style author-date
6436−(You can override this default by copying a CSL style of your choice to
6437−\f[C]default.csl\f[R] in your user data directory.) The CSL project
6438−provides further information on finding and editing styles.
6440−The \f[C]--citation-abbreviations\f[R] option (or the
6441−\f[C]citation-abbreviations\f[R] metadata field) may be used to specify
6442−a JSON file containing abbreviations of journals that should be used in
6443−formatted bibliographies when \f[C]form=\[dq]short\[dq]\f[R] is
6445−The format of the file can be illustrated with an example:
6449−{ \[dq]default\[dq]: {
6450− \[dq]container-title\[dq]: {
6451− \[dq]Lloyd\[aq]s Law Reports\[dq]: \[dq]Lloyd\[aq]s Rep\[dq],
6452− \[dq]Estates Gazette\[dq]: \[dq]EG\[dq],
6453− \[dq]Scots Law Times\[dq]: \[dq]SLT\[dq]
6459−.SS Citations in note styles
6461−Pandoc\[cq]s citation processing is designed to allow you to move
6462−between author-date, numerical, and note styles without modifying the
6464−When you\[cq]re using a note style, avoid inserting footnotes manually.
6465−Instead, insert citations just as you would in an author-date
6466−style\[em]for example,
6470−Blah blah [\[at]foo, p. 33].
6474−The footnote will be created automatically.
6475−Pandoc will take care of removing the space and moving the note before
6476−or after the period, depending on the setting of
6477−\f[C]notes-after-punctuation\f[R], as described below in Other relevant
6480−In some cases you may need to put a citation inside a regular footnote.
6481−Normal citations in footnotes (such as \f[C][\[at]foo, p. 33]\f[R]) will
6482−be rendered in parentheses.
6483−In-text citations (such as \f[C]\[at]foo [p. 33]\f[R]) will be rendered
6484−without parentheses.
6485−(A comma will be added if appropriate.) Thus:
6489−[\[ha]1]: Some studies [\[at]foo; \[at]bar, p. 33] show that
6490−frubulicious zoosnaps are quantical. For a survey
6491−of the literature, see \[at]baz [chap. 1].
6494−.SS Raw content in a style
6496−To include raw content in a prefix, suffix, delimiter, or term, surround
6497−it with these tags indicating the format:
6501−{{jats}}<ref>{{/jats}}
6505−Without the tags, the string will be interpreted as a string and escaped
6506−in the output, rather than being passed through raw.
6508−This feature allows stylesheets to be customized to give different
6509−output for different output formats.
6510−However, stylesheets customized in this way will not be usable by other
6511−CSL implementations.
6512−.SS Placement of the bibliography
6514−If the style calls for a list of works cited, it will be placed in a div
6515−with id \f[C]refs\f[R], if one exists:
6524−Otherwise, it will be placed at the end of the document.
6525−Generation of the bibliography can be suppressed by setting
6526−\f[C]suppress-bibliography: true\f[R] in the YAML metadata.
6528−If you wish the bibliography to have a section heading, you can set
6529−\f[C]reference-section-title\f[R] in the metadata, or put the heading at
6530−the beginning of the div with id \f[C]refs\f[R] (if you are using it) or
6531−at the end of your document:
6541−The bibliography will be inserted after this heading.
6542−Note that the \f[C]unnumbered\f[R] class will be added to this heading,
6543−so that the section will not be numbered.
6544−.SS Including uncited items in the bibliography
6546−If you want to include items in the bibliography without actually citing
6547−them in the body text, you can define a dummy \f[C]nocite\f[R] metadata
6548−field and put the citations there:
6554− \[at]item1, \[at]item2
6561−In this example, the document will contain a citation for
6562−\f[C]item3\f[R] only, but the bibliography will contain entries for
6563−\f[C]item1\f[R], \f[C]item2\f[R], and \f[C]item3\f[R].
6565−It is possible to create a bibliography with all the citations, whether
6566−or not they appear in the document, by using a wildcard:
6577−For LaTeX output, you can also use \f[C]natbib\f[R] or
6578−\f[C]biblatex\f[R] to render the bibliography.
6579−In order to do so, specify bibliography files as outlined above, and add
6580−\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] argument to \f[C]pandoc\f[R]
6582−Bear in mind that bibliography files have to be in either BibTeX (for
6583−\f[C]--natbib\f[R]) or BibLaTeX (for \f[C]--biblatex\f[R]) format.
6584−.SS Other relevant metadata fields
6586−A few other metadata fields affect bibliography formatting:
6588−\f[B]\f[CB]link-citations\f[B]\f[R]
6589−If true, citations will be hyperlinked to the corresponding bibliography
6590−entries (for author-date and numerical styles only).
6592−\f[B]\f[CB]lang\f[B]\f[R]
6593−The \f[C]lang\f[R] field will affect how the style is localized, for
6594−example in the translation of labels, the use of quotation marks, and
6595−the way items are sorted.
6596−(For backwards compatibility, \f[C]locale\f[R] may be used instead of
6597−\f[C]lang\f[R], but this use is deprecated.)
6600−A BCP 47 language tag is expected: for example, \f[C]en\f[R],
6601−\f[C]de\f[R], \f[C]en-US\f[R], \f[C]fr-CA\f[R], \f[C]ug-Cyrl\f[R].
6602−The unicode extension syntax (after \f[C]-u-\f[R]) may be used to
6603−specify options for collation (sorting) more precisely.
6604−Here are some examples:
6606−\f[C]zh-u-co-pinyin\f[R] \[en] Chinese with the Pinyin collation.
6608−\f[C]es-u-co-trad\f[R] \[en] Spanish with the traditional collation
6609−(with \f[C]Ch\f[R] sorting after \f[C]C\f[R]).
6611−\f[C]fr-u-kb\f[R] \[en] French with \[lq]backwards\[rq] accent sorting
6612−(with \f[C]cot\['e]\f[R] sorting after \f[C]c\[^o]te\f[R]).
6614−\f[C]en-US-u-kf-upper\f[R] \[en] English with uppercase letters sorting
6615−before lower (default is lower before upper).
6618−\f[B]\f[CB]notes-after-punctuation\f[B]\f[R]
6619−If true (the default), pandoc will put footnote citations after
6620−following punctuation.
6621−For example, if the source contains \f[C]blah blah [\[at]jones99].\f[R],
6622−the result will look like \f[C]blah blah.[\[ha]1]\f[R], with the note
6623−moved after the period and the space collapsed.
6624−If false, the space will still be collapsed, but the footnote will not
6625−be moved after the punctuation.
6626−.SH SLIDE SHOWS
6156+.SH PRODUCING SLIDE SHOWS WITH PANDOC
6628You can use pandoc to produce an HTML + JavaScript slide presentation
6158You can use pandoc to produce an HTML + JavaScript slide presentation
6629that can be viewed via a web browser.
6159that can be viewed via a web browser.
@@ -6632,7 +6162,7 @@ reveal.js.
6632You can also produce a PDF slide show using LaTeX \f[C]beamer\f[R], or
6162You can also produce a PDF slide show using LaTeX \f[C]beamer\f[R], or
6633slides shows in Microsoft PowerPoint format.
6163slides shows in Microsoft PowerPoint format.
6635−Here\[cq]s the Markdown source for a simple slide show,
6165+Here\[aq]s the Markdown source for a simple slide show,
6636\f[C]habits.txt\f[R]:
6166\f[C]habits.txt\f[R]:
@@ -6734,26 +6264,21 @@ A heading at the slide level always starts a new slide.
6734.IP \[bu] 2
6264.IP \[bu] 2
6735Headings \f[I]below\f[R] the slide level in the hierarchy create
6265Headings \f[I]below\f[R] the slide level in the hierarchy create
6736headings \f[I]within\f[R] a slide.
6266headings \f[I]within\f[R] a slide.
6737−(In beamer, a \[lq]block\[rq] will be created.
6738−If the heading has the class \f[C]example\f[R], an
6739−\f[C]exampleblock\f[R] environment will be used; if it has the class
6740−\f[C]alert\f[R], an \f[C]alertblock\f[R] will be used; otherwise a
6741−regular \f[C]block\f[R] will be used.)
6742.IP \[bu] 2
6267.IP \[bu] 2
6743Headings \f[I]above\f[R] the slide level in the hierarchy create
6268Headings \f[I]above\f[R] the slide level in the hierarchy create
6744−\[lq]title slides,\[rq] which just contain the section title and help to
6269+\[dq]title slides,\[dq] which just contain the section title and help to
6745break the slide show into sections.
6270break the slide show into sections.
6746Non-slide content under these headings will be included on the title
6271Non-slide content under these headings will be included on the title
6747slide (for HTML slide shows) or in a subsequent slide with the same
6272slide (for HTML slide shows) or in a subsequent slide with the same
6748title (for beamer).
6273title (for beamer).
6749.IP \[bu] 2
6274.IP \[bu] 2
6750−A title page is constructed automatically from the document\[cq]s title
6275+A title page is constructed automatically from the document\[aq]s title
6751block, if present.
6276block, if present.
6752(In the case of beamer, this can be disabled by commenting out some
6277(In the case of beamer, this can be disabled by commenting out some
6753lines in the default template.)
6278lines in the default template.)
6755These rules are designed to support many different styles of slide show.
6280These rules are designed to support many different styles of slide show.
6756−If you don\[cq]t care about structuring your slides into sections and
6281+If you don\[aq]t care about structuring your slides into sections and
6757subsections, you can just use level-1 headings for all each slide.
6282subsections, you can just use level-1 headings for all each slide.
6758(In that case, level-1 will be the slide level.) But you can also
6283(In that case, level-1 will be the slide level.) But you can also
6759structure the slide show into sections, as in the example above.
6284structure the slide show into sections, as in the example above.
@@ -6765,8 +6290,8 @@ It is not recommended that you use deeper nesting of section levels with
6765reveal.js.
6290reveal.js.
6766.SS Incremental lists
6291.SS Incremental lists
6768−By default, these writers produce lists that display \[lq]all at
6293+By default, these writers produce lists that display \[dq]all at
6769−once.\[rq] If you want your lists to display incrementally (one item at
6294+once.\[dq] If you want your lists to display incrementally (one item at
6770a time), use the \f[C]-i\f[R] option.
6295a time), use the \f[C]-i\f[R] option.
6771If you want a particular list to depart from the default, put it in a
6296If you want a particular list to depart from the default, put it in a
6772\f[C]div\f[R] block with class \f[C]incremental\f[R] or
6297\f[C]div\f[R] block with class \f[C]incremental\f[R] or
@@ -6819,7 +6344,7 @@ Note: Neither the \f[C]-i/--incremental\f[R] option nor any of the
6819methods described here currently works for PowerPoint output.
6344methods described here currently works for PowerPoint output.
6820.SS Inserting pauses
6345.SS Inserting pauses
6822−You can add \[lq]pauses\[rq] within a slide by including a paragraph
6347+You can add \[dq]pauses\[dq] within a slide by including a paragraph
6823containing three dots, separated by spaces:
6348containing three dots, separated by spaces:
@@ -6842,7 +6367,7 @@ in \f[C]$DATADIR/s5/default\f[R] (for S5), \f[C]$DATADIR/slidy\f[R] (for
6842Slidy), or \f[C]$DATADIR/slideous\f[R] (for Slideous), where
6367Slidy), or \f[C]$DATADIR/slideous\f[R] (for Slideous), where
6843\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
6368\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
6845−The originals may be found in pandoc\[cq]s system data directory
6370+The originals may be found in pandoc\[aq]s system data directory
6846(generally \f[C]$CABALDIR/pandoc-VERSION/s5/default\f[R]).
6371(generally \f[C]$CABALDIR/pandoc-VERSION/s5/default\f[R]).
6847Pandoc will look there for any files it does not find in the user data
6372Pandoc will look there for any files it does not find in the user data
6848directory.
6373directory.
@@ -6972,7 +6497,7 @@ contents...
6972The class \f[C]onlytextwidth\f[R] sets the \f[C]totalwidth\f[R] to
6497The class \f[C]onlytextwidth\f[R] sets the \f[C]totalwidth\f[R] to
6973\f[C]\[rs]textwidth\f[R].
6498\f[C]\[rs]textwidth\f[R].
6975−See Section 12.7 of the Beamer User\[cq]s Guide for more details.
6500+See Section 12.7 of the Beamer User\[aq]s Guide for more details.
6976.SS Frame attributes in beamer
6501.SS Frame attributes in beamer
6978Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[R] option to
6503Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[R] option to
@@ -6988,7 +6513,7 @@ introducing the slide:
6990All of the other frame attributes described in Section 8.1 of the Beamer
6515All of the other frame attributes described in Section 8.1 of the Beamer
6991−User\[cq]s Guide may also be used: \f[C]allowdisplaybreaks\f[R],
6516+User\[aq]s Guide may also be used: \f[C]allowdisplaybreaks\f[R],
6992\f[C]allowframebreaks\f[R], \f[C]b\f[R], \f[C]c\f[R], \f[C]t\f[R],
6517\f[C]allowframebreaks\f[R], \f[C]b\f[R], \f[C]c\f[R], \f[C]t\f[R],
6993\f[C]environment\f[R], \f[C]label\f[R], \f[C]plain\f[R],
6518\f[C]environment\f[R], \f[C]label\f[R], \f[C]plain\f[R],
6994\f[C]shrink\f[R], \f[C]standout\f[R], \f[C]noframenumbering\f[R].
6519\f[C]shrink\f[R], \f[C]standout\f[R], \f[C]noframenumbering\f[R].
@@ -7013,7 +6538,7 @@ To set an image for a particular reveal.js slide, add
7013\f[C]{data-background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
6538\f[C]{data-background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
7014slide-level heading on the slide (which may even be empty).
6539slide-level heading on the slide (which may even be empty).
7016−In reveal.js\[cq]s overview mode, the parallaxBackgroundImage will show
6541+In reveal.js\[aq]s overview mode, the parallaxBackgroundImage will show
7017up only on the first slide.
6542up only on the first slide.
7019Other reveal.js background settings also work on individual slides,
6544Other reveal.js background settings also work on individual slides,
@@ -7049,7 +6574,7 @@ Slide 1 has background_image.png as its background.
7049Slide 2 has a special image for its background, even though the heading has no content.
6574Slide 2 has a special image for its background, even though the heading has no content.
7052−.SH EPUBS
6577+.SH CREATING EPUBS WITH PANDOC
7053.SS EPUB Metadata
6578.SS EPUB Metadata
7055EPUB metadata may be specified using the \f[C]--epub-metadata\f[R]
6580EPUB metadata may be specified using the \f[C]--epub-metadata\f[R]
@@ -7103,8 +6628,8 @@ Valid values for \f[C]type\f[R] are \f[C]main\f[R], \f[C]subtitle\f[R],
7103Either a string value, or an object with fields \f[C]role\f[R],
6628Either a string value, or an object with fields \f[C]role\f[R],
7104\f[C]file-as\f[R], and \f[C]text\f[R], or a list of such objects.
6629\f[C]file-as\f[R], and \f[C]text\f[R], or a list of such objects.
7105Valid values for \f[C]role\f[R] are MARC relators, but pandoc will
6630Valid values for \f[C]role\f[R] are MARC relators, but pandoc will
7106−attempt to translate the human-readable versions (like \[lq]author\[rq]
6631+attempt to translate the human-readable versions (like \[dq]author\[dq]
7107−and \[lq]editor\[rq]) to the appropriate marc relators.
6632+and \[dq]editor\[dq]) to the appropriate marc relators.
7109\f[B]\f[CB]contributor\f[B]\f[R]
6634\f[B]\f[CB]contributor\f[B]\f[R]
7110Same format as \f[C]creator\f[R].
6635Same format as \f[C]creator\f[R].
@@ -7139,16 +6664,6 @@ A string value.
7139\f[B]\f[CB]rights\f[B]\f[R]
6664\f[B]\f[CB]rights\f[B]\f[R]
7140A string value.
6665A string value.
7142−\f[B]\f[CB]belongs-to-collection\f[B]\f[R]
7144−identifies the name of a collection to which the EPUB Publication
7147−\f[B]\f[CB]group-position\f[B]\f[R]
7148−The \f[C]group-position\f[R] field indicates the numeric position in
7149−which the EPUB Publication belongs relative to other works belonging to
7150−the same \f[C]belongs-to-collection\f[R] field.
7152\f[B]\f[CB]cover-image\f[B]\f[R]
6667\f[B]\f[CB]cover-image\f[B]\f[R]
7153A string value (path to cover image).
6668A string value (path to cover image).
@@ -7303,6 +6818,11 @@ T}@T{
7303frontmatter
6818frontmatter
7308backmatter
6828backmatter
@@ -7343,7 +6863,7 @@ For example:
7346−.SH JUPYTER NOTEBOOKS
6866+.SH CREATING JUPYTER NOTEBOOKS WITH PANDOC
7348When creating a Jupyter notebook, pandoc will try to infer the notebook
6868When creating a Jupyter notebook, pandoc will try to infer the notebook
7349structure.
6869structure.
@@ -7458,7 +6978,7 @@ hello
7458If you include raw HTML or TeX in an output cell, use the [raw
6978If you include raw HTML or TeX in an output cell, use the [raw
7459attribute][Extension: \f[C]fenced_attribute\f[R]], as shown in the last
6979attribute][Extension: \f[C]fenced_attribute\f[R]], as shown in the last
7460cell of the example above.
6980cell of the example above.
7461−Although pandoc can process \[lq]bare\[rq] raw HTML and TeX, the result
6981+Although pandoc can process \[dq]bare\[dq] raw HTML and TeX, the result
7462is often interspersed raw elements and normal textual elements, and in
6982is often interspersed raw elements and normal textual elements, and in
7463an output cell pandoc expects a single, connected raw block.
6983an output cell pandoc expects a single, connected raw block.
7464To avoid using raw HTML or TeX except when marked explicitly using raw
6984To avoid using raw HTML or TeX except when marked explicitly using raw
@@ -7511,10 +7031,10 @@ pandoc --highlight-style my.theme
7513If you are not satisfied with the built-in highlighting, or you want
7033If you are not satisfied with the built-in highlighting, or you want
7514−highlight a language that isn\[cq]t supported, you can use the
7034+highlight a language that isn\[aq]t supported, you can use the
7515\f[C]--syntax-definition\f[R] option to load a KDE-style XML syntax
7035\f[C]--syntax-definition\f[R] option to load a KDE-style XML syntax
7516definition file.
7036definition file.
7517−Before writing your own, have a look at KDE\[cq]s repository of syntax
7037+Before writing your own, have a look at KDE\[aq]s repository of syntax
7518definitions.
7038definitions.
7520To disable highlighting, use the \f[C]--no-highlight\f[R] option.
7040To disable highlighting, use the \f[C]--no-highlight\f[R] option.
@@ -7523,7 +7043,7 @@ To disable highlighting, use the \f[C]--no-highlight\f[R] option.
7523Custom styles can be used in the docx and ICML formats.
7043Custom styles can be used in the docx and ICML formats.
7524.SS Output
7044.SS Output
7526−By default, pandoc\[cq]s docx and ICML output applies a predefined set
7046+By default, pandoc\[aq]s docx and ICML output applies a predefined set
7527of styles for blocks such as paragraphs and block quotes, and uses
7047of styles for blocks such as paragraphs and block quotes, and uses
7528largely default formatting (italics, bold) for inlines.
7048largely default formatting (italics, bold) for inlines.
7529This will work for most purposes, especially alongside a
7049This will work for most purposes, especially alongside a
@@ -7544,7 +7064,7 @@ So, for example, using the \f[C]bracketed_spans\f[R] syntax,
7547−would produce a docx file with \[lq]Get out\[rq] styled with character
7067+would produce a docx file with \[dq]Get out\[dq] styled with character
7548style \f[C]Emphatically\f[R].
7068style \f[C]Emphatically\f[R].
7549Similarly, using the \f[C]fenced_divs\f[R] syntax,
7069Similarly, using the \f[C]fenced_divs\f[R] syntax,
@@ -7575,13 +7095,13 @@ character style (perhaps to change their color), you can write a filter
7575which will transform all italicized inlines to inlines within an
7095which will transform all italicized inlines to inlines within an
7576\f[C]Emphasis\f[R] custom-style \f[C]span\f[R].
7096\f[C]Emphasis\f[R] custom-style \f[C]span\f[R].
7578−For docx output, you don\[cq]t need to enable any extensions for custom
7098+For docx output, you don\[aq]t need to enable any extensions for custom
7579styles to work.
7099styles to work.
7580.SS Input
7100.SS Input
7582The docx reader, by default, only reads those styles that it can convert
7102The docx reader, by default, only reads those styles that it can convert
7583into pandoc elements, either by direct conversion or interpreting the
7103into pandoc elements, either by direct conversion or interpreting the
7584−derivation of the input document\[cq]s styles.
7104+derivation of the input document\[aq]s styles.
7586By enabling the \f[C]styles\f[R] extension in the docx reader
7106By enabling the \f[C]styles\f[R] extension in the docx reader
7587(\f[C]-f docx+styles\f[R]), you can produce output that maintains the
7107(\f[C]-f docx+styles\f[R]), you can produce output that maintains the
@@ -7664,20 +7184,6 @@ need to specify a template manually using \f[C]--template\f[R] or add a
7664new default template with the name
7184new default template with the name
7665\f[C]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[C]templates\f[R]
7185\f[C]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[C]templates\f[R]
7666subdirectory of your user data directory (see Templates).
7186subdirectory of your user data directory (see Templates).
7667−.SH REPRODUCIBLE BUILDS
7669−Some of the document formats pandoc targets (such as EPUB, docx, and
7670−ODT) include build timestamps in the generated document.
7671−That means that the files generated on successive builds will differ,
7672−even if the source does not.
7673−To avoid this, set the \f[C]SOURCE_DATE_EPOCH\f[R] environment variable,
7674−and the timestamp will be taken from it instead of the current time.
7675−\f[C]SOURCE_DATE_EPOCH\f[R] should contain an integer unix timestamp
7676−(specifying the number of second since midnight UTC January 1, 1970).
7678−Some document formats also include a unique identifier.
7679−For EPUB, this can be set explicitly by setting the \f[C]identifier\f[R]
7680−metadata field (see EPUB Metadata, above).
7681.SH A NOTE ON SECURITY
7187.SH A NOTE ON SECURITY
7683If you use pandoc to convert user-contributed content in a web
7189If you use pandoc to convert user-contributed content in a web
@@ -7696,7 +7202,7 @@ fully isolates pandoc from your file system, by running the pandoc
7696operations in the \f[C]PandocPure\f[R] monad.
7202operations in the \f[C]PandocPure\f[R] monad.
7697See the document Using the pandoc API for more details.
7203See the document Using the pandoc API for more details.
7698.IP "3." 3
7204.IP "3." 3
7699−Pandoc\[cq]s parsers can exhibit pathological performance on some corner
7205+Pandoc\[aq]s parsers can exhibit pathological performance on some corner
7701It is wise to put any pandoc operations under a timeout, to avoid DOS
7207It is wise to put any pandoc operations under a timeout, to avoid DOS
7702attacks that exploit these issues.
7208attacks that exploit these issues.
@@ -7708,16 +7214,16 @@ The HTML generated by pandoc is not guaranteed to be safe.
7708If \f[C]raw_html\f[R] is enabled for the Markdown input, users can
7214If \f[C]raw_html\f[R] is enabled for the Markdown input, users can
7709inject arbitrary HTML.
7215inject arbitrary HTML.
7710Even if \f[C]raw_html\f[R] is disabled, users can include dangerous
7216Even if \f[C]raw_html\f[R] is disabled, users can include dangerous
7711−content in URLs and attributes.
7217+content in attributes for headings, spans, and code blocks.
7712To be safe, you should run all the generated HTML through an HTML
7218To be safe, you should run all the generated HTML through an HTML
7713sanitizer.
7219sanitizer.
7714.SH AUTHORS
7220.SH AUTHORS
7716−Copyright 2006\[en]2021 John MacFarlane (jgm\[at]berkeley.edu).
7222+Copyright 2006--2020 John MacFarlane (jgm\[at]berkeley.edu).
7717Released under the GPL, version 2 or greater.
7223Released under the GPL, version 2 or greater.
7718This software carries no warranty of any kind.
7224This software carries no warranty of any kind.
7719(See COPYRIGHT for full copyright and warranty notices.) For a full list
7225(See COPYRIGHT for full copyright and warranty notices.) For a full list
7720of contributors, see the file AUTHORS.md in the pandoc source code.
7226of contributors, see the file AUTHORS.md in the pandoc source code.
7722The Pandoc source code and all documentation may be downloaded
7228The Pandoc source code and all documentation may be downloaded
7723−from <https://pandoc.org>.
7229+from <http://pandoc.org>.