@@ -1,13 +1,13 @@
1−'\" t
2−.\" Automatically generated by Pandoc 2.14.0.1
1+.\"t
2+.\" Automatically generated by Pandoc 2.9.2
33.\"
4−.TH "Pandoc User\[cq]s Guide" "" "June 20, 2021" "pandoc 2.14.0.3" ""
4+.TH "Pandoc User\[aq]s Guide" "" "March 23, 2020" "pandoc 2.9.2.1" ""
55.hy
66.SH NAME
77pandoc - general markup converter
88.SH SYNOPSIS
99.PP
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]]...
1111.SH DESCRIPTION
1212.PP
1313Pandoc 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]
2020and \f[C]--to\f[R] options below.
2121Pandoc can also produce PDF output: see creating a PDF, below.
2222.PP
23−Pandoc\[cq]s enhanced version of Markdown includes syntax for tables,
23+Pandoc\[aq]s enhanced version of Markdown includes syntax for tables,
2424definition lists, metadata blocks, footnotes, citations, math, and much
2525more.
26−See below under Pandoc\[cq]s Markdown.
26+See below under Pandoc\[aq]s Markdown.
2727.PP
2828Pandoc has a modular design: it consists of a set of readers, which
2929parse 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
3333writer.
3434Users can also run custom pandoc filters to modify the intermediate AST.
3535.PP
36−Because pandoc\[cq]s intermediate representation of a document is less
36+Because pandoc\[aq]s intermediate representation of a document is less
3737expressive than many of the formats it converts between, one should not
3838expect perfect conversions between every format and every other.
3939Pandoc attempts to preserve the structural elements of a document, but
4040not formatting details such as margin size.
4141And some document elements, such as complex tables, may not fit into
42−pandoc\[cq]s simple document model.
43−While conversions from pandoc\[cq]s Markdown to all formats aspire to be
44−perfect, conversions from formats more expressive than pandoc\[cq]s
42+pandoc\[aq]s simple document model.
43+While conversions from pandoc\[aq]s Markdown to all formats aspire to be
44+perfect, conversions from formats more expressive than pandoc\[aq]s
4545Markdown can be expected to be lossy.
4646.SS Using pandoc
4747.PP
@@ -57,9 +57,9 @@ pandoc -o output.html input.txt
5757.fi
5858.PP
5959By default, pandoc produces a document fragment.
60−To produce a standalone document (e.g.\ a valid HTML file including
61−\f[C]<head>\f[R] and \f[C]<body>\f[R]), use the \f[C]-s\f[R] or
62−\f[C]--standalone\f[R] flag:
60+To produce a standalone document (e.g.
61+a valid HTML file including \f[C]<head>\f[R] and \f[C]<body>\f[R]), use
62+the \f[C]-s\f[R] or \f[C]--standalone\f[R] flag:
6363.IP
6464.nf
6565\f[C]
@@ -115,10 +115,10 @@ pandoc -o hello.tex hello.txt
115115.PP
116116will convert \f[C]hello.txt\f[R] from Markdown to LaTeX.
117117If 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
119119output format will default to HTML.
120120If 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
122122input format will be assumed to be Markdown.
123123.SS Character encoding
124124.PP
@@ -172,15 +172,15 @@ You can then test it with \f[C]pdflatex test.tex\f[R].
172172When using LaTeX, the following packages need to be available (they are
173173included with all recent versions of TeX Live): \f[C]amsfonts\f[R],
174174\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
176−is used), \f[C]fancyvrb\f[R], \f[C]longtable\f[R], \f[C]booktabs\f[R],
177−\f[C]graphicx\f[R] (if the document contains images),
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
180−\f[C]linestretch\f[R]), and \f[C]babel\f[R] (with \f[C]lang\f[R]).
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],
177+\f[C]longtable\f[R], \f[C]booktabs\f[R], \f[C]graphicx\f[R] (if the
178+document contains images), \f[C]hyperref\f[R], \f[C]xcolor\f[R],
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
181+\f[C]babel\f[R] (with \f[C]lang\f[R]).
181182The use of \f[C]xelatex\f[R] or \f[C]lualatex\f[R] as the PDF engine
182183requires \f[C]fontspec\f[R].
183−\f[C]lualatex\f[R] uses \f[C]selnolig\f[R].
184184\f[C]xelatex\f[R] uses \f[C]polyglossia\f[R] (with \f[C]lang\f[R]),
185185\f[C]xecjk\f[R], and \f[C]bidi\f[R] (with the \f[C]dir\f[R] variable
186186set).
@@ -227,18 +227,10 @@ Specify input format.
227227\f[I]FORMAT\f[R] can be:
228228.RS
229229.IP \[bu] 2
230−\f[C]bibtex\f[R] (BibTeX bibliography)
231−.IP \[bu] 2
232−\f[C]biblatex\f[R] (BibLaTeX bibliography)
233−.IP \[bu] 2
234230\f[C]commonmark\f[R] (CommonMark Markdown)
235231.IP \[bu] 2
236−\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)
237−.IP \[bu] 2
238232\f[C]creole\f[R] (Creole 1.0)
239233.IP \[bu] 2
240−\f[C]csljson\f[R] (CSL JSON bibliography)
241−.IP \[bu] 2
242234\f[C]csv\f[R] (CSV table)
243235.IP \[bu] 2
244236\f[C]docbook\f[R] (DocBook)
@@ -263,13 +255,13 @@ if you need extensions not supported in \f[C]gfm\f[R].
263255.IP \[bu] 2
264256\f[C]jats\f[R] (JATS XML)
265257.IP \[bu] 2
266−\f[C]jira\f[R] (Jira/Confluence wiki markup)
258+\f[C]jira\f[R] (Jira wiki markup)
267259.IP \[bu] 2
268260\f[C]json\f[R] (JSON version of native AST)
269261.IP \[bu] 2
270262\f[C]latex\f[R] (LaTeX)
271263.IP \[bu] 2
272−\f[C]markdown\f[R] (Pandoc\[cq]s Markdown)
264+\f[C]markdown\f[R] (Pandoc\[aq]s Markdown)
273265.IP \[bu] 2
274266\f[C]markdown_mmd\f[R] (MultiMarkdown)
275267.IP \[bu] 2
@@ -319,18 +311,10 @@ Specify output format.
319311.IP \[bu] 2
320312\f[C]beamer\f[R] (LaTeX beamer slide show)
321313.IP \[bu] 2
322−\f[C]bibtex\f[R] (BibTeX bibliography)
323−.IP \[bu] 2
324−\f[C]biblatex\f[R] (BibLaTeX bibliography)
325−.IP \[bu] 2
326314\f[C]commonmark\f[R] (CommonMark Markdown)
327315.IP \[bu] 2
328−\f[C]commonmark_x\f[R] (CommonMark Markdown with extensions)
329−.IP \[bu] 2
330316\f[C]context\f[R] (ConTeXt)
331317.IP \[bu] 2
332−\f[C]csljson\f[R] (CSL JSON bibliography)
333−.IP \[bu] 2
334318\f[C]docbook\f[R] or \f[C]docbook4\f[R] (DocBook 4)
335319.IP \[bu] 2
336320\f[C]docbook5\f[R] (DocBook 5)
@@ -351,8 +335,8 @@ if you need extensions not supported in \f[C]gfm\f[R].
351335.IP \[bu] 2
352336\f[C]haddock\f[R] (Haddock markup)
353337.IP \[bu] 2
354−\f[C]html\f[R] or \f[C]html5\f[R] (HTML, i.e.\ HTML5/XHTML polyglot
355−markup)
338+\f[C]html\f[R] or \f[C]html5\f[R] (HTML, i.e.
339+HTML5/XHTML polyglot markup)
356340.IP \[bu] 2
357341\f[C]html4\f[R] (XHTML 1.0 Transitional)
358342.IP \[bu] 2
@@ -368,7 +352,7 @@ markup)
368352.IP \[bu] 2
369353\f[C]jats\f[R] (alias for \f[C]jats_archiving\f[R])
370354.IP \[bu] 2
371−\f[C]jira\f[R] (Jira/Confluence wiki markup)
355+\f[C]jira\f[R] (Jira wiki markup)
372356.IP \[bu] 2
373357\f[C]json\f[R] (JSON version of native AST)
374358.IP \[bu] 2
@@ -376,7 +360,7 @@ markup)
376360.IP \[bu] 2
377361\f[C]man\f[R] (roff man)
378362.IP \[bu] 2
379−\f[C]markdown\f[R] (Pandoc\[cq]s Markdown)
363+\f[C]markdown\f[R] (Pandoc\[aq]s Markdown)
380364.IP \[bu] 2
381365\f[C]markdown_mmd\f[R] (MultiMarkdown)
382366.IP \[bu] 2
@@ -457,15 +441,16 @@ On *nix and macOS systems this will be the \f[C]pandoc\f[R] subdirectory
457441of the XDG data directory (by default, \f[C]$HOME/.local/share\f[R],
458442overridable by setting the \f[C]XDG_DATA_HOME\f[R] environment
459443variable).
460−If that directory does not exist and \f[C]$HOME/.pandoc\f[R] exists, it
461−will be used (for backwards compatibility).
462−On Windows the default user data directory is
444+If that directory does not exist, \f[C]$HOME/.pandoc\f[R] will be used
445+(for backwards compatibility).
446+In Windows the default user data directory is
463447\f[C]C:\[rs]Users\[rs]USERNAME\[rs]AppData\[rs]Roaming\[rs]pandoc\f[R].
464448You can find the default user data directory on your system by looking
465449at 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],
468−\f[C]templates\f[R]) will override pandoc\[cq]s normal defaults.
450+A \f[C]reference.odt\f[R], \f[C]reference.docx\f[R], \f[C]epub.css\f[R],
451+\f[C]templates\f[R], \f[C]slidy\f[R], \f[C]slideous\f[R], or
452+\f[C]s5\f[R] directory placed in this directory will override
453+pandoc\[aq]s normal defaults.
469454.TP
470455\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]
471456Specify a set of default option settings.
@@ -496,6 +481,7 @@ eval \[dq]$(pandoc --bash-completion)\[dq]
496481.TP
497482\f[B]\f[CB]--verbose\f[B]\f[R]
498483Give verbose debugging output.
484+Currently this only has an effect with PDF output.
499485.TP
500486\f[B]\f[CB]--quiet\f[B]\f[R]
501487Suppress warning messages.
@@ -518,7 +504,7 @@ List supported output formats, one per line.
518504List supported extensions for \f[I]FORMAT\f[R], one per line, preceded
519505by a \f[C]+\f[R] or \f[C]-\f[R] indicating whether it is enabled by
520506default in \f[I]FORMAT\f[R].
521−If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[cq]s Markdown
507+If \f[I]FORMAT\f[R] is not specified, defaults for pandoc\[aq]s Markdown
522508are given.
523509.TP
524510\f[B]\f[CB]--list-highlight-languages\f[B]\f[R]
@@ -563,7 +549,7 @@ This option is useful for converting word processing documents where
563549users have used empty paragraphs to create inter-paragraph space.
564550.TP
565551\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,
552+Specify classes to use for indented code blocks--for example,
567553\f[C]perl,numberLines\f[R] or \f[C]haskell\f[R].
568554Multiple classes may be separated by spaces or commas.
569555.TP
@@ -585,7 +571,7 @@ Reading binary files (docx, odt, epub) implies \f[C]--file-scope\f[R].
585571Specify an executable to be used as a filter transforming the pandoc AST
586572after the input is parsed and before the output is written.
587573The 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.
574+The JSON must be formatted like pandoc\[aq]s own JSON input and output.
589575The name of the output format will be passed to the filter as the first
590576argument.
591577Hence,
@@ -625,13 +611,13 @@ above).
625611.IP "3." 3
626612\f[C]$PATH\f[R] (executable only)
627613.PP
628−Filters, Lua-filters, and citeproc processing are applied in the order
629−specified on the command line.
614+Filters and Lua-filters are applied in the order specified on the
615+command line.
630616.RE
631617.TP
632618\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]
633619Transform 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.
620+\f[C]--filter\f[R]), but use pandoc\[aq]s build-in Lua filtering system.
635621The given Lua script is expected to return a list of Lua filters which
636622will be applied in order.
637623Each Lua filter must contain element-transforming functions indexed by
@@ -641,19 +627,31 @@ applied.
641627.PP
642628The \f[C]pandoc\f[R] Lua module provides helper functions for element
643629creation.
644−It is always loaded into the script\[cq]s Lua environment.
630+It is always loaded into the script\[aq]s Lua environment.
645631.PP
646−See the Lua filters documentation for further details.
632+The following is an example Lua script for macro-expansion:
633+.IP
634+.nf
635+\f[C]
636+function expand_hello_world(inline)
637+ if inline.c == \[aq]{{helloworld}}\[aq] then
638+ return pandoc.Emph{ pandoc.Str \[dq]Hello, World\[dq] }
639+ else
640+ return inline
641+ end
642+end
643+
644+return {{Str = expand_hello_world}}
645+\f[R]
646+.fi
647647.PP
648648In order of preference, pandoc will look for Lua filters in
649649.IP "1." 3
650−a specified full or relative path
650+a specified full or relative path (executable or non-executable)
651651.IP "2." 3
652−\f[C]$DATADIR/filters\f[R] where \f[C]$DATADIR\f[R] is the user data
653−directory (see \f[C]--data-dir\f[R], above).
654−.PP
655−Filters, Lua filters, and citeproc processing are applied in the order
656−specified on the command line.
652+\f[C]$DATADIR/filters\f[R] (executable or non-executable) where
653+\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
654+above).
657655.RE
658656.TP
659657\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 +691,13 @@ Specify the number of spaces per tab (default is 4).
693691.TP
694692\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]
695693Specifies what to do with insertions, deletions, and comments produced
696−by the MS Word \[lq]Track Changes\[rq] feature.
697−\f[C]accept\f[R] (the default) processes all the insertions and
694+by the MS Word \[dq]Track Changes\[dq] feature.
695+\f[C]accept\f[R] (the default), inserts all insertions, and ignores all
698696deletions.
699−\f[C]reject\f[R] ignores them.
697+\f[C]reject\f[R] inserts all deletions and ignores insertions.
700698Both \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−in spans with \f[C]insertion\f[R], \f[C]deletion\f[R],
699+\f[C]all\f[R] puts in insertions, deletions, and comments, wrapped in
700+spans with \f[C]insertion\f[R], \f[C]deletion\f[R],
703701\f[C]comment-start\f[R], and \f[C]comment-end\f[R] classes,
704702respectively.
705703The author and time of change is included.
@@ -716,11 +714,11 @@ Extract images and other media contained in or linked from the source
716714document to the path \f[I]DIR\f[R], creating it if necessary, and adjust
717715the images references in the document so they point to the extracted
718716files.
719−Media are downloaded, read from the file system, or extracted from a
720−binary container (e.g.\ docx), as needed.
721−The original file paths are used if they are relative paths not
722−containing \f[C]..\f[R].
723−Otherwise filenames are constructed from the SHA1 hash of the contents.
717+If the source format is a binary container (docx, epub, or odt), the
718+media is extracted from the container and the original filenames are
719+used.
720+Otherwise the media is read from the file system or downloaded, and new
721+filenames are constructed based on SHA1 hashes of the contents.
724722.TP
725723\f[B]\f[CB]--abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
726724Specifies a custom abbreviations file, with abbreviations one to a line.
@@ -730,14 +728,14 @@ system default.
730728To see the system default, use
731729\f[C]pandoc --print-default-data-file=abbreviations\f[R].
732730The 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−the period will not produce sentence-ending space in formats like LaTeX.
735−The strings may not contain spaces.
731+Strings ending in a period that are found in this list will be followed
732+by a nonbreaking space, so that the period will not produce
733+sentence-ending space in formats like LaTeX.
736734.SS General writer options
737735.TP
738736\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−HTML, LaTeX, TEI, or RTF file, not a fragment).
737+Produce output with an appropriate header and footer (e.g.
738+a standalone HTML, LaTeX, TEI, or RTF file, not a fragment).
741739This option is set automatically for \f[C]pdf\f[R], \f[C]epub\f[R],
742740\f[C]epub3\f[R], \f[C]fb2\f[R], \f[C]docx\f[R], and \f[C]odt\f[R]
743741output.
@@ -897,7 +895,8 @@ Implies \f[C]--standalone\f[R].
897895.TP
898896\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]
899897Include 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
898+document body (e.g.
899+after the \f[C]<body>\f[R] tag in HTML, or the
901900\f[C]\[rs]begin{document}\f[R] command in LaTeX).
902901This can be used to include navigation bars or banners in HTML
903902documents.
@@ -923,23 +922,20 @@ Note that, if \f[C]--resource-path\f[R] is specified, the working
923922directory must be explicitly listed or it will not be searched.
924923For example: \f[C]--resource-path=.:test\f[R] will search the working
925924directory and the \f[C]test\f[R] subdirectory, in that order.
926−This option can be used repeatedly.
927−Search path components that come later on the command line will be
928−searched before those that come earlier, so
929−\f[C]--resource-path foo:bar --resource-path baz:bim\f[R] is equivalent
930−to \f[C]--resource-path baz:bim:foo:bar\f[R].
925+.RS
926+.PP
927+\f[C]--resource-path\f[R] only has an effect if (a) the output format
928+embeds images (for example, \f[C]docx\f[R], \f[C]pdf\f[R], or
929+\f[C]html\f[R] with \f[C]--self-contained\f[R]) or (b) it is used
930+together with \f[C]--extract-media\f[R].
931+.RE
931932.TP
932933\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]
933934Set the request header \f[I]NAME\f[R] to the value \f[I]VAL\f[R] when
934935making HTTP requests (for example, when a URL is given on the command
935936line, 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
937+If you\[aq]re behind a proxy, you also need to set the environment
937938variable \f[C]http_proxy\f[R] to \f[C]http://...\f[R].
938−.TP
939−\f[B]\f[CB]--no-check-certificate\f[B]\f[R]
940−Disable the certificate verification to allow access to unsecure HTTP
941−resources (for example when the certificate is no longer valid or self
942−signed).
943939.SS Options affecting specific writers
944940.TP
945941\f[B]\f[CB]--self-contained\f[B]\f[R]
@@ -947,7 +943,7 @@ Produce a standalone HTML file with no external dependencies, using
947943\f[C]data:\f[R] URIs to incorporate the contents of linked scripts,
948944stylesheets, images, and videos.
949945Implies \f[C]--standalone\f[R].
950−The resulting file should be \[lq]self-contained,\[rq] in the sense that
946+The resulting file should be \[dq]self-contained,\[dq] in the sense that
951947it needs no external files and no net access to be displayed properly by
952948a browser.
953949This option works only with HTML output formats, including
@@ -963,14 +959,12 @@ left alone; the documents they link to will not be incorporated in the
963959document.
964960Limitation: resources that are loaded dynamically through JavaScript
965961cannot 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
967−speaker notes) may not work in an offline \[lq]self-contained\[rq]
968−\f[C]reveal.js\f[R] slide show.
962+work with \f[C]--mathjax\f[R], and some advanced features (e.g.
963+zoom or speaker notes) may not work in an offline
964+\[dq]self-contained\[dq] \f[C]reveal.js\f[R] slide show.
969965.TP
970966\f[B]\f[CB]--html-q-tags\f[B]\f[R]
971967Use \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.)
974968.TP
975969\f[B]\f[CB]--ascii\f[B]\f[R]
976970Use only ASCII characters in output.
@@ -988,24 +982,21 @@ By default inline links are used.
988982The placement of link references is affected by the
989983\f[C]--reference-location\f[R] option.
990984.TP
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]
985+\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]
992986Specify whether footnotes (and references, if \f[C]reference-links\f[R]
993987is set) are placed at the end of the current (top-level) block, the
994988current section, or the document.
995989The default is \f[C]document\f[R].
996990Currently only affects the markdown writer.
997991.TP
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
1002−levels 3+.
1003−This option also affects Markdown cells in \f[C]ipynb\f[R] output.
1004−.TP
1005992\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]
993+Use ATX-style headings in Markdown output.
994+The default is to use setext-style headings for levels 1 to 2, and then
995+ATX headings.
996+(Note: for \f[C]gfm\f[R] output, ATX headings are always used.) This
997+option also affects markdown cells in \f[C]ipynb\f[R] output.
1007998.TP
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]
999+\f[B]\f[CB]--top-level-division=[default|section|chapter|part]\f[B]\f[R]
10091000Treat top-level headings as the given division type in LaTeX, ConTeXt,
10101001DocBook, and TEI output.
10111002The hierarchy order is part, chapter, then section; all headings are
@@ -1022,22 +1013,21 @@ become \f[C]\[rs]part{..}\f[R], while second-level headings remain as
10221013their default type.
10231014.TP
10241015\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
1026−output.
1016+Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
10271017By default, sections are not numbered.
10281018Sections with class \f[C]unnumbered\f[R] will never be numbered, even if
10291019\f[C]--number-sections\f[R] is specified.
10301020.TP
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]]
1021+\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]]
10321022Offset for section headings in HTML output (ignored in other output
10331023formats).
10341024The first number is added to the section number for top-level headings,
10351025the second for second-level headings, and so on.
10361026So, for example, if you want the first top-level heading in your
1037−document to be numbered \[lq]6\[rq], specify
1027+document to be numbered \[dq]6\[dq], specify
10381028\f[C]--number-offset=5\f[R].
10391029If 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].
1030+numbered \[dq]1.5\[dq], specify \f[C]--number-offset=1,4\f[R].
10411031Offsets are 0 by default.
10421032Implies \f[C]--number-sections\f[R].
10431033.TP
@@ -1202,8 +1192,6 @@ Verbatim Char
12021192Footnote Reference
12031193.IP \[bu] 2
12041194Hyperlink
1205−.IP \[bu] 2
1206−Section Number
12071195.PP
12081196Table style:
12091197.IP \[bu] 2
@@ -1336,7 +1324,7 @@ body { font-family: \[dq]DejaVuSans\[dq]; }
13361324.TP
13371325\f[B]\f[CB]--epub-chapter-level=\f[B]\f[R]\f[I]NUMBER\f[R]
13381326Specify the heading level at which to split the EPUB into separate
1339−\[lq]chapter\[rq] files.
1327+\[dq]chapter\[dq] files.
13401328The default is to split into chapters at level-1 headings.
13411329This option only affects the internal composition of the EPUB, not the
13421330way chapters and sections are displayed to users.
@@ -1378,8 +1366,7 @@ depending on the output format specified using \f[C]-t/--to\f[R]:
13781366\f[C]-t context\f[R]: \f[C]context\f[R]
13791367.IP \[bu] 2
13801368\f[C]-t html\f[R]: \f[C]wkhtmltopdf\f[R] (other options:
1381−\f[C]prince\f[R], \f[C]weasyprint\f[R]; see print-css.rocks for a good
1382−introduction to PDF generation from HTML/CSS.)
1369+\f[C]prince\f[R], \f[C]weasyprint\f[R])
13831370.IP \[bu] 2
13841371\f[C]-t ms\f[R]: \f[C]pdfroff\f[R]
13851372.RE
@@ -1388,69 +1375,47 @@ introduction to PDF generation from HTML/CSS.)
13881375Use the given string as a command-line argument to the
13891376\f[C]pdf-engine\f[R].
13901377For example, to use a persistent directory \f[C]foo\f[R] for
1391−\f[C]latexmk\f[R]\[cq]s auxiliary files, use
1378+\f[C]latexmk\f[R]\[aq]s auxiliary files, use
13921379\f[C]--pdf-engine-opt=-outdir=foo\f[R].
13931380Note that no check for duplicate options is done.
13941381.SS Citation rendering
13951382.TP
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.
1412−.TP
14131383\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
1415−\f[I]FILE\f[R], overriding any value set in the metadata.
1384+Set the \f[C]bibliography\f[R] field in the document\[aq]s metadata to
1385+\f[I]FILE\f[R], overriding any value set in the metadata, and process
1386+citations using \f[C]pandoc-citeproc\f[R].
1387+(This is equivalent to
1388+\f[C]--metadata bibliography=FILE --filter pandoc-citeproc\f[R].) If
1389+\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] is also supplied,
1390+\f[C]pandoc-citeproc\f[R] is not used, making this equivalent to
1391+\f[C]--metadata bibliography=FILE\f[R].
14161392If you supply this argument multiple times, each \f[I]FILE\f[R] will be
14171393added 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]).
14211394.TP
14221395\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
1396+Set the \f[C]csl\f[R] field in the document\[aq]s metadata to
14241397\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]
1426−is a URL, it will be fetched via HTTP.
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
1430−directory.
1398+(This is equivalent to \f[C]--metadata csl=FILE\f[R].) This option is
1399+only relevant with \f[C]pandoc-citeproc\f[R].
14311400.TP
14321401\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
1402+Set the \f[C]citation-abbreviations\f[R] field in the document\[aq]s
14341403metadata to \f[I]FILE\f[R], overriding any value set in the metadata.
14351404(This is equivalent to
1436−\f[C]--metadata citation-abbreviations=FILE\f[R].) If \f[I]FILE\f[R] is
1437−a URL, it will be fetched via HTTP.
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
1441−directory.
1405+\f[C]--metadata citation-abbreviations=FILE\f[R].) This option is only
1406+relevant with \f[C]pandoc-citeproc\f[R].
14421407.TP
14431408\f[B]\f[CB]--natbib\f[B]\f[R]
14441409Use \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
1446−PDF output.
1410+This option is not for use with the \f[C]pandoc-citeproc\f[R] filter or
1411+with PDF output.
14471412It is intended for use in producing a LaTeX file that can be processed
14481413with \f[C]bibtex\f[R].
14491414.TP
14501415\f[B]\f[CB]--biblatex\f[B]\f[R]
14511416Use \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
1453−PDF output.
1417+This option is not for use with the \f[C]pandoc-citeproc\f[R] filter or
1418+with PDF output.
14541419It is intended for use in producing a LaTeX file that can be processed
14551420with \f[C]bibtex\f[R] or \f[C]biber\f[R].
14561421.SS Math rendering in HTML
@@ -1491,7 +1456,7 @@ For SVG images you can for example use
14911456If no URL is specified, the CodeCogs URL generating PNGs will be used
14921457(\f[C]https://latex.codecogs.com/png.latex?\f[R]).
14931458Note: 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
1459+as HTML, which is useful if you\[aq]re targeting a version of Markdown
14951460without native math support.
14961461.TP
14971462\f[B]\f[CB]--katex\f[B]\f[R][\f[B]\f[CB]=\f[B]\f[R]\f[I]URL\f[R]]
@@ -1504,16 +1469,16 @@ inserted.
15041469.TP
15051470\f[B]\f[CB]--gladtex\f[B]\f[R]
15061471Enclose 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
1508−images of the typeset formulas and an HTML file with these images
1509−embedded.
1472+The resulting HTML can then be processed by GladTeX to produce images of
1473+the typeset formulas and an HTML file with links to these images.
1474+So, the procedure is:
15101475.RS
15111476.IP
15121477.nf
15131478\f[C]
15141479pandoc -s --gladtex input.md -o myfile.htex
1515−gladtex -d image_dir myfile.htex
1516−# produces myfile.html and images in image_dir
1480+gladtex -d myfile-images myfile.htex
1481+# produces myfile.html and images in myfile-images
15171482\f[R]
15181483.fi
15191484.RE
@@ -1602,11 +1567,6 @@ T}@T{
16021567PandocUnsupportedExtensionError
16031568T}
16041569T{
1605−24
1606−T}@T{
1607−PandocCiteprocError
1608−T}
1609−T{
1610157031
16111571T}@T{
16121572PandocEpubSubdirectoryError
@@ -1617,11 +1577,6 @@ T}@T{
16171577PandocPDFError
16181578T}
16191579T{
1620−44
1621−T}@T{
1622−PandocXMLError
1623−T}
1624−T{
1625158047
16261581T}@T{
16271582PandocPDFProgramNotFoundError
@@ -1682,11 +1637,6 @@ T}@T{
16821637PandocIpynbDecodingError
16831638T}
16841639T{
1685−94
1686−T}@T{
1687−PandocUnsupportedCharsetError
1688−T}
1689−T{
1690164097
16911641T}@T{
16921642PandocCouldNotFindDataFileError
@@ -1719,16 +1669,6 @@ input-files:
17191669- content.md
17201670# or you may use input-file: with a single value
17211671
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.
1728−defaults:
1729−- defsA
1730−- defsB
1731−
17321672template: letter
17331673standalone: true
17341674self-contained: false
@@ -1756,24 +1696,11 @@ include-after-body: []
17561696include-in-header: []
17571697resource-path: [\[dq].\[dq]]
17581698
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).
1763−citeproc: true
1764−csl: ieee
1765−bibliography:
1766−- foobar.bib
1767−- barbaz.json
1768−citation-abbreviations: abbrevs.json
1769−
1770−# Filters will be assumed to be Lua filters if they have
1699+# filters will be assumed to be Lua filters if they have
17711700# the .lua extension, and json filters otherwise. But
1772−# 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].
1701+# the filter type can also be specified explicitly, as shown:
17761702filters:
1703+- pandoc-citeproc
17771704- wordcount.lua
17781705- type: json
17791706 path: foo.lua
@@ -1786,11 +1713,8 @@ data-dir:
17861713verbosity: INFO
17871714log-file: log.json
17881715
1789−# citeproc, natbib, or biblatex. This only affects LaTeX
1790−# output. If you want to use citeproc to format citations,
1791−# you should also set \[aq]citeproc: true\[aq] (see above).
1716+# citeproc, natbib, or biblatex
17921717cite-method: citeproc
1793−
17941718# part, chapter, section, or default:
17951719top-level-division: chapter
17961720abbreviations:
@@ -1859,7 +1783,7 @@ epub-cover-image: cover.jpg
18591783reference-links: true
18601784# block, section, or document
18611785reference-location: block
1862−markdown-headings: setext
1786+atx-headers: false
18631787
18641788# accept, reject, or all
18651789track-changes: accept
@@ -1891,38 +1815,6 @@ verbosity: INFO
18911815\f[R]
18921816.fi
18931817.PP
1894−In fields that expect a file path (or list of file paths), the following
1895−syntax may be used to interpolate environment variables:
1896−.IP
1897−.nf
1898−\f[C]
1899−csl: ${HOME}/mycsldir/special.csl
1900−\f[R]
1901−.fi
1902−.PP
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
1906−\f[C]USERDATA\f[R].
1907−.PP
1908−\f[C]${.}\f[R] will resolve to the directory containing the default file
1909−itself.
1910−This allows you to refer to resources contained in that directory:
1911−.IP
1912−.nf
1913−\f[C]
1914−epub-cover-image: ${.}/cover.jpg
1915−epub-metadata: ${.}/meta.xml
1916−resource-path:
1917−- . # the working directory from which pandoc is run
1918−- ${.}/images # the images subdirectory of the directory
1919− # containing this defaults file
1920−\f[R]
1921−.fi
1922−.PP
1923−This environment variable interpolation syntax \f[I]only\f[R] works in
1924−fields that expect file paths.
1925−.PP
19261818Default files can be placed in the \f[C]defaults\f[R] subdirectory of
19271819the user data directory and used from any directory.
19281820For example, one could create a file specifying defaults for writing
@@ -1979,10 +1871,10 @@ arbitrary information at any point in the file.
19791871They may be set at the command line using the \f[C]-V/--variable\f[R]
19801872option.
19811873If 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
1874+document\[aq]s metadata, which can be set using either YAML metadata
19831875blocks or with the \f[C]-M/--metadata\f[R] option.
19841876In addition, some variables are given default values by pandoc.
1985−See Variables below for a list of variables used in pandoc\[cq]s default
1877+See Variables below for a list of variables used in pandoc\[aq]s default
19861878templates.
19871879.PP
19881880If you use custom templates, you may need to revise them as pandoc
@@ -1999,8 +1891,8 @@ be treated as a comment and omitted from the output.
19991891.SS Delimiters
20001892.PP
20011893To 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
2003−as delimiters.
1894+\f[C]$\f[R]...\f[C]$\f[R] or \f[C]${\f[R]...\f[C]}\f[R] may be used as
1895+delimiters.
20041896The styles may also be mixed in the same template, but the opening and
20051897closing delimiter must match in each case.
20061898The opening delimiter may be followed by one or more spaces or tabs,
@@ -2161,29 +2053,19 @@ ${ endfor }
21612053.fi
21622054.SS Partials
21632055.PP
2164−Partials (subtemplates stored in different files) may be included by
2165−using the name of the partial, followed by \f[C]()\f[R], for example:
2166−.IP
2167−.nf
2168−\f[C]
2169−${ styles() }
2170−\f[R]
2171−.fi
2172−.PP
2173−Partials will be sought in the directory containing the main template.
2174−The file name will be assumed to have the same extension as the main
2175−template if it lacks an extension.
2176−When calling the partial, the full name including file extension can
2177−also be used:
2056+Partials (subtemplates stored in different files) may be included using
2057+the syntax
21782058.IP
21792059.nf
21802060\f[C]
2181−${ styles.html() }
2061+${ boilerplate() }
21822062\f[R]
21832063.fi
21842064.PP
2185−(If a partial is not found in the directory of the template and the
2186−template path is given as a relative path, it will also be sought in the
2065+Partials will be sought in the directory containing the main template,
2066+and will be assumed to have the same extension as the main template if
2067+they lack an explicit extension.
2068+(If the partials are not found here, they will also be sought in the
21872069\f[C]templates\f[R] subdirectory of the user data directory.)
21882070.PP
21892071Partials may optionally be applied to variables using a colon:
@@ -2233,7 +2115,7 @@ an explicit \f[C]for\f[R] loop) cannot contain interpolated variables or
22332115other template directives.
22342116.SS Nesting
22352117.PP
2236−To ensure that content is \[lq]nested,\[rq] that is, subsequent lines
2118+To ensure that content is \[dq]nested,\[dq] that is, subsequent lines
22372119indented, use the \f[C]\[ha]\f[R] directive:
22382120.IP
22392121.nf
@@ -2275,7 +2157,7 @@ will produce
22752157.PP
22762158If a variable occurs by itself on a line, preceded by whitespace and not
22772159followed by further text or directives on the same line, and the
2278−variable\[cq]s value contains multiple lines, it will be nested
2160+variable\[aq]s value contains multiple lines, it will be nested
22792161automatically.
22802162.SS Breakable spaces
22812163.PP
@@ -2350,18 +2232,6 @@ for a textual value, number of elements for a map or array.
23502232\f[C]reverse\f[R]: Reverses a textual value or array, and has no effect
23512233on other values.
23522234.IP \[bu] 2
2353−\f[C]first\f[R]: Returns the first value of an array, if applied to a
2354−non-empty array; otherwise returns the original value.
2355−.IP \[bu] 2
2356−\f[C]last\f[R]: Returns the last value of an array, if applied to a
2357−non-empty array; otherwise returns the original value.
2358−.IP \[bu] 2
2359−\f[C]rest\f[R]: Returns all but the first value of an array, if applied
2360−to a non-empty array; otherwise returns the original value.
2361−.IP \[bu] 2
2362−\f[C]allbutlast\f[R]: Returns all but the last value of an array, if
2363−applied to a non-empty array; otherwise returns the original value.
2364−.IP \[bu] 2
23652235\f[C]chomp\f[R]: Removes trailing newlines (and breakable space).
23662236.IP \[bu] 2
23672237\f[C]nowrap\f[R]: Disables line wrapping on breakable spaces.
@@ -2417,8 +2287,7 @@ including a title block in the document itself, you can set the
24172287\f[C]title-meta\f[R], \f[C]author-meta\f[R], and \f[C]date-meta\f[R]
24182288variables.
24192289(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
2421−\f[C]pagetitle\f[R], which is equal to \f[C]title\f[R] by default.
2290+\f[C]author\f[R], and \f[C]date\f[R].)
24222291.RE
24232292.TP
24242293\f[B]\f[CB]subtitle\f[B]\f[R]
@@ -2508,81 +2377,13 @@ For bidirectional documents, native pandoc \f[C]span\f[R]s and
25082377\f[C]div\f[R]s with the \f[C]dir\f[R] attribute (value \f[C]rtl\f[R] or
25092378\f[C]ltr\f[R]) can be used to override the base direction in some output
25102379formats.
2511−This may not always be necessary if the final renderer (e.g.\ the
2512−browser, when generating HTML) supports the Unicode Bidirectional
2380+This may not always be necessary if the final renderer (e.g.
2381+the browser, when generating HTML) supports the Unicode Bidirectional
25132382Algorithm.
25142383.PP
25152384When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[R]
25162385engine is fully supported (use \f[C]--pdf-engine=xelatex\f[R]).
25172386.RE
2518−.SS Variables for HTML
2519−.TP
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]
2525−by default.
2526−You can disable it with e.g.\ \f[C]pandoc -M document-css=false\f[R].
2527−.TP
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]
2530−element.
2531−.TP
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
2535−most browsers).
2536−.TP
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.
2539−.TP
2540−\f[B]\f[CB]linkcolor\f[B]\f[R]
2541−sets the CSS \f[C]color\f[R] property on all links.
2542−.TP
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.
2545−.TP
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.
2549−.TP
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.
2553−.TP
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]
2556−element.
2557−.TP
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.
2561−.PP
2562−To override or extend some CSS for just one document, include for
2563−example:
2564−.IP
2565−.nf
2566−\f[C]
2567−---
2568−header-includes: |
2569− <style>
2570− blockquote {
2571− font-style: italic;
2572− }
2573− tr.even {
2574− background-color: #f0f0f0;
2575− }
2576− td, th {
2577− padding: 0.5em 2em 0.5em 0.5em;
2578− }
2579− tbody {
2580− border-bottom: none;
2581− }
2582− </style>
2583−---
2584−\f[R]
2585−.fi
25862387.SS Variables for HTML math
25872388.TP
25882389\f[B]\f[CB]classoption\f[B]\f[R]
@@ -2590,14 +2391,14 @@ when using KaTeX, you can render display math equations flush left using
25902391YAML metadata or with \f[C]-M classoption=fleqn\f[R].
25912392.SS Variables for HTML slides
25922393.PP
2593−These affect HTML output when [producing slide shows with pandoc].
2594−.TP
2595−\f[B]\f[CB]institute\f[B]\f[R]
2596−author affiliations: can be a list when there are multiple authors
2394+These affect HTML output when producing slide shows with pandoc.
2395+.PP
2396+All reveal.js configuration options are available as variables.
2397+To turn off boolean flags that default to true in reveal.js, use
2398+\f[C]0\f[R].
25972399.TP
25982400\f[B]\f[CB]revealjs-url\f[B]\f[R]
2599−base URL for reveal.js documents (defaults to
2600−\f[C]https://unpkg.com/reveal.js\[at]\[ha]4/\f[R])
2401+base URL for reveal.js documents (defaults to \f[C]reveal.js\f[R])
26012402.TP
26022403\f[B]\f[CB]s5-url\f[B]\f[R]
26032404base URL for S5 documents (defaults to \f[C]s5/default\f[R])
@@ -2612,10 +2413,6 @@ base URL for Slideous documents (defaults to \f[C]slideous\f[R])
26122413\f[B]\f[CB]title-slide-attributes\f[B]\f[R]
26132414additional attributes for the title slide of reveal.js slide shows.
26142415See background in reveal.js and beamer for an example.
2615−.PP
2616−All reveal.js configuration options are available as variables.
2617−To turn off boolean flags that default to true in reveal.js, use
2618−\f[C]0\f[R].
26192416.SS Variables for Beamer slides
26202417.PP
26212418These variables change the appearance of PDF slides using
@@ -2644,7 +2441,7 @@ navigation symbols; other valid values are \f[C]frame\f[R],
26442441\f[C]vertical\f[R], and \f[C]horizontal\f[R])
26452442.TP
26462443\f[B]\f[CB]section-titles\f[B]\f[R]
2647−enables \[lq]title pages\[rq] for new sections (default is true)
2444+enables \[dq]title pages\[dq] for new sections (default is true)
26482445.TP
26492446\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]
26502447beamer themes
@@ -2696,8 +2493,8 @@ header-includes: |
26962493.RE
26972494.TP
26982495\f[B]\f[CB]classoption\f[B]\f[R]
2699−option for document class, e.g.\ \f[C]oneside\f[R]; repeat for multiple
2700−options:
2496+option for document class, e.g.
2497+\f[C]oneside\f[R]; repeat for multiple options:
27012498.RS
27022499.IP
27032500.nf
@@ -2718,8 +2515,8 @@ document class: usually one of the standard classes, \f[C]article\f[R],
27182515default to smaller margins; or \f[C]memoir\f[R]
27192516.TP
27202517\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];
2722−repeat for multiple options:
2518+option for \f[C]geometry\f[R] package, e.g.
2519+\f[C]margin=1in\f[R]; repeat for multiple options:
27232520.RS
27242521.IP
27252522.nf
@@ -2735,8 +2532,8 @@ geometry:
27352532.RE
27362533.TP
27372534\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];
2739−repeat for multiple options:
2535+option for \f[C]hyperref\f[R] package, e.g.
2536+\f[C]linktoc=all\f[R]; repeat for multiple options:
27402537.RS
27412538.IP
27422539.nf
@@ -2752,13 +2549,12 @@ hyperrefoptions:
27522549.RE
27532550.TP
27542551\f[B]\f[CB]indent\f[B]\f[R]
2755−if true, pandoc will use document class settings for indentation (the
2756−default LaTeX template otherwise removes indentation and adds space
2757−between paragraphs)
2552+uses document class settings for indentation (the default LaTeX template
2553+otherwise removes indentation and adds space between paragraphs)
27582554.TP
27592555\f[B]\f[CB]linestretch\f[B]\f[R]
2760−adjusts line spacing using the \f[C]setspace\f[R] package,
2761−e.g.\ \f[C]1.25\f[R], \f[C]1.5\f[R]
2556+adjusts line spacing using the \f[C]setspace\f[R] package, e.g.
2557+\f[C]1.25\f[R], \f[C]1.5\f[R]
27622558.TP
27632559\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]
27642560sets margins if \f[C]geometry\f[R] is not used (otherwise
@@ -2770,7 +2566,8 @@ control \f[C]\[rs]pagestyle{}\f[R]: the default article class supports
27702566numbers), and \f[C]headings\f[R] (section titles in running heads)
27712567.TP
27722568\f[B]\f[CB]papersize\f[B]\f[R]
2773−paper size, e.g.\ \f[C]letter\f[R], \f[C]a4\f[R]
2569+paper size, e.g.
2570+\f[C]letter\f[R], \f[C]a4\f[R]
27742571.TP
27752572\f[B]\f[CB]secnumdepth\f[B]\f[R]
27762573numbering depth for sections (with \f[C]--number-sections\f[R] option or
@@ -2895,32 +2692,35 @@ list of options for natbib
28952692Pandoc uses these variables when creating a PDF with ConTeXt.
28962693.TP
28972694\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])
2695+font size for body text (e.g.
2696+\f[C]10pt\f[R], \f[C]12pt\f[R])
28992697.TP
29002698\f[B]\f[CB]headertext\f[B]\f[R], \f[B]\f[CB]footertext\f[B]\f[R]
29012699text to be placed in running header or footer (see ConTeXt Headers and
29022700Footers); repeat up to four times for different placement
29032701.TP
29042702\f[B]\f[CB]indenting\f[B]\f[R]
2905−controls indentation of paragraphs, e.g.\ \f[C]yes,small,next\f[R] (see
2906−ConTeXt Indentation); repeat for multiple options
2703+controls indentation of paragraphs, e.g.
2704+\f[C]yes,small,next\f[R] (see ConTeXt Indentation); repeat for multiple
2705+options
29072706.TP
29082707\f[B]\f[CB]interlinespace\f[B]\f[R]
2909−adjusts line spacing, e.g.\ \f[C]4ex\f[R] (using
2910−\f[C]setupinterlinespace\f[R]); repeat for multiple options
2708+adjusts line spacing, e.g.
2709+\f[C]4ex\f[R] (using \f[C]setupinterlinespace\f[R]); repeat for multiple
2710+options
29112711.TP
29122712\f[B]\f[CB]layout\f[B]\f[R]
29132713options for page margins and text arrangement (see ConTeXt Layout);
29142714repeat for multiple options
29152715.TP
29162716\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],
2918−\f[C]blue\f[R] (see ConTeXt Color)
2717+color for links outside and inside a page, e.g.
2718+\f[C]red\f[R], \f[C]blue\f[R] (see ConTeXt Color)
29192719.TP
29202720\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],
2922−\f[C]slanted\f[R], \f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R],
2923−\f[C]small\f[R]
2721+typeface style for links, e.g.
2722+\f[C]normal\f[R], \f[C]bold\f[R], \f[C]slanted\f[R],
2723+\f[C]boldslanted\f[R], \f[C]type\f[R], \f[C]cap\f[R], \f[C]small\f[R]
29242724.TP
29252725\f[B]\f[CB]lof\f[B]\f[R], \f[B]\f[CB]lot\f[B]\f[R]
29262726include list of figures, list of tables
@@ -2938,13 +2738,16 @@ page number style and location (using \f[C]setuppagenumbering\f[R]);
29382738repeat for multiple options
29392739.TP
29402740\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]
2942−(see ConTeXt Paper Setup); repeat for multiple options
2741+paper size, e.g.
2742+\f[C]letter\f[R], \f[C]A4\f[R], \f[C]landscape\f[R] (see ConTeXt Paper
2743+Setup); repeat for multiple options
29432744.TP
29442745\f[B]\f[CB]pdfa\f[B]\f[R]
29452746adds 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].
2947−If no type is specified (i.e.\ the value is set to True, by e.g.
2747+specified, e.g.
2748+\f[C]1a:2005\f[R], \f[C]2a\f[R].
2749+If no type is specified (i.e.
2750+the value is set to True, by e.g.
29482751\f[C]--metadata=pdfa\f[R] or \f[C]pdfa: true\f[R] in a YAML metadata
29492752block), \f[C]1b:2005\f[R] will be used as default, for reasons of
29502753backwards compatibility.
@@ -2959,7 +2762,8 @@ See also ConTeXt PDFA for more details.
29592762.TP
29602763\f[B]\f[CB]pdfaiccprofile\f[B]\f[R]
29612764when 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].
2765+to use in the PDF, e.g.
2766+\f[C]default.cmyk\f[R].
29632767If left unspecified, \f[C]sRGB.icc\f[R] is used as default.
29642768May be repeated to include multiple profiles.
29652769Note that the profiles have to be available on the system.
@@ -2967,17 +2771,17 @@ They can be obtained from ConTeXt ICC Profiles.
29672771.TP
29682772\f[B]\f[CB]pdfaintent\f[B]\f[R]
29692773when used in conjunction with \f[C]pdfa\f[R], specifies the output
2970−intent for the colors,
2971−e.g.\ \f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If
2972−left unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.
2774+intent for the colors, e.g.
2775+\f[C]ISO coated v2 300\[rs]letterpercent\[rs]space (ECI)\f[R] If left
2776+unspecified, \f[C]sRGB IEC61966-2.1\f[R] is used as default.
29732777.TP
29742778\f[B]\f[CB]toc\f[B]\f[R]
29752779include table of contents (can also be set using
29762780\f[C]--toc/--table-of-contents\f[R])
29772781.TP
29782782\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
2980−\f[C]setupwhitespace\f[R])
2783+spacing between paragraphs, e.g.
2784+\f[C]none\f[R], \f[C]small\f[R] (using \f[C]setupwhitespace\f[R])
29812785.TP
29822786\f[B]\f[CB]includesource\f[B]\f[R]
29832787include all source documents as file attachments in the PDF file
@@ -3015,16 +2819,20 @@ section number in man pages
30152819.SS Variables for ms
30162820.TP
30172821\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])
2822+font family (e.g.
2823+\f[C]T\f[R] or \f[C]P\f[R])
30192824.TP
30202825\f[B]\f[CB]indent\f[B]\f[R]
3021−paragraph indent (e.g.\ \f[C]2m\f[R])
2826+paragraph indent (e.g.
2827+\f[C]2m\f[R])
30222828.TP
30232829\f[B]\f[CB]lineheight\f[B]\f[R]
3024−line height (e.g.\ \f[C]12p\f[R])
2830+line height (e.g.
2831+\f[C]12p\f[R])
30252832.TP
30262833\f[B]\f[CB]pointsize\f[B]\f[R]
3027−point size (e.g.\ \f[C]10p\f[R])
2834+point size (e.g.
2835+\f[C]10p\f[R])
30282836.SS Variables set automatically
30292837.PP
30302838Pandoc sets these variables automatically in response to options or
@@ -3040,9 +2848,10 @@ in all HTML based formats (dzslides, epub, html, html4, html5, revealjs,
30402848s5, slideous, slidy).
30412849The recognized formats for \f[C]date\f[R] are: \f[C]mm/dd/yyyy\f[R],
30422850\f[C]mm/dd/yy\f[R], \f[C]yyyy-mm-dd\f[R] (ISO 8601),
3043−\f[C]dd MM yyyy\f[R] (e.g.\ either \f[C]02 Apr 2018\f[R] or
3044−\f[C]02 April 2018\f[R]), \f[C]MM dd, yyyy\f[R]
3045−(e.g.\ \f[C]Apr. 02, 2018\f[R] or
2851+\f[C]dd MM yyyy\f[R] (e.g.
2852+either \f[C]02 Apr 2018\f[R] or \f[C]02 April 2018\f[R]),
2853+\f[C]MM dd, yyyy\f[R] (e.g.
2854+\f[C]Apr. 02, 2018\f[R] or
30462855\f[C]April 02, 2018),\f[R]yyyy[mm[dd]]]\f[C](e.g.\f[R]20180402,
30472856\f[C]201804\f[R] or \f[C]2018\f[R]).
30482857.TP
@@ -3059,7 +2868,7 @@ contents specified by \f[C]-A/--include-after-body\f[R] (may have
30592868multiple values)
30602869.TP
30612870\f[B]\f[CB]meta-json\f[B]\f[R]
3062−JSON representation of all of the document\[cq]s metadata.
2871+JSON representation of all of the document\[aq]s metadata.
30632872Field values are transformed to the selected output format.
30642873.TP
30652874\f[B]\f[CB]numbersections\f[B]\f[R]
@@ -3087,7 +2896,8 @@ $endif$
30872896Similarly, \f[C]outputfile\f[R] can be \f[C]-\f[R] if output goes to the
30882897terminal.
30892898.PP
3090−If you need absolute paths, use e.g.\ \f[C]$curdir$/$sourcefile$\f[R].
2899+If you need absolute paths, use e.g.
2900+\f[C]$curdir$/$sourcefile$\f[R].
30912901.RE
30922902.TP
30932903\f[B]\f[CB]curdir\f[B]\f[R]
@@ -3108,12 +2918,12 @@ An extension can be enabled by adding \f[C]+EXTENSION\f[R] to the format
31082918name and disabled by adding \f[C]-EXTENSION\f[R].
31092919For example, \f[C]--from markdown_strict+footnotes\f[R] is strict
31102920Markdown with footnotes enabled, while
3111−\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[cq]s Markdown
2921+\f[C]--from markdown-footnotes-pipe_tables\f[R] is pandoc\[aq]s Markdown
31122922without footnotes or pipe tables.
31132923.PP
31142924The markdown reader and writer make by far the most use of extensions.
31152925Extensions only used by them are therefore covered in the section
3116−Pandoc\[cq]s Markdown below (See Markdown variants for
2926+Pandoc\[aq]s Markdown below (See Markdown variants for
31172927\f[C]commonmark\f[R] and \f[C]gfm\f[R].) In the following, extensions
31182928that also work for other formats are covered.
31192929.PP
@@ -3126,7 +2936,7 @@ Markdown cells in Jupyter notebooks (as do command-line options like
31262936Interpret straight quotes as curly quotes, \f[C]---\f[R] as em-dashes,
31272937\f[C]--\f[R] as en-dashes, and \f[C]...\f[R] as ellipses.
31282938Nonbreaking spaces are inserted after certain abbreviations, such as
3129−\[lq]Mr.\[rq]
2939+\[dq]Mr.\[dq]
31302940.PP
31312941This extension can be enabled/disabled for the following formats:
31322942.TP
@@ -3276,7 +3086,7 @@ letters are omitted.
32763086.SS Extension: \f[C]gfm_auto_identifiers\f[R]
32773087.PP
32783088Changes the algorithm used by \f[C]auto_identifiers\f[R] to conform to
3279−GitHub\[cq]s method.
3089+GitHub\[aq]s method.
32803090Spaces are converted to dashes (\f[C]-\f[R]), uppercase characters to
32813091lowercase characters, and punctuation characters other than \f[C]-\f[R]
32823092and \f[C]_\f[R] are removed.
@@ -3286,29 +3096,32 @@ Emojis are replaced by their names.
32863096The extensions \f[C]tex_math_dollars\f[R],
32873097\f[C]tex_math_single_backslash\f[R], and
32883098\f[C]tex_math_double_backslash\f[R] are described in the section about
3289−Pandoc\[cq]s Markdown.
3099+Pandoc\[aq]s Markdown.
32903100.PP
32913101However, they can also be used with HTML input.
32923102This is handy for reading web pages formatted using MathJax, for
32933103example.
32943104.SS Raw HTML/TeX
32953105.PP
3296−The following extensions are described in more detail in their
3297−respective sections of Pandoc\[cq]s Markdown:
3298−.IP \[bu] 2
3299−\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.
3106+The following extensions (especially how they affect Markdown
3107+input/output) are also described in more detail in their respective
3108+sections of Pandoc\[aq]s Markdown.
3109+.SS Extension: \f[C]raw_html\f[R]
3110+.PP
3111+When converting from HTML, parse elements to raw HTML which are not
3112+representable in pandoc\[aq]s AST.
33013113By default, this is disabled for HTML input.
3302−.IP \[bu] 2
3303−\f[C]raw_tex\f[R] allows raw LaTeX, TeX, and ConTeXt to be included in a
3304−document.
3114+.SS Extension: \f[C]raw_tex\f[R]
3115+.PP
3116+Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
3117+.PP
33053118This extension can be enabled/disabled for the following formats (in
33063119addition to \f[C]markdown\f[R]):
3307−.RS 2
33083120.TP
33093121input formats
3310−\f[C]latex\f[R], \f[C]textile\f[R], \f[C]html\f[R] (environments,
3311−\f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only), \f[C]ipynb\f[R]
3122+\f[C]latex\f[R], \f[C]org\f[R], \f[C]textile\f[R], \f[C]html\f[R]
3123+(environments, \f[C]\[rs]ref\f[R], and \f[C]\[rs]eqref\f[R] only),
3124+\f[C]ipynb\f[R]
33123125.TP
33133126output formats
33143127\f[C]textile\f[R], \f[C]commonmark\f[R]
@@ -3319,22 +3132,26 @@ with mime type \f[C]text/html\f[R] in output cells.
33193132Since the \f[C]ipynb\f[R] reader attempts to preserve the richest
33203133possible outputs when several options are given, you will get best
33213134results 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
3135+converting to formats like \f[C]docx\f[R] which don\[aq]t allow raw
33233136\f[C]html\f[R] or \f[C]tex\f[R].
3324−.RE
3325−.IP \[bu] 2
3326−\f[C]native_divs\f[R] causes HTML \f[C]div\f[R] elements to be parsed as
3327−native pandoc Div blocks.
3328−If you want them to be parsed as raw HTML, use
3329−\f[C]-f html-native_divs+raw_html\f[R].
3330−.IP \[bu] 2
3331−\f[C]native_spans\f[R] causes HTML \f[C]span\f[R] elements to be parsed
3332−as native pandoc Span inlines.
3333−If you want them to be parsed as raw HTML, use
3334−\f[C]-f html-native_spans+raw_html\f[R].
3335−If you want to drop all \f[C]div\f[R]s and \f[C]span\f[R]s when
3336−converting HTML to Markdown, you can use
3337−\f[C]pandoc -f html-native_divs-native_spans -t markdown\f[R].
3137+.SS Extension: \f[C]native_divs\f[R]
3138+.PP
3139+This extension is enabled by default for HTML input.
3140+This means that \f[C]div\f[R]s are parsed to pandoc native elements.
3141+(Alternatively, you can parse them to raw HTML using
3142+\f[C]-f html-native_divs+raw_html\f[R].)
3143+.PP
3144+When converting HTML to Markdown, for example, you may want to drop all
3145+\f[C]div\f[R]s and \f[C]span\f[R]s:
3146+.IP
3147+.nf
3148+\f[C]
3149+pandoc -f html-native_divs-native_spans -t markdown
3150+\f[R]
3151+.fi
3152+.SS Extension: \f[C]native_spans\f[R]
3153+.PP
3154+Analogous to \f[C]native_divs\f[R] above.
33383155.SS Literate Haskell support
33393156.SS Extension: \f[C]literate_haskell\f[R]
33403157.PP
@@ -3353,22 +3170,23 @@ the formats above, pandoc will treat the document as literate Haskell
33533170source.
33543171This means that
33553172.IP \[bu] 2
3356−In Markdown input, \[lq]bird track\[rq] sections will be parsed as
3173+In Markdown input, \[dq]bird track\[dq] sections will be parsed as
33573174Haskell code rather than block quotations.
33583175Text between \f[C]\[rs]begin{code}\f[R] and \f[C]\[rs]end{code}\f[R]
33593176will also be treated as Haskell code.
3360−For ATX-style headings the character `=' will be used instead of `#'.
3177+For ATX-style headings the character \[aq]=\[aq] will be used instead of
3178+\[aq]#\[aq].
33613179.IP \[bu] 2
33623180In Markdown output, code blocks with classes \f[C]haskell\f[R] and
33633181\f[C]literate\f[R] will be rendered using bird tracks, and block
33643182quotations will be indented one space, so they will not be treated as
33653183Haskell code.
33663184In addition, headings will be rendered setext-style (with underlines)
3367−rather than ATX-style (with `#' characters).
3368−(This is because ghc treats `#' characters in column 1 as introducing
3369−line numbers.)
3185+rather than ATX-style (with \[aq]#\[aq] characters).
3186+(This is because ghc treats \[aq]#\[aq] characters in column 1 as
3187+introducing line numbers.)
33703188.IP \[bu] 2
3371−In restructured text input, \[lq]bird track\[rq] sections will be parsed
3189+In restructured text input, \[dq]bird track\[dq] sections will be parsed
33723190as Haskell code.
33733191.IP \[bu] 2
33743192In restructured text output, code blocks with class \f[C]haskell\f[R]
@@ -3404,8 +3222,9 @@ writes HTML with the Haskell code in bird tracks, so it can be copied
34043222and pasted as literate Haskell source.
34053223.PP
34063224Note that GHC expects the bird tracks in the first column, so indented
3407−literate code blocks (e.g.\ inside an itemized environment) will not be
3408−picked up by the Haskell compiler.
3225+literate code blocks (e.g.
3226+inside an itemized environment) will not be picked up by the Haskell
3227+compiler.
34093228.SS Other extensions
34103229.SS Extension: \f[C]empty_paragraphs\f[R]
34113230.PP
@@ -3428,43 +3247,6 @@ This extension can be enabled/disabled for the following formats:
34283247.TP
34293248output formats
34303249\f[C]odt\f[R], \f[C]opendocument\f[R]
3431−.SS Extension: \f[C]xrefs_name\f[R]
3432−.PP
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
3437−refreshed.
3438−This extension can be combined with \f[C]xrefs_number\f[R] in which case
3439−numbers will appear before the name.
3440−.PP
3441−Text in cross-references is only made consistent with the referenced
3442−item once the document has been refreshed.
3443−.PP
3444−This extension can be enabled/disabled for the following formats:
3445−.TP
3446−output formats
3447−\f[C]odt\f[R], \f[C]opendocument\f[R]
3448−.SS Extension: \f[C]xrefs_number\f[R]
3449−.PP
3450−Links to headings, figures and tables inside the document are
3451−substituted with cross-references that will use the number of the
3452−referenced item.
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.
3456−.PP
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.
3460−.PP
3461−Numbers in cross-references are only visible in the final document once
3462−it has been refreshed.
3463−.PP
3464−This extension can be enabled/disabled for the following formats:
3465−.TP
3466−output formats
3467−\f[C]odt\f[R], \f[C]opendocument\f[R]
34683250.SS Extension: \f[C]styles\f[R]
34693251.PP
34703252When converting from docx, read all docx styles as divs (for paragraph
@@ -3479,33 +3261,20 @@ input formats
34793261.PP
34803262In the \f[C]muse\f[R] input format, this enables Text::Amuse extensions
34813263to Emacs Muse markup.
3482−.SS Extension: \f[C]raw_markdown\f[R]
3483−.PP
3484−In the \f[C]ipynb\f[R] input format, this causes Markdown cells to be
3485−included as raw Markdown blocks (allowing lossless round-tripping)
3486−rather than being parsed.
3487−Use this only when you are targeting \f[C]ipynb\f[R] or a markdown-based
3488−output format.
34893264.SS Extension: \f[C]citations\f[R]
34903265.PP
3491−Some aspects of Pandoc\[cq]s Markdown citation syntax are also accepted
3266+Some aspects of Pandoc\[aq]s Markdown citation syntax are also accepted
34923267in \f[C]org\f[R] input.
3493−.SS Extension: \f[C]element_citations\f[R]
3494−.PP
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.
34993268.SS Extension: \f[C]ntb\f[R]
35003269.PP
35013270In the \f[C]context\f[R] output format this enables the use of Natural
35023271Tables (TABLE) instead of the default Extreme Tables (xtables).
35033272Natural tables allow more fine-grained global customization but come at
35043273a performance penalty compared to extreme tables.
3505−.SH PANDOC\[cq]S MARKDOWN
3274+.SH PANDOC\[aq]S MARKDOWN
35063275.PP
35073276Pandoc understands an extended and slightly revised version of John
3508−Gruber\[cq]s Markdown syntax.
3277+Gruber\[aq]s Markdown syntax.
35093278This document explains the syntax, noting differences from standard
35103279Markdown.
35113280Except where noted, these differences can be suppressed by using the
@@ -3522,15 +3291,15 @@ easy to read:
35223291.RS
35233292.PP
35243293A Markdown-formatted document should be publishable as-is, as plain
3525−text, without looking like it\[cq]s been marked up with tags or
3294+text, without looking like it\[aq]s been marked up with tags or
35263295formatting instructions.
3527−\[en] John Gruber
3296+-- John Gruber
35283297.RE
35293298.PP
3530−This principle has guided pandoc\[cq]s decisions in finding syntax for
3299+This principle has guided pandoc\[aq]s decisions in finding syntax for
35313300tables, footnotes, and other extensions.
35323301.PP
3533−There is, however, one respect in which pandoc\[cq]s aims are different
3302+There is, however, one respect in which pandoc\[aq]s aims are different
35343303from the original aims of Markdown.
35353304Whereas Markdown was originally designed with HTML generation in mind,
35363305pandoc is designed for multiple output formats.
@@ -3555,7 +3324,7 @@ a hard line break, since trailing spaces in the cells are ignored.
35553324There are two kinds of headings: Setext and ATX.
35563325.SS Setext-style headings
35573326.PP
3558−A setext-style heading is a line of text \[lq]underlined\[rq] with a row
3327+A setext-style heading is a line of text \[dq]underlined\[dq] with a row
35593328of \f[C]=\f[R] signs (for a level-one heading) or \f[C]-\f[R] signs (for
35603329a level-two heading):
35613330.IP
@@ -3646,7 +3415,7 @@ My other heading {#foo}
36463415(This syntax is compatible with PHP Markdown Extra.)
36473416.PP
36483417Note that although this syntax allows assignment of classes and
3649−key/value attributes, writers generally don\[cq]t use all of this
3418+key/value attributes, writers generally don\[aq]t use all of this
36503419information.
36513420Identifiers, classes, and key/value attributes are used in HTML and
36523421HTML-based formats such as EPUB and slidy.
@@ -3761,7 +3530,7 @@ indented more than three spaces.)
37613530\f[R]
37623531.fi
37633532.PP
3764−A \[lq]lazy\[rq] form, which requires the \f[C]>\f[R] character only on
3533+A \[dq]lazy\[dq] form, which requires the \f[C]>\f[R] character only on
37653534the first line of each block, is also allowed:
37663535.IP
37673536.nf
@@ -3979,9 +3748,6 @@ begin with a space.
39793748\f[R]
39803749.fi
39813750.PP
3982−Inline formatting (such as emphasis) is allowed in the content, but not
3983−block-level formatting (such as block quotes or lists).
3984−.PP
39853751This syntax is borrowed from reStructuredText.
39863752.SS Lists
39873753.SS Bullet lists
@@ -3999,8 +3765,8 @@ Here is a simple example:
39993765\f[R]
40003766.fi
40013767.PP
4002−This will produce a \[lq]compact\[rq] list.
4003−If you want a \[lq]loose\[rq] list, in which each item is formatted as a
3768+This will produce a \[dq]compact\[dq] list.
3769+If you want a \[dq]loose\[dq] list, in which each item is formatted as a
40043770paragraph, put spaces between the items:
40053771.IP
40063772.nf
@@ -4028,7 +3794,7 @@ List items look best if subsequent lines are flush with the first line
40283794\f[R]
40293795.fi
40303796.PP
4031−But Markdown also allows a \[lq]lazy\[rq] format:
3797+But Markdown also allows a \[dq]lazy\[dq] format:
40323798.IP
40333799.nf
40343800\f[C]
@@ -4091,7 +3857,7 @@ character after the list marker of the containing list item.
40913857.fi
40923858.PP
40933859As noted above, Markdown allows you to write list items
4094−\[lq]lazily,\[rq] instead of indenting continuation lines.
3860+\[dq]lazily,\[dq] instead of indenting continuation lines.
40953861However, if there are multiple paragraphs or other blocks in a list
40963862item, the first line of each must be indented.
40973863.IP
@@ -4145,8 +3911,8 @@ They must be separated from the text that follows by at least one space,
41453911and, if the list marker is a capital letter with a period, by at least
41463912two spaces.
41473913.PP
4148−The \f[C]fancy_lists\f[R] extension also allows `\f[C]#\f[R]' to be used
4149−as an ordered list marker in place of a numeral:
3914+The \f[C]fancy_lists\f[R] extension also allows \[aq]\f[C]#\f[R]\[aq] to
3915+be used as an ordered list marker in place of a numeral:
41503916.IP
41513917.nf
41523918\f[C]
@@ -4239,7 +4005,7 @@ one or more block elements (paragraph, code block, list, etc.), each
42394005indented four spaces or one tab stop.
42404006The body of the definition (including the first line, aside from the
42414007colon or tilde) should be indented four spaces.
4242−However, as with other Markdown lists, you can \[lq]lazily\[rq] omit
4008+However, as with other Markdown lists, you can \[dq]lazily\[dq] omit
42434009indentation except at the beginning of a paragraph or other block
42444010element:
42454011.IP
@@ -4273,16 +4039,16 @@ Term 2
42734039.fi
42744040.PP
42754041Note that space between items in a definition list is required.
4276−(A variant that loosens this requirement, but disallows \[lq]lazy\[rq]
4042+(A variant that loosens this requirement, but disallows \[dq]lazy\[dq]
42774043hard wrapping, can be activated with \f[C]compact_definition_lists\f[R]:
4278−see Non-default extensions, below.)
4044+see Non-pandoc extensions, below.)
42794045.SS Numbered example lists
42804046.SS Extension: \f[C]example_lists\f[R]
42814047.PP
42824048The special list marker \f[C]\[at]\f[R] can be used for sequentially
42834049numbered examples.
4284−The first list item with a \f[C]\[at]\f[R] marker will be numbered `1',
4285−the next `2', and so on, throughout the document.
4050+The first list item with a \f[C]\[at]\f[R] marker will be numbered
4051+\[aq]1\[aq], the next \[aq]2\[aq], and so on, throughout the document.
42864052The numbered examples need not occur in a single list; each new list
42874053using \f[C]\[at]\f[R] will take up where the last stopped.
42884054So, for example:
@@ -4318,6 +4084,39 @@ That is, example lists always behave as if the \f[C]four_space_rule\f[R]
43184084extension is set.
43194085This is because example labels tend to be long, and indenting content to
43204086the first non-space character after the label would be awkward.
4087+.SS Compact and loose lists
4088+.PP
4089+Pandoc behaves differently from \f[C]Markdown.pl\f[R] on some \[dq]edge
4090+cases\[dq] involving lists.
4091+Consider this source:
4092+.IP
4093+.nf
4094+\f[C]
4095++ First
4096++ Second:
4097+ - Fee
4098+ - Fie
4099+ - Foe
4100+
4101++ Third
4102+\f[R]
4103+.fi
4104+.PP
4105+Pandoc transforms this into a \[dq]compact list\[dq] (with no
4106+\f[C]<p>\f[R] tags around \[dq]First\[dq], \[dq]Second\[dq], or
4107+\[dq]Third\[dq]), while Markdown puts \f[C]<p>\f[R] tags around
4108+\[dq]Second\[dq] and \[dq]Third\[dq] (but not \[dq]First\[dq]), because
4109+of the blank space around \[dq]Third\[dq].
4110+Pandoc follows a simple rule: if the text is followed by a blank line,
4111+it is treated as a paragraph.
4112+Since \[dq]Second\[dq] is followed by a list, and not a blank line, it
4113+isn\[aq]t treated as a paragraph.
4114+The fact that the list is followed by a blank line is irrelevant.
4115+(Note: Pandoc works this way even when the \f[C]markdown_strict\f[R]
4116+format is specified.
4117+This behavior is consistent with the official Markdown syntax
4118+description, even though it is different from that of
4119+\f[C]Markdown.pl\f[R].)
43214120.SS Ending a list
43224121.PP
43234122What if you want to put an indented code block after a list?
@@ -4335,8 +4134,8 @@ Trouble! Here pandoc (like other Markdown implementations) will treat
43354134\f[C]{ my code block }\f[R] as the second paragraph of item two, and not
43364135as a code block.
43374136.PP
4338−To \[lq]cut off\[rq] the list after item two, you can insert some
4339−non-indented content, like an HTML comment, which won\[cq]t produce
4137+To \[dq]cut off\[dq] the list after item two, you can insert some
4138+non-indented content, like an HTML comment, which won\[aq]t produce
43404139visible output in any format:
43414140.IP
43424141.nf
@@ -4532,7 +4331,7 @@ can be omitted for a headerless table.
45324331The cells of grid tables may contain arbitrary block elements (multiple
45334332paragraphs, code blocks, lists, etc.).
45344333Cells that span multiple columns or rows are not supported.
4535−Grid tables can be created easily using Emacs\[cq] table-mode
4334+Grid tables can be created easily using Emacs\[aq] table-mode
45364335(\f[C]M-x table-insert\f[R]).
45374336.PP
45384337Alignments can be specified as with pipe tables, by putting colons at
@@ -4605,7 +4404,7 @@ orange|3.09
46054404.PP
46064405The cells of pipe tables cannot contain block elements like paragraphs
46074406and lists, and cannot span multiple lines.
4608−If a pipe table contains a row whose Markdown content is wider than the
4407+If a pipe table contains a row whose printable content is wider than the
46094408column width (see \f[C]--columns\f[R]), then the table will take up the
46104409full text width and the cell contents will wrap, with the relative cell
46114410widths determined by the number of dashes in the line separating the
@@ -4616,7 +4415,7 @@ lines are wider than column width, then cell contents will not be
46164415wrapped, and the cells will be sized to their contents.
46174416.PP
46184417Note: pandoc also recognizes pipe tables of the following form, as can
4619−be produced by Emacs\[cq] orgtbl-mode:
4418+be produced by Emacs\[aq] orgtbl-mode:
46204419.IP
46214420.nf
46224421\f[C]
@@ -4629,7 +4428,7 @@ be produced by Emacs\[cq] orgtbl-mode:
46294428.PP
46304429The difference is that \f[C]+\f[R] is used instead of \f[C]|\f[R].
46314430Other orgtbl features are not supported.
4632−In particular, to get non-default column alignment, you\[cq]ll need to
4431+In particular, to get non-default column alignment, you\[aq]ll need to
46334432add colons as above.
46344433.SS Metadata blocks
46354434.SS Extension: \f[C]pandoc_title_block\f[R]
@@ -4655,11 +4454,7 @@ no author, you need a blank line:
46554454\f[C]
46564455%
46574456% Author
4658−\f[R]
4659−.fi
4660−.IP
4661−.nf
4662−\f[C]
4457+
46634458% My title
46644459%
46654460% June 15, 2006
@@ -4684,17 +4479,9 @@ So, all of the following are equivalent:
46844479\f[C]
46854480% Author One
46864481 Author Two
4687−\f[R]
4688−.fi
4689−.IP
4690−.nf
4691−\f[C]
4482+
46924483% Author One; Author Two
4693−\f[R]
4694−.fi
4695−.IP
4696−.nf
4697−\f[C]
4484+
46984485% Author One;
46994486 Author Two
47004487\f[R]
@@ -4707,13 +4494,13 @@ All three metadata fields may contain standard inline formatting
47074494.PP
47084495Title blocks will always be parsed, but they will affect the output only
47094496when 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
4711−\[en] this is the title that will appear at the top of the window in a
4712−browser \[en] and once at the beginning of the document body.
4497+In HTML output, titles will appear twice: once in the document head --
4498+this is the title that will appear at the top of the window in a browser
4499+-- and once at the beginning of the document body.
47134500The title in the document head can have an optional prefix attached
47144501(\f[C]--title-prefix\f[R] or \f[C]-T\f[R] option).
47154502The title in the body appears as an H1 element with class
4716−\[lq]title\[rq], so it can be suppressed or reformatted with CSS.
4503+\[dq]title\[dq], so it can be suppressed or reformatted with CSS.
47174504If a title prefix is specified with \f[C]-T\f[R] and no title block
47184505appears in the document, the title prefix will be used by itself as the
47194506HTML title.
@@ -4742,7 +4529,7 @@ will yield a man page with the title \f[C]PANDOC\f[R] and section 1.
47424529\f[R]
47434530.fi
47444531.PP
4745−will also have \[lq]Pandoc User Manuals\[rq] in the footer.
4532+will also have \[dq]Pandoc User Manuals\[dq] in the footer.
47464533.IP
47474534.nf
47484535\f[C]
@@ -4750,7 +4537,7 @@ will also have \[lq]Pandoc User Manuals\[rq] in the footer.
47504537\f[R]
47514538.fi
47524539.PP
4753−will also have \[lq]Version 4.0\[rq] in the header.
4540+will also have \[dq]Version 4.0\[dq] in the header.
47544541.SS Extension: \f[C]yaml_metadata_block\f[R]
47554542.PP
47564543A YAML metadata block is a valid YAML object, delimited by a line of
@@ -4796,9 +4583,7 @@ All of the metadata will appear in a single block at the beginning of
47964583the document.
47974584.PP
47984585Note that YAML escaping rules must be followed.
4799−Thus, for example, if a title contains a colon, it must be quoted, and
4800−if it contains a backslash escape, then it must be ensured that it is
4801−not treated as a YAML escape sequence.
4586+Thus, for example, if a title contains a colon, it must be quoted.
48024587The pipe character (\f[C]|\f[R]) can be used to begin an indented block
48034588that will be interpreted literally, without need for escaping.
48044589This form is necessary when the field contains blank lines or
@@ -4820,13 +4605,6 @@ abstract: |
48204605\f[R]
48214606.fi
48224607.PP
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
4826−as metadata.
4827−For an overview of the complex rules governing YAML, see the Wikipedia
4828−entry on YAML syntax.
4829−.PP
48304608Template variables will be set automatically from the metadata.
48314609Thus, for example, in writing HTML, the variable \f[C]abstract\f[R] will
48324610be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[R]
@@ -4875,7 +4653,7 @@ $endfor$
48754653\f[R]
48764654.fi
48774655.PP
4878−Raw content to include in the document\[cq]s header may be specified
4656+Raw content to include in the document\[aq]s header may be specified
48794657using \f[C]header-includes\f[R]; however, it is important to mark up
48804658this content as raw code for a particular output format, using the
48814659\f[C]raw_attribute\f[R] extension), or it will be interpreted as
@@ -4892,21 +4670,6 @@ header-includes:
48924670 \[ga]\[ga]\[ga]
48934671\f[R]
48944672.fi
4895−.PP
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:
4900−.IP \[bu] 2
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.
4905−.IP \[bu] 2
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.
49104673.SS Backslash escapes
49114674.SS Extension: \f[C]all_symbols_escapable\f[R]
49124675.PP
@@ -4937,7 +4700,7 @@ instead of
49374700\f[R]
49384701.fi
49394702.PP
4940−This rule is easier to remember than standard Markdown\[cq]s rule, which
4703+This rule is easier to remember than standard Markdown\[aq]s rule, which
49414704allows only the following characters to be backslash-escaped:
49424705.IP
49434706.nf
@@ -4953,15 +4716,16 @@ A backslash-escaped space is parsed as a nonbreaking space.
49534716In TeX output, it will appear as \f[C]\[ti]\f[R].
49544717In HTML and XML output, it will appear as a literal unicode nonbreaking
49554718space character (note that it will thus actually look
4956−\[lq]invisible\[rq] in the generated HTML source; you can still use the
4719+\[dq]invisible\[dq] in the generated HTML source; you can still use the
49574720\f[C]--ascii\f[R] command-line option to make it appear as an explicit
49584721entity).
49594722.PP
4960−A backslash-escaped newline (i.e.\ a backslash occurring at the end of a
4961−line) is parsed as a hard line break.
4723+A backslash-escaped newline (i.e.
4724+a backslash occurring at the end of a line) is parsed as a hard line
4725+break.
49624726It will appear in TeX output as \f[C]\[rs]\[rs]\f[R] and in HTML as
49634727\f[C]<br />\f[R].
4964−This is a nice alternative to Markdown\[cq]s \[lq]invisible\[rq] way of
4728+This is a nice alternative to Markdown\[aq]s \[dq]invisible\[dq] way of
49654729indicating hard line breaks using two trailing spaces on a line.
49664730.PP
49674731Backslash escapes do not work in verbatim contexts.
@@ -5038,8 +4802,8 @@ If the superscripted or subscripted text contains spaces, these spaces
50384802must be escaped with backslashes.
50394803(This is to prevent accidental superscripting and subscripting through
50404804the 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
5042−cat' in subscripts, use \f[C]P\[ti]a\[rs] cat\[ti]\f[R], not
4805+interactions with footnotes.) Thus, if you want the letter P with \[aq]a
4806+cat\[aq] in subscripts, use \f[C]P\[ti]a\[rs] cat\[ti]\f[R], not
50434807\f[C]P\[ti]a cat\[ti]\f[R].
50444808.SS Verbatim
50454809.PP
@@ -5119,16 +4883,14 @@ The opening \f[C]$\f[R] must have a non-space character immediately to
51194883its right, while the closing \f[C]$\f[R] must have a non-space character
51204884immediately to its left, and must not be followed immediately by a
51214885digit.
5122−Thus, \f[C]$20,000 and $30,000\f[R] won\[cq]t parse as math.
4886+Thus, \f[C]$20,000 and $30,000\f[R] won\[aq]t parse as math.
51234887If 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
4888+characters, backslash-escape them and they won\[aq]t be treated as math
51254889delimiters.
51264890.PP
51274891For display math, use \f[C]$$\f[R] delimiters.
51284892(In this case, the delimiters may be separated from the formula by
5129−whitespace.
5130−However, there can be no blank lines betwen the opening and closing
5131−\f[C]$$\f[R] delimiters.)
4893+whitespace.)
51324894.PP
51334895TeX math will be printed in all output formats.
51344896How it is rendered depends on the output format:
@@ -5159,7 +4921,7 @@ Texinfo
51594921It will be rendered inside a \f[C]\[at]math\f[R] command.
51604922.TP
51614923roff man, Jira markup
5162−It will be rendered verbatim without \f[C]$\f[R]\[cq]s.
4924+It will be rendered verbatim without \f[C]$\f[R]\[aq]s.
51634925.TP
51644926MediaWiki, DokuWiki
51654927It will be rendered inside \f[C]<math>\f[R] tags.
@@ -5217,7 +4979,7 @@ Note that even if \f[C]raw_html\f[R] is disabled, tables will be
52174979rendered with HTML syntax if they cannot use pipe syntax.
52184980.SS Extension: \f[C]markdown_in_html_blocks\f[R]
52194981.PP
5220−Standard Markdown allows you to include HTML \[lq]blocks\[rq]: blocks of
4982+Standard Markdown allows you to include HTML \[dq]blocks\[dq]: blocks of
52214983HTML between balanced tags that are separated from the surrounding text
52224984with blank lines, and start and end at the left margin.
52234985Within these blocks, everything is interpreted as HTML, not Markdown; so
@@ -5254,9 +5016,8 @@ into
52545016.PP
52555017whereas \f[C]Markdown.pl\f[R] will preserve it as is.
52565018.PP
5257−There is one exception to this rule: text between \f[C]<script>\f[R],
5258−\f[C]<style>\f[R], and \f[C]<textarea>\f[R] tags is not interpreted as
5259−Markdown.
5019+There is one exception to this rule: text between \f[C]<script>\f[R] and
5020+\f[C]<style>\f[R] tags is not interpreted as Markdown.
52605021.PP
52615022This departure from standard Markdown should make it easier to mix
52625023Markdown with HTML block elements.
@@ -5556,7 +5317,7 @@ slide shows and EPUB), LaTeX, and ConTeXt.
55565317.PP
55575318A link immediately preceded by a \f[C]!\f[R] will be treated as an
55585319image.
5559−The link text will be used as the image\[cq]s alt text:
5320+The link text will be used as the image\[aq]s alt text:
55605321.IP
55615322.nf
55625323\f[C]
@@ -5571,7 +5332,7 @@ The link text will be used as the image\[cq]s alt text:
55715332.PP
55725333An image with nonempty alt text, occurring by itself in a paragraph,
55735334will be rendered as a figure with a caption.
5574−The image\[cq]s alt text will be used as the caption.
5335+The image\[aq]s alt text will be used as the caption.
55755336.IP
55765337.nf
55775338\f[C]
@@ -5580,8 +5341,9 @@ The image\[cq]s alt text will be used as the caption.
55805341.fi
55815342.PP
55825343How this is rendered depends on the output format.
5583−Some output formats (e.g.\ RTF) do not yet support figures.
5584−In those formats, you\[cq]ll just get an image in a paragraph by itself,
5344+Some output formats (e.g.
5345+RTF) do not yet support figures.
5346+In those formats, you\[aq]ll just get an image in a paragraph by itself,
55855347with no caption.
55865348.PP
55875349If you just want a regular inline image, just make sure it is not the
@@ -5636,12 +5398,11 @@ For example:
56365398\f[R]
56375399.fi
56385400.IP \[bu] 2
5639−Dimensions may be converted to a form that is compatible with the output
5640−format (for example, dimensions given in pixels will be converted to
5641−inches when converting HTML to LaTeX).
5642−Conversion between pixels and physical measurements is affected by the
5643−\f[C]--dpi\f[R] option (by default, 96 dpi is assumed, unless the image
5644−itself contains dpi information).
5401+Dimensions are converted to inches for output in page-based formats like
5402+LaTeX.
5403+Dimensions are converted to pixels for output in HTML-like formats.
5404+Use the \f[C]--dpi\f[R] option to specify the number of pixels per inch.
5405+The default is 96dpi.
56455406.IP \[bu] 2
56465407The \f[C]%\f[R] unit is generally relative to some available space.
56475408For example the above example will render to the following.
@@ -5652,7 +5413,7 @@ HTML:
56525413.IP \[bu] 2
56535414LaTeX:
56545415\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
5416+(If you\[aq]re using a custom template, you need to configure
56565417\f[C]graphicx\f[R] as in the default template.)
56575418.IP \[bu] 2
56585419ConTeXt:
@@ -5735,7 +5496,7 @@ immediately by attributes:
57355496.SS Footnotes
57365497.SS Extension: \f[C]footnotes\f[R]
57375498.PP
5738−Pandoc\[cq]s Markdown allows footnotes, using the following syntax:
5499+Pandoc\[aq]s Markdown allows footnotes, using the following syntax:
57395500.IP
57405501.nf
57415502\f[C]
@@ -5784,82 +5545,207 @@ note.]
57845545.fi
57855546.PP
57865547Inline and regular footnotes may be mixed freely.
5787−.SS Citation syntax
5548+.SS Citations
57885549.SS Extension: \f[C]citations\f[R]
57895550.PP
5790−To cite a bibliographic item with an identifier foo, use the syntax
5791−\f[C]\[at]foo\f[R].
5792−Normal citations should be included in square brackets, with semicolons
5793−separating distinct items:
5794−.IP
5795−.nf
5796−\f[C]
5797−Blah blah [\[at]doe99; \[at]smith2000; \[at]smith2004].
5798−\f[R]
5799−.fi
5800−.PP
5801−How this is rendered depends on the citation style.
5802−In an author-date style, it might render as
5803−.IP
5804−.nf
5805−\f[C]
5806−Blah blah (Doe 1999, Smith 2000, 2004).
5807−\f[R]
5808−.fi
5809−.PP
5810−In a footnote style, it might render as
5551+Using an external filter, \f[C]pandoc-citeproc\f[R], pandoc can
5552+automatically generate citations and a bibliography in a number of
5553+styles.
5554+Basic usage is
58115555.IP
58125556.nf
58135557\f[C]
5814−Blah blah.[\[ha]1]
5815−
5816−[\[ha]1]: John Doe, \[dq]Frogs,\[dq] *Journal of Amphibians* 44 (1999);
5817−Susan Smith, \[dq]Flies,\[dq] *Journal of Insects* (2000);
5818−Susan Smith, \[dq]Bees,\[dq] *Journal of Insects* (2004).
5558+pandoc --filter pandoc-citeproc myinput.txt
58195559\f[R]
58205560.fi
58215561.PP
5822−See the CSL user documentation for more information about CSL styles and
5823−how they affect rendering.
5562+In order to use this feature, you will need to specify a bibliography
5563+file using the \f[C]bibliography\f[R] metadata field in a YAML metadata
5564+section, or \f[C]--bibliography\f[R] command line argument.
5565+You can supply multiple \f[C]--bibliography\f[R] arguments or set
5566+\f[C]bibliography\f[R] metadata field to YAML array, if you want to use
5567+multiple bibliography files.
5568+The bibliography may have any of these formats:
58245569.PP
5825−Unless a citation key start with a letter, digit, or \f[C]_\f[R], and
5826−contains only alphanumerics and internal punctuation characters
5827−(\f[C]:.#$%&-+?<>\[ti]/\f[R]), it must be surrounded by curly braces,
5828−which are not considered part of the key.
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].
5570+.TS
5571+tab(@);
5572+l l.
5573+T{
5574+Format
5575+T}@T{
5576+File extension
5577+T}
5578+_
5579+T{
5580+BibLaTeX
5581+T}@T{
5582+\&.bib
5583+T}
5584+T{
5585+BibTeX
5586+T}@T{
5587+\&.bibtex
5588+T}
5589+T{
5590+Copac
5591+T}@T{
5592+\&.copac
5593+T}
5594+T{
5595+CSL JSON
5596+T}@T{
5597+\&.json
5598+T}
5599+T{
5600+CSL YAML
5601+T}@T{
5602+\&.yaml
5603+T}
5604+T{
5605+EndNote
5606+T}@T{
5607+\&.enl
5608+T}
5609+T{
5610+EndNote XML
5611+T}@T{
5612+\&.xml
5613+T}
5614+T{
5615+ISI
5616+T}@T{
5617+\&.wos
5618+T}
5619+T{
5620+MEDLINE
5621+T}@T{
5622+\&.medline
5623+T}
5624+T{
5625+MODS
5626+T}@T{
5627+\&.mods
5628+T}
5629+T{
5630+RIS
5631+T}@T{
5632+\&.ris
5633+T}
5634+.TE
58365635.PP
5837−Citation items may optionally include a prefix, a locator, and a suffix.
5838−In
5839−.IP
5840−.nf
5841−\f[C]
5842−Blah blah [see \[at]doe99, pp. 33-35 and *passim*; \[at]smith04, chap. 1].
5843−\f[R]
5844−.fi
5636+Note that \f[C].bib\f[R] can be used with both BibTeX and BibLaTeX
5637+files; use \f[C].bibtex\f[R] to force BibTeX.
58455638.PP
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
5849−prefix or suffix.
5639+Note that \f[C]pandoc-citeproc --bib2json\f[R] and
5640+\f[C]pandoc-citeproc --bib2yaml\f[R] can produce \f[C].json\f[R] and
5641+\f[C].yaml\f[R] files from any of the supported formats.
58505642.PP
5851−Pandoc uses some heuristics to separate the locator from the rest of the
5852−subject.
5853−It is sensitive to the locator terms defined in the CSL locale files.
5854−Either abbreviated or unabbreviated forms are accepted.
5855−In the \f[C]en-US\f[R] locale, locator terms can be written in either
5856−singular or plural forms, as \f[C]book\f[R],
5857−\f[C]bk.\f[R]/\f[C]bks.\f[R]; \f[C]chapter\f[R],
5858−\f[C]chap.\f[R]/\f[C]chaps.\f[R]; \f[C]column\f[R],
5859−\f[C]col.\f[R]/\f[C]cols.\f[R]; \f[C]figure\f[R],
5860−\f[C]fig.\f[R]/\f[C]figs.\f[R]; \f[C]folio\f[R],
5861−\f[C]fol.\f[R]/\f[C]fols.\f[R]; \f[C]number\f[R],
5862−\f[C]no.\f[R]/\f[C]nos.\f[R]; \f[C]line\f[R],
5643+In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc
5644+parses a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown;
5645+and in CSL JSON databases, an HTML-like markup:
5646+.TP
5647+\f[B]\f[CB]<i>...</i>\f[B]\f[R]
5648+italics
5649+.TP
5650+\f[B]\f[CB]<b>...</b>\f[B]\f[R]
5651+bold
5652+.TP
5653+\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]
5654+small capitals
5655+.TP
5656+\f[B]\f[CB]<sub>...</sub>\f[B]\f[R]
5657+subscript
5658+.TP
5659+\f[B]\f[CB]<sup>...</sup>\f[B]\f[R]
5660+superscript
5661+.TP
5662+\f[B]\f[CB]<span class=\[dq]nocase\[dq]>...</span>\f[B]\f[R]
5663+prevent a phrase from being capitalized as title case
5664+.PP
5665+\f[C]pandoc-citeproc -j\f[R] and \f[C]-y\f[R] interconvert the CSL JSON
5666+and CSL YAML formats as far as possible.
5667+.PP
5668+As an alternative to specifying a bibliography file using
5669+\f[C]--bibliography\f[R] or the YAML metadata field
5670+\f[C]bibliography\f[R], you can include the citation data directly in
5671+the \f[C]references\f[R] field of the document\[aq]s YAML metadata.
5672+The field should contain an array of YAML-encoded references, for
5673+example:
5674+.IP
5675+.nf
5676+\f[C]
5677+---
5678+references:
5679+- type: article-journal
5680+ id: WatsonCrick1953
5681+ author:
5682+ - family: Watson
5683+ given: J. D.
5684+ - family: Crick
5685+ given: F. H. C.
5686+ issued:
5687+ date-parts:
5688+ - - 1953
5689+ - 4
5690+ - 25
5691+ title: \[aq]Molecular structure of nucleic acids: a structure for deoxyribose
5692+ nucleic acid\[aq]
5693+ title-short: Molecular structure of nucleic acids
5694+ container-title: Nature
5695+ volume: 171
5696+ issue: 4356
5697+ page: 737-738
5698+ DOI: 10.1038/171737a0
5699+ URL: https://www.nature.com/articles/171737a0
5700+ language: en-GB
5701+\&...
5702+\f[R]
5703+.fi
5704+.PP
5705+(\f[C]pandoc-citeproc --bib2yaml\f[R] can produce these from a
5706+bibliography file in one of the supported formats.)
5707+.PP
5708+Citations and references can be formatted using any style supported by
5709+the Citation Style Language, listed in the Zotero Style Repository.
5710+These files are specified using the \f[C]--csl\f[R] option or the
5711+\f[C]csl\f[R] metadata field.
5712+By default, \f[C]pandoc-citeproc\f[R] will use the Chicago Manual of
5713+Style author-date format.
5714+The CSL project provides further information on finding and editing
5715+styles.
5716+.PP
5717+To make your citations hyperlinks to the corresponding bibliography
5718+entries, add \f[C]link-citations: true\f[R] to your YAML metadata.
5719+.PP
5720+Citations go inside square brackets and are separated by semicolons.
5721+Each citation must have a key, composed of \[aq]\[at]\[aq] + the
5722+citation identifier from the database, and may optionally have a prefix,
5723+a locator, and a suffix.
5724+The citation key must begin with a letter, digit, or \f[C]_\f[R], and
5725+may contain alphanumerics, \f[C]_\f[R], and internal punctuation
5726+characters (\f[C]:.#$%&-+?<>\[ti]/\f[R]).
5727+Here are some examples:
5728+.IP
5729+.nf
5730+\f[C]
5731+Blah blah [see \[at]doe99, pp. 33-35; also \[at]smith04, chap. 1].
5732+
5733+Blah blah [\[at]doe99, pp. 33-35, 38-39 and *passim*].
5734+
5735+Blah blah [\[at]smith04; \[at]doe99].
5736+\f[R]
5737+.fi
5738+.PP
5739+\f[C]pandoc-citeproc\f[R] detects locator terms in the CSL locale files.
5740+Either abbreviated or unabbreviated forms are accepted.
5741+In the \f[C]en-US\f[R] locale, locator terms can be written in either
5742+singular or plural forms, as \f[C]book\f[R],
5743+\f[C]bk.\f[R]/\f[C]bks.\f[R]; \f[C]chapter\f[R],
5744+\f[C]chap.\f[R]/\f[C]chaps.\f[R]; \f[C]column\f[R],
5745+\f[C]col.\f[R]/\f[C]cols.\f[R]; \f[C]figure\f[R],
5746+\f[C]fig.\f[R]/\f[C]figs.\f[R]; \f[C]folio\f[R],
5747+\f[C]fol.\f[R]/\f[C]fols.\f[R]; \f[C]number\f[R],
5748+\f[C]no.\f[R]/\f[C]nos.\f[R]; \f[C]line\f[R],
58635749\f[C]l.\f[R]/\f[C]ll.\f[R]; \f[C]note\f[R], \f[C]n.\f[R]/\f[C]nn.\f[R];
58645750\f[C]opus\f[R], \f[C]op.\f[R]/\f[C]opp.\f[R]; \f[C]page\f[R],
58655751\f[C]p.\f[R]/\f[C]pp.\f[R]; \f[C]paragraph\f[R],
@@ -5870,17 +5756,17 @@ singular or plural forms, as \f[C]book\f[R],
58705756\f[C]v.\f[R]/\f[C]vv.\f[R]; \f[C]volume\f[R],
58715757\f[C]vol.\f[R]/\f[C]vols.\f[R]; \f[C]\[ps]\f[R]/\f[C]\[ps]\[ps]\f[R];
58725758\f[C]\[sc]\f[R]/\f[C]\[sc]\[sc]\f[R].
5873−If no locator term is used, \[lq]page\[rq] is assumed.
5759+If no locator term is used, \[dq]page\[dq] is assumed.
58745760.PP
5875−In complex cases, you can force something to be treated as a locator by
5876−enclosing it in curly braces or prevent parsing the suffix as locator by
5877−prepending curly braces:
5761+\f[C]pandoc-citeproc\f[R] will use heuristics to distinguish the locator
5762+from the suffix.
5763+In complex cases, the locator can be enclosed in curly braces (using
5764+\f[C]pandoc-citeproc\f[R] 0.15 and higher only):
58785765.IP
58795766.nf
58805767\f[C]
58815768[\[at]smith{ii, A, D-Z}, with a suffix]
58825769[\[at]smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
5883−[\[at]smith{}, 99 years later]
58845770\f[R]
58855771.fi
58865772.PP
@@ -5894,8 +5780,7 @@ Smith says blah [-\[at]smith04].
58945780\f[R]
58955781.fi
58965782.PP
5897−You can also write an author-in-text citation, by omitting the square
5898−brackets:
5783+You can also write an in-text citation, as follows:
58995784.IP
59005785.nf
59015786\f[C]
@@ -5905,96 +5790,84 @@ brackets:
59055790\f[R]
59065791.fi
59075792.PP
5908−This will cause the author\[cq]s name to be rendered, followed by the
5909−bibliographical details.
5910−Use this form when you want to make the citation the subject of a
5911−sentence.
5793+If the style calls for a list of works cited, it will be placed in a div
5794+with id \f[C]refs\f[R], if one exists:
5795+.IP
5796+.nf
5797+\f[C]
5798+::: {#refs}
5799+:::
5800+\f[R]
5801+.fi
59125802.PP
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
5915−note.
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
5918−citations will not.
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
5803+Otherwise, it will be placed at the end of the document.
5804+Generation of the bibliography can be suppressed by setting
5805+\f[C]suppress-bibliography: true\f[R] in the YAML metadata.
59225806.PP
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
5927−hard line breaks.
5928−.SS Extension: \f[C]rebase_relative_paths\f[R]
5807+If you wish the bibliography to have a section heading, you can set
5808+\f[C]reference-section-title\f[R] in the metadata, or put the heading at
5809+the beginning of the div with id \f[C]refs\f[R] (if you are using it) or
5810+at the end of your document:
5811+.IP
5812+.nf
5813+\f[C]
5814+last paragraph...
5815+
5816+# References
5817+\f[R]
5818+.fi
59295819.PP
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.
5820+The bibliography will be inserted after this heading.
5821+Note that the \f[C]unnumbered\f[R] class will be added to this heading,
5822+so that the section will not be numbered.
59355823.PP
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
5940−the chapter.
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].
5945−To do this, use
5824+If you want to include items in the bibliography without actually citing
5825+them in the body text, you can define a dummy \f[C]nocite\f[R] metadata
5826+field and put the citations there:
59465827.IP
59475828.nf
59485829\f[C]
5949−pandoc chap*/*.md -f markdown+rebase_relative_paths
5830+---
5831+nocite: |
5832+ \[at]item1, \[at]item2
5833+\&...
5834+
5835+\[at]item3
59505836\f[R]
59515837.fi
59525838.PP
5953−Without this extension, you would have to use
5954−\f[C]\f[R] in \f[C]chap1/text.md\f[R] and
5955−\f[C]\f[R] in \f[C]chap2/text.md\f[R].
5956−Links with relative paths will be rewritten in the same way as images.
5839+In this example, the document will contain a citation for
5840+\f[C]item3\f[R] only, but the bibliography will contain entries for
5841+\f[C]item1\f[R], \f[C]item2\f[R], and \f[C]item3\f[R].
59575842.PP
5958−Absolute paths and URLs are not changed.
5959−Neither are empty paths or paths consisting entirely of a fragment,
5960−e.g., \f[C]#foo\f[R].
5843+It is possible to create a bibliography with all the citations, whether
5844+or not they appear in the document, by using a wildcard:
5845+.IP
5846+.nf
5847+\f[C]
5848+---
5849+nocite: |
5850+ \[at]*
5851+\&...
5852+\f[R]
5853+.fi
59615854.PP
5962−Note that relative paths in reference links and images will be rewritten
5963−relative to the file containing the link reference definition, not the
5964−file containing the reference link or image itself, if these differ.
5965−.SS Extension: \f[C]attributes\f[R]
5855+For LaTeX output, you can also use \f[C]natbib\f[R] or
5856+\f[C]biblatex\f[R] to render the bibliography.
5857+In order to do so, specify bibliography files as outlined above, and add
5858+\f[C]--natbib\f[R] or \f[C]--biblatex\f[R] argument to \f[C]pandoc\f[R]
5859+invocation.
5860+Bear in mind that bibliography files have to be in respective format
5861+(either BibTeX or BibLaTeX).
59665862.PP
5967−Allows attributes to be attached to any inline or block-level element.
5968−The syntax for the attributes is the same as that used in
5969−\f[C]header_attributes\f[R].
5970−.IP \[bu] 2
5971−Attributes that occur immediately after an inline element affect that
5972−element.
5973−If they follow a space, then they belong to the space.
5974−(Hence, this option subsumes \f[C]inline_code_attributes\f[R] and
5975−\f[C]link_attributes\f[R].)
5976−.IP \[bu] 2
5977−Attributes that occur immediately before a block element, on a line by
5978−themselves, affect that element.
5979−.IP \[bu] 2
5980−Consecutive attribute specifiers may be used, either for blocks or for
5981−inlines.
5982−Their attributes will be combined.
5983−.IP \[bu] 2
5984−Attributes that occur at the end of the text of a Setext or ATX heading
5985−(separated by whitespace from the text) affect the heading element.
5986−(Hence, this option subsumes \f[C]header_attributes\f[R].)
5987−.IP \[bu] 2
5988−Attributes that occur after the opening fence in a fenced code block
5989−affect the code block element.
5990−(Hence, this option subsumes \f[C]fenced_code_attributes\f[R].)
5991−.IP \[bu] 2
5992−Attributes that occur at the end of a reference link definition affect
5993−links that refer to that definition.
5863+For more information, see the pandoc-citeproc man page.
5864+.SS Non-pandoc extensions
59945865.PP
5995−Note that pandoc\[cq]s AST does not currently allow attributes to be
5996−attached to arbitrary elements.
5997−Hence a Span or Div container will be added if needed.
5866+The following Markdown syntax extensions are not enabled by default in
5867+pandoc, but may be enabled by adding \f[C]+EXTENSION\f[R] to the format
5868+name, where \f[C]EXTENSION\f[R] is the name of the extension.
5869+Thus, for example, \f[C]markdown+hard_line_breaks\f[R] is Markdown with
5870+hard line breaks.
59985871.SS Extension: \f[C]old_dashes\f[R]
59995872.PP
60005873Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
@@ -6006,7 +5879,7 @@ It is selected automatically for \f[C]textile\f[R] input.
60065879.PP
60075880Allow \f[C]<\f[R] and \f[C]>\f[R] to be backslash-escaped, as they can
60085881be in GitHub flavored Markdown but not original Markdown.
6009−This is implied by pandoc\[cq]s default \f[C]all_symbols_escapable\f[R].
5882+This is implied by pandoc\[aq]s default \f[C]all_symbols_escapable\f[R].
60105883.SS Extension: \f[C]lists_without_preceding_blankline\f[R]
60115884.PP
60125885Allow a list to occur right after a paragraph, with no intervening blank
@@ -6130,7 +6003,7 @@ in several respects:
61306003No blank line is required between consecutive items of the definition
61316004list.
61326005.IP \[bu] 2
6133−To get a \[lq]tight\[rq] or \[lq]compact\[rq] list, omit space between
6006+To get a \[dq]tight\[dq] or \[dq]compact\[dq] list, omit space between
61346007consecutive items; the space between a term and its definition does not
61356008affect anything.
61366009.IP \[bu] 2
@@ -6141,489 +6014,64 @@ be indented four spaces.
61416014Use Project Gutenberg conventions for \f[C]plain\f[R] output: all-caps
61426015for strong emphasis, surround by underscores for regular emphasis, add
61436016extra blank space around headings.
6144−.SS Extension: \f[C]sourcepos\f[R]
6145−.PP
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.
61506017.SS Markdown variants
61516018.PP
6152−In addition to pandoc\[cq]s extended Markdown, the following Markdown
6019+In addition to pandoc\[aq]s extended Markdown, the following Markdown
61536020variants are supported:
6154−.IP \[bu] 2
6155−\f[C]markdown_phpextra\f[R] (PHP Markdown Extra)
6156−.IP \[bu] 2
6157−\f[C]markdown_github\f[R] (deprecated GitHub-Flavored Markdown)
6158−.IP \[bu] 2
6159−\f[C]markdown_mmd\f[R] (MultiMarkdown)
6160−.IP \[bu] 2
6161−\f[C]markdown_strict\f[R] (Markdown.pl)
6162−.IP \[bu] 2
6163−\f[C]commonmark\f[R] (CommonMark)
6164−.IP \[bu] 2
6165−\f[C]gfm\f[R] (Github-Flavored Markdown)
6166−.IP \[bu] 2
6167−\f[C]commonmark_x\f[R] (CommonMark with many pandoc extensions)
6168−.PP
6169−To see which extensions are supported for a given format, and which are
6170−enabled by default, you can use the command
6171−.IP
6172−.nf
6173−\f[C]
6174−pandoc --list-extensions=FORMAT
6175−\f[R]
6176−.fi
6177−.PP
6178−where \f[C]FORMAT\f[R] is replaced with the name of the format.
6179−.PP
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
6182−default commonmark.
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.
6185−.SH CITATIONS
6186−.PP
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.
6189−Basic usage is
6190−.IP
6191−.nf
6192−\f[C]
6193−pandoc --citeproc myinput.txt
6194−\f[R]
6195−.fi
6196−.PP
6197−To use this feature, you will need to have
6198−.IP \[bu] 2
6199−a document containing citations (see Extension: \f[C]citations\f[R]);
6200−.IP \[bu] 2
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
6203−.IP \[bu] 2
6204−optionally, a CSL citation style.
6205−.SS Specifying bibliographic data
6206−.PP
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:
6214−.PP
6215−.TS
6216−tab(@);
6217−l l.
6218−T{
6219−Format
6220−T}@T{
6221−File extension
6222−T}
6223−_
6224−T{
6225−BibLaTeX
6226−T}@T{
6227−\&.bib
6228−T}
6229−T{
6230−BibTeX
6231−T}@T{
6232−\&.bibtex
6233−T}
6234−T{
6235−CSL JSON
6236−T}@T{
6237−\&.json
6238−T}
6239−T{
6240−CSL YAML
6241−T}@T{
6242−\&.yaml
6243−T}
6244−.TE
6245−.PP
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
6248−BibTeX.
6249−.PP
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:
6253−.TP
6254−\f[B]\f[CB]<i>...</i>\f[B]\f[R]
6255−italics
6256−.TP
6257−\f[B]\f[CB]<b>...</b>\f[B]\f[R]
6258−bold
6259−.TP
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]
6261−small capitals
6262−.TP
6263−\f[B]\f[CB]<sub>...</sub>\f[B]\f[R]
6264−subscript
6265−.TP
6266−\f[B]\f[CB]<sup>...</sup>\f[B]\f[R]
6267−superscript
6268−.TP
6269−\f[B]\f[CB]<span class=\[dq]nocase\[dq]>...</span>\f[B]\f[R]
6270−prevent a phrase from being capitalized as title case
6271−.PP
6272−As an alternative to specifying a bibliography file using
6273−\f[C]--bibliography\f[R] or the YAML metadata field
6274−\f[C]bibliography\f[R], you can include the citation data directly in
6275−the \f[C]references\f[R] field of the document\[cq]s YAML metadata.
6276−The field should contain an array of YAML-encoded references, for
6277−example:
6278−.IP
6279−.nf
6280−\f[C]
6281−---
6282−references:
6283−- type: article-journal
6284− id: WatsonCrick1953
6285− author:
6286− - family: Watson
6287− given: J. D.
6288− - family: Crick
6289− given: F. H. C.
6290− issued:
6291− date-parts:
6292− - - 1953
6293− - 4
6294− - 25
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
6299− volume: 171
6300− issue: 4356
6301− page: 737-738
6302− DOI: 10.1038/171737a0
6303− URL: https://www.nature.com/articles/171737a0
6304− language: en-GB
6305−\&...
6306−\f[R]
6307−.fi
6308−.PP
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
6312−precedence.
6313−.PP
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:
6316−.IP
6317−.nf
6318−\f[C]
6319−pandoc chem.bib -s -f biblatex -t markdown
6320−pandoc chem.json -s -f csljson -t markdown
6321−\f[R]
6322−.fi
6323−.PP
6324−Indeed, \f[C]pandoc\f[R] can convert between any of these citation
6325−formats:
6326−.IP
6327−.nf
6328−\f[C]
6329−pandoc chem.bib -s -f biblatex -t csljson
6330−pandoc chem.yaml -s -f markdown -t biblatex
6331−\f[R]
6332−.fi
6333−.PP
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
6336−choice:
6337−.IP
6338−.nf
6339−\f[C]
6340−pandoc chem.bib -s --citeproc -o chem.html
6341−pandoc chem.bib -s --citeproc -o chem.pdf
6342−\f[R]
6343−.fi
6344−.SS Capitalization in titles
6345−.PP
6346−If you are using a bibtex or biblatex bibliography, then observe the
6347−following rules:
6348−.IP \[bu] 2
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].)
6356−.IP \[bu] 2
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.
6360−For example:
6361−.RS 2
6362−.IP
6363−.nf
6364−\f[C]
6365−title = {My Dinner with {Andre}}
6366−\f[R]
6367−.fi
6368−.RE
6369−.IP \[bu] 2
6370−In addition, words that should remain lowercase (or camelCase) should be
6371−protected:
6372−.RS 2
6373−.IP
6374−.nf
6375−\f[C]
6376−title = {Spin Wave Dispersion on the {nm} Scale}
6377−\f[R]
6378−.fi
6379−.PP
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.
6385−.RE
6386−.PP
6387−If you are using a CSL bibliography (either JSON or YAML), then observe
6388−the following rules:
6389−.IP \[bu] 2
6390−All titles should be in sentence case.
6391−.IP \[bu] 2
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]
6395−or is left empty.)
6396−.IP \[bu] 2
6397−Protect words that should not be converted to title case using this
6398−syntax:
6399−.RS 2
6400−.IP
6401−.nf
6402−\f[C]
6403−Spin wave dispersion on the <span class=\[dq]nocase\[dq]>nm</span> scale
6404−\f[R]
6405−.fi
6406−.RE
6407−.SS Conference Papers, Published vs.\ Unpublished
6408−.PP
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]).
6412−.PP
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]).
6416−.PP
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
6420−\f[C]speech\f[R]).
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
6429−.PP
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
6435−format.
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.
6439−.PP
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
6444−specified.
6445−The format of the file can be illustrated with an example:
6446−.IP
6447−.nf
6448−\f[C]
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]
6454− }
6455− }
6456−}
6457−\f[R]
6458−.fi
6459−.SS Citations in note styles
6460−.PP
6461−Pandoc\[cq]s citation processing is designed to allow you to move
6462−between author-date, numerical, and note styles without modifying the
6463−markdown source.
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,
6467−.IP
6468−.nf
6469−\f[C]
6470−Blah blah [\[at]foo, p. 33].
6471−\f[R]
6472−.fi
6473−.PP
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
6478−metadata fields.
6479−.PP
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:
6486−.IP
6487−.nf
6488−\f[C]
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].
6492−\f[R]
6493−.fi
6494−.SS Raw content in a style
6495−.PP
6496−To include raw content in a prefix, suffix, delimiter, or term, surround
6497−it with these tags indicating the format:
6498−.IP
6499−.nf
6500−\f[C]
6501−{{jats}}<ref>{{/jats}}
6502−\f[R]
6503−.fi
6504−.PP
6505−Without the tags, the string will be interpreted as a string and escaped
6506−in the output, rather than being passed through raw.
6507−.PP
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
6513−.PP
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:
6516−.IP
6517−.nf
6518−\f[C]
6519−::: {#refs}
6520−:::
6521−\f[R]
6522−.fi
6523−.PP
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.
6527−.PP
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:
6532−.IP
6533−.nf
6534−\f[C]
6535−last paragraph...
6536−
6537−# References
6538−\f[R]
6539−.fi
6540−.PP
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
6545−.PP
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:
6549−.IP
6550−.nf
6551−\f[C]
6552−---
6553−nocite: |
6554− \[at]item1, \[at]item2
6555−\&...
6556−
6557−\[at]item3
6558−\f[R]
6559−.fi
6560−.PP
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].
6564−.PP
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:
6567−.IP
6568−.nf
6569−\f[C]
6570−---
6571−nocite: |
6572− \[at]*
6573−\&...
6574−\f[R]
6575−.fi
6576−.PP
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]
6581−invocation.
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
6585−.PP
6586−A few other metadata fields affect bibliography formatting:
6587−.TP
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).
65916021.TP
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.)
6598−.RS
6599−.PP
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:
6605−.IP \[bu] 2
6606−\f[C]zh-u-co-pinyin\f[R] \[en] Chinese with the Pinyin collation.
6607−.IP \[bu] 2
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]).
6610−.IP \[bu] 2
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]).
6613−.IP \[bu] 2
6614−\f[C]en-US-u-kf-upper\f[R] \[en] English with uppercase letters sorting
6615−before lower (default is lower before upper).
6616−.RE
6617−.TP
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
6022+\f[B]\f[CB]markdown_phpextra\f[B]\f[R] (PHP Markdown Extra)
6023+\f[C]footnotes\f[R], \f[C]pipe_tables\f[R], \f[C]raw_html\f[R],
6024+\f[C]markdown_attribute\f[R], \f[C]fenced_code_blocks\f[R],
6025+\f[C]definition_lists\f[R], \f[C]intraword_underscores\f[R],
6026+\f[C]header_attributes\f[R], \f[C]link_attributes\f[R],
6027+\f[C]abbreviations\f[R], \f[C]shortcut_reference_links\f[R],
6028+\f[C]spaced_reference_links\f[R].
6029+.TP
6030+\f[B]\f[CB]markdown_github\f[B]\f[R] (deprecated GitHub-Flavored Markdown)
6031+\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
6032+\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
6033+\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
6034+\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
6035+\f[C]strikeout\f[R], \f[C]task_lists\f[R], \f[C]emoji\f[R],
6036+\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
6037+\f[C]lists_without_preceding_blankline\f[R].
6038+.TP
6039+\f[B]\f[CB]markdown_mmd\f[B]\f[R] (MultiMarkdown)
6040+\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]markdown_attribute\f[R],
6041+\f[C]mmd_link_attributes\f[R], \f[C]tex_math_double_backslash\f[R],
6042+\f[C]intraword_underscores\f[R], \f[C]mmd_title_block\f[R],
6043+\f[C]footnotes\f[R], \f[C]definition_lists\f[R],
6044+\f[C]all_symbols_escapable\f[R], \f[C]implicit_header_references\f[R],
6045+\f[C]auto_identifiers\f[R], \f[C]mmd_header_identifiers\f[R],
6046+\f[C]shortcut_reference_links\f[R], \f[C]implicit_figures\f[R],
6047+\f[C]superscript\f[R], \f[C]subscript\f[R],
6048+\f[C]backtick_code_blocks\f[R], \f[C]spaced_reference_links\f[R],
6049+\f[C]raw_attribute\f[R].
6050+.TP
6051+\f[B]\f[CB]markdown_strict\f[B]\f[R] (Markdown.pl)
6052+\f[C]raw_html\f[R], \f[C]shortcut_reference_links\f[R],
6053+\f[C]spaced_reference_links\f[R].
6054+.PP
6055+We also support \f[C]commonmark\f[R] and \f[C]gfm\f[R] (GitHub-Flavored
6056+Markdown, which is implemented as a set of extensions on
6057+\f[C]commonmark\f[R]).
6058+.PP
6059+Note, however, that \f[C]commonmark\f[R] and \f[C]gfm\f[R] have limited
6060+support for extensions.
6061+Only those listed below (and \f[C]smart\f[R], \f[C]raw_tex\f[R], and
6062+\f[C]hard_line_breaks\f[R]) will work.
6063+The extensions can, however, all be individually disabled.
6064+Also, \f[C]raw_tex\f[R] only affects \f[C]gfm\f[R] output, not input.
6065+.TP
6066+\f[B]\f[CB]gfm\f[B]\f[R] (GitHub-Flavored Markdown)
6067+\f[C]pipe_tables\f[R], \f[C]raw_html\f[R], \f[C]fenced_code_blocks\f[R],
6068+\f[C]auto_identifiers\f[R], \f[C]gfm_auto_identifiers\f[R],
6069+\f[C]backtick_code_blocks\f[R], \f[C]autolink_bare_uris\f[R],
6070+\f[C]space_in_atx_header\f[R], \f[C]intraword_underscores\f[R],
6071+\f[C]strikeout\f[R], \f[C]task_lists\f[R], \f[C]emoji\f[R],
6072+\f[C]shortcut_reference_links\f[R], \f[C]angle_brackets_escapable\f[R],
6073+\f[C]lists_without_preceding_blankline\f[R].
6074+.SH PRODUCING SLIDE SHOWS WITH PANDOC
66276075.PP
66286076You can use pandoc to produce an HTML + JavaScript slide presentation
66296077that can be viewed via a web browser.
@@ -6632,7 +6080,7 @@ reveal.js.
66326080You can also produce a PDF slide show using LaTeX \f[C]beamer\f[R], or
66336081slides shows in Microsoft PowerPoint format.
66346082.PP
6635−Here\[cq]s the Markdown source for a simple slide show,
6083+Here\[aq]s the Markdown source for a simple slide show,
66366084\f[C]habits.txt\f[R]:
66376085.IP
66386086.nf
@@ -6734,26 +6182,21 @@ A heading at the slide level always starts a new slide.
67346182.IP \[bu] 2
67356183Headings \f[I]below\f[R] the slide level in the hierarchy create
67366184headings \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.)
67426185.IP \[bu] 2
67436186Headings \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
6187+\[dq]title slides,\[dq] which just contain the section title and help to
67456188break the slide show into sections.
67466189Non-slide content under these headings will be included on the title
67476190slide (for HTML slide shows) or in a subsequent slide with the same
67486191title (for beamer).
67496192.IP \[bu] 2
6750−A title page is constructed automatically from the document\[cq]s title
6193+A title page is constructed automatically from the document\[aq]s title
67516194block, if present.
67526195(In the case of beamer, this can be disabled by commenting out some
67536196lines in the default template.)
67546197.PP
67556198These 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
6199+If you don\[aq]t care about structuring your slides into sections and
67576200subsections, you can just use level-1 headings for all each slide.
67586201(In that case, level-1 will be the slide level.) But you can also
67596202structure the slide show into sections, as in the example above.
@@ -6765,8 +6208,8 @@ It is not recommended that you use deeper nesting of section levels with
67656208reveal.js.
67666209.SS Incremental lists
67676210.PP
6768−By default, these writers produce lists that display \[lq]all at
6769−once.\[rq] If you want your lists to display incrementally (one item at
6211+By default, these writers produce lists that display \[dq]all at
6212+once.\[dq] If you want your lists to display incrementally (one item at
67706213a time), use the \f[C]-i\f[R] option.
67716214If you want a particular list to depart from the default, put it in a
67726215\f[C]div\f[R] block with class \f[C]incremental\f[R] or
@@ -6819,7 +6262,7 @@ Note: Neither the \f[C]-i/--incremental\f[R] option nor any of the
68196262methods described here currently works for PowerPoint output.
68206263.SS Inserting pauses
68216264.PP
6822−You can add \[lq]pauses\[rq] within a slide by including a paragraph
6265+You can add \[dq]pauses\[dq] within a slide by including a paragraph
68236266containing three dots, separated by spaces:
68246267.IP
68256268.nf
@@ -6842,7 +6285,7 @@ in \f[C]$DATADIR/s5/default\f[R] (for S5), \f[C]$DATADIR/slidy\f[R] (for
68426285Slidy), or \f[C]$DATADIR/slideous\f[R] (for Slideous), where
68436286\f[C]$DATADIR\f[R] is the user data directory (see \f[C]--data-dir\f[R],
68446287above).
6845−The originals may be found in pandoc\[cq]s system data directory
6288+The originals may be found in pandoc\[aq]s system data directory
68466289(generally \f[C]$CABALDIR/pandoc-VERSION/s5/default\f[R]).
68476290Pandoc will look there for any files it does not find in the user data
68486291directory.
@@ -6928,51 +6371,6 @@ contents...
69286371::::::::::::::
69296372\f[R]
69306373.fi
6931−.SS Additional columns attributes in beamer
6932−.PP
6933−The div containers with classes \f[C]columns\f[R] and \f[C]column\f[R]
6934−can optionally have an \f[C]align\f[R] attribute.
6935−The class \f[C]columns\f[R] can optionally have a \f[C]totalwidth\f[R]
6936−attribute or an \f[C]onlytextwidth\f[R] class.
6937−.IP
6938−.nf
6939−\f[C]
6940−:::::::::::::: {.columns align=center totalwidth=8em}
6941−::: {.column width=\[dq]40%\[dq]}
6942−contents...
6943−:::
6944−::: {.column width=\[dq]60%\[dq] align=bottom}
6945−contents...
6946−:::
6947−::::::::::::::
6948−\f[R]
6949−.fi
6950−.PP
6951−The \f[C]align\f[R] attributes on \f[C]columns\f[R] and \f[C]column\f[R]
6952−can be used with the values \f[C]top\f[R], \f[C]top-baseline\f[R],
6953−\f[C]center\f[R] and \f[C]bottom\f[R] to vertically align the columns.
6954−It defaults to \f[C]top\f[R] in \f[C]columns\f[R].
6955−.PP
6956−The \f[C]totalwidth\f[R] attribute limits the width of the columns to
6957−the given value.
6958−.IP
6959−.nf
6960−\f[C]
6961−:::::::::::::: {.columns align=top .onlytextwidth}
6962−::: {.column width=\[dq]40%\[dq] align=center}
6963−contents...
6964−:::
6965−::: {.column width=\[dq]60%\[dq]}
6966−contents...
6967−:::
6968−::::::::::::::
6969−\f[R]
6970−.fi
6971−.PP
6972−The class \f[C]onlytextwidth\f[R] sets the \f[C]totalwidth\f[R] to
6973−\f[C]\[rs]textwidth\f[R].
6974−.PP
6975−See Section 12.7 of the Beamer User\[cq]s Guide for more details.
69766374.SS Frame attributes in beamer
69776375.PP
69786376Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[R] option to
@@ -6988,7 +6386,7 @@ introducing the slide:
69886386.fi
69896387.PP
69906388All 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],
6389+User\[aq]s Guide may also be used: \f[C]allowdisplaybreaks\f[R],
69926390\f[C]allowframebreaks\f[R], \f[C]b\f[R], \f[C]c\f[R], \f[C]t\f[R],
69936391\f[C]environment\f[R], \f[C]label\f[R], \f[C]plain\f[R],
69946392\f[C]shrink\f[R], \f[C]standout\f[R], \f[C]noframenumbering\f[R].
@@ -7013,7 +6411,7 @@ To set an image for a particular reveal.js slide, add
70136411\f[C]{data-background-image=\[dq]/path/to/image\[dq]}\f[R] to the first
70146412slide-level heading on the slide (which may even be empty).
70156413.PP
7016−In reveal.js\[cq]s overview mode, the parallaxBackgroundImage will show
6414+In reveal.js\[aq]s overview mode, the parallaxBackgroundImage will show
70176415up only on the first slide.
70186416.PP
70196417Other reveal.js background settings also work on individual slides,
@@ -7049,7 +6447,7 @@ Slide 1 has background_image.png as its background.
70496447Slide 2 has a special image for its background, even though the heading has no content.
70506448\f[R]
70516449.fi
7052−.SH EPUBS
6450+.SH CREATING EPUBS WITH PANDOC
70536451.SS EPUB Metadata
70546452.PP
70556453EPUB metadata may be specified using the \f[C]--epub-metadata\f[R]
@@ -7103,8 +6501,8 @@ Valid values for \f[C]type\f[R] are \f[C]main\f[R], \f[C]subtitle\f[R],
71036501Either a string value, or an object with fields \f[C]role\f[R],
71046502\f[C]file-as\f[R], and \f[C]text\f[R], or a list of such objects.
71056503Valid 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]
7107−and \[lq]editor\[rq]) to the appropriate marc relators.
6504+attempt to translate the human-readable versions (like \[dq]author\[dq]
6505+and \[dq]editor\[dq]) to the appropriate marc relators.
71086506.TP
71096507\f[B]\f[CB]contributor\f[B]\f[R]
71106508Same format as \f[C]creator\f[R].
@@ -7139,16 +6537,6 @@ A string value.
71396537\f[B]\f[CB]rights\f[B]\f[R]
71406538A string value.
71416539.TP
7142−\f[B]\f[CB]belongs-to-collection\f[B]\f[R]
7143−A string value.
7144−identifies the name of a collection to which the EPUB Publication
7145−belongs.
7146−.TP
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.
7151−.TP
71526540\f[B]\f[CB]cover-image\f[B]\f[R]
71536541A string value (path to cover image).
71546542.TP
@@ -7303,6 +6691,16 @@ T}@T{
73036691frontmatter
73046692T}
73056693T{
6694+seriespage
6695+T}@T{
6696+frontmatter
6697+T}
6698+T{
6699+titlepage
6700+T}@T{
6701+frontmatter
6702+T}
6703+T{
73066704appendix
73076705T}@T{
73086706backmatter
@@ -7343,7 +6741,7 @@ For example:
73436741</audio>
73446742\f[R]
73456743.fi
7346−.SH JUPYTER NOTEBOOKS
6744+.SH CREATING JUPYTER NOTEBOOKS WITH PANDOC
73476745.PP
73486746When creating a Jupyter notebook, pandoc will try to infer the notebook
73496747structure.
@@ -7458,7 +6856,7 @@ hello
74586856If you include raw HTML or TeX in an output cell, use the [raw
74596857attribute][Extension: \f[C]fenced_attribute\f[R]], as shown in the last
74606858cell of the example above.
7461−Although pandoc can process \[lq]bare\[rq] raw HTML and TeX, the result
6859+Although pandoc can process \[dq]bare\[dq] raw HTML and TeX, the result
74626860is often interspersed raw elements and normal textual elements, and in
74636861an output cell pandoc expects a single, connected raw block.
74646862To avoid using raw HTML or TeX except when marked explicitly using raw
@@ -7511,10 +6909,10 @@ pandoc --highlight-style my.theme
75116909.fi
75126910.PP
75136911If 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
6912+highlight a language that isn\[aq]t supported, you can use the
75156913\f[C]--syntax-definition\f[R] option to load a KDE-style XML syntax
75166914definition file.
7517−Before writing your own, have a look at KDE\[cq]s repository of syntax
6915+Before writing your own, have a look at KDE\[aq]s repository of syntax
75186916definitions.
75196917.PP
75206918To disable highlighting, use the \f[C]--no-highlight\f[R] option.
@@ -7523,7 +6921,7 @@ To disable highlighting, use the \f[C]--no-highlight\f[R] option.
75236921Custom styles can be used in the docx and ICML formats.
75246922.SS Output
75256923.PP
7526−By default, pandoc\[cq]s docx and ICML output applies a predefined set
6924+By default, pandoc\[aq]s docx and ICML output applies a predefined set
75276925of styles for blocks such as paragraphs and block quotes, and uses
75286926largely default formatting (italics, bold) for inlines.
75296927This will work for most purposes, especially alongside a
@@ -7544,7 +6942,7 @@ So, for example, using the \f[C]bracketed_spans\f[R] syntax,
75446942\f[R]
75456943.fi
75466944.PP
7547−would produce a docx file with \[lq]Get out\[rq] styled with character
6945+would produce a docx file with \[dq]Get out\[dq] styled with character
75486946style \f[C]Emphatically\f[R].
75496947Similarly, using the \f[C]fenced_divs\f[R] syntax,
75506948.IP
@@ -7575,13 +6973,13 @@ character style (perhaps to change their color), you can write a filter
75756973which will transform all italicized inlines to inlines within an
75766974\f[C]Emphasis\f[R] custom-style \f[C]span\f[R].
75776975.PP
7578−For docx output, you don\[cq]t need to enable any extensions for custom
6976+For docx output, you don\[aq]t need to enable any extensions for custom
75796977styles to work.
75806978.SS Input
75816979.PP
75826980The docx reader, by default, only reads those styles that it can convert
75836981into pandoc elements, either by direct conversion or interpreting the
7584−derivation of the input document\[cq]s styles.
6982+derivation of the input document\[aq]s styles.
75856983.PP
75866984By enabling the \f[C]styles\f[R] extension in the docx reader
75876985(\f[C]-f docx+styles\f[R]), you can produce output that maintains the
@@ -7664,20 +7062,6 @@ need to specify a template manually using \f[C]--template\f[R] or add a
76647062new default template with the name
76657063\f[C]default.NAME_OF_CUSTOM_WRITER.lua\f[R] to the \f[C]templates\f[R]
76667064subdirectory of your user data directory (see Templates).
7667−.SH REPRODUCIBLE BUILDS
7668−.PP
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).
7677−.PP
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).
76817065.SH A NOTE ON SECURITY
76827066.PP
76837067If you use pandoc to convert user-contributed content in a web
@@ -7696,7 +7080,7 @@ fully isolates pandoc from your file system, by running the pandoc
76967080operations in the \f[C]PandocPure\f[R] monad.
76977081See the document Using the pandoc API for more details.
76987082.IP "3." 3
7699−Pandoc\[cq]s parsers can exhibit pathological performance on some corner
7083+Pandoc\[aq]s parsers can exhibit pathological performance on some corner
77007084cases.
77017085It is wise to put any pandoc operations under a timeout, to avoid DOS
77027086attacks that exploit these issues.
@@ -7708,16 +7092,16 @@ The HTML generated by pandoc is not guaranteed to be safe.
77087092If \f[C]raw_html\f[R] is enabled for the Markdown input, users can
77097093inject arbitrary HTML.
77107094Even if \f[C]raw_html\f[R] is disabled, users can include dangerous
7711−content in URLs and attributes.
7095+content in attributes for headings, spans, and code blocks.
77127096To be safe, you should run all the generated HTML through an HTML
77137097sanitizer.
77147098.SH AUTHORS
77157099.PP
7716−Copyright 2006\[en]2021 John MacFarlane (jgm\[at]berkeley.edu).
7100+Copyright 2006--2020 John MacFarlane (jgm\[at]berkeley.edu).
77177101Released under the GPL, version 2 or greater.
77187102This software carries no warranty of any kind.
77197103(See COPYRIGHT for full copyright and warranty notices.) For a full list
77207104of contributors, see the file AUTHORS.md in the pandoc source code.
77217105.PP
77227106The Pandoc source code and all documentation may be downloaded
7723−from <https://pandoc.org>.
7107+from <http://pandoc.org>.