@@ -1,6520 +0,0 @@
1−---
2−title: Pandoc User's Guide
3−author: John MacFarlane
4−date: June 20, 2021
5−---
6−
7−# Synopsis
8−
9−`pandoc` [*options*] [*input-file*]...
10−
11−# Description
12−
13−Pandoc is a [Haskell] library for converting from one markup format to
14−another, and a command-line tool that uses this library.
15−
16−Pandoc can convert between numerous markup and word processing formats,
17−including, but not limited to, various flavors of [Markdown], [HTML],
18−[LaTeX] and [Word docx]. For the full lists of input and output formats,
19−see the `--from` and `--to` [options below][General options].
20−Pandoc can also produce [PDF] output: see [creating a PDF], below.
21−
22−Pandoc's enhanced version of Markdown includes syntax for [tables],
23−[definition lists], [metadata blocks], [footnotes], [citations], [math],
24−and much more. See below under [Pandoc's Markdown].
25−
26−Pandoc has a modular design: it consists of a set of readers, which parse
27−text in a given format and produce a native representation of the document
28−(an _abstract syntax tree_ or AST), and a set of writers, which convert
29−this native representation into a target format. Thus, adding an input
30−or output format requires only adding a reader or writer. Users can also
31−run custom [pandoc filters] to modify the intermediate AST.
32−
33−Because pandoc's intermediate representation of a document is less
34−expressive than many of the formats it converts between, one should
35−not expect perfect conversions between every format and every other.
36−Pandoc attempts to preserve the structural elements of a document, but
37−not formatting details such as margin size. And some document elements,
38−such as complex tables, may not fit into pandoc's simple document
39−model. While conversions from pandoc's Markdown to all formats aspire
40−to be perfect, conversions from formats more expressive than pandoc's
41−Markdown can be expected to be lossy.
42−
43−## Using pandoc
44−
45−If no *input-files* are specified, input is read from *stdin*.
46−Output goes to *stdout* by default. For output to a file,
47−use the `-o` option:
48−
49− pandoc -o output.html input.txt
50−
51−By default, pandoc produces a document fragment. To produce a standalone
52−document (e.g. a valid HTML file including `<head>` and `<body>`),
53−use the `-s` or `--standalone` flag:
54−
55− pandoc -s -o output.html input.txt
56−
57−For more information on how standalone documents are produced, see
58−[Templates] below.
59−
60−If multiple input files are given, `pandoc` will concatenate them all (with
61−blank lines between them) before parsing. (Use `--file-scope` to parse files
62−individually.)
63−
64−## Specifying formats
65−
66−The format of the input and output can be specified explicitly using
67−command-line options. The input format can be specified using the
68−`-f/--from` option, the output format using the `-t/--to` option.
69−Thus, to convert `hello.txt` from Markdown to LaTeX, you could type:
70−
71− pandoc -f markdown -t latex hello.txt
72−
73−To convert `hello.html` from HTML to Markdown:
74−
75− pandoc -f html -t markdown hello.html
76−
77−Supported input and output formats are listed below under [Options]
78−(see `-f` for input formats and `-t` for output formats). You
79−can also use `pandoc --list-input-formats` and
80−`pandoc --list-output-formats` to print lists of supported
81−formats.
82−
83−If the input or output format is not specified explicitly, `pandoc`
84−will attempt to guess it from the extensions of the filenames.
85−Thus, for example,
86−
87− pandoc -o hello.tex hello.txt
88−
89−will convert `hello.txt` from Markdown to LaTeX. If no output file
90−is specified (so that output goes to *stdout*), or if the output file's
91−extension is unknown, the output format will default to HTML.
92−If no input file is specified (so that input comes from *stdin*), or
93−if the input files' extensions are unknown, the input format will
94−be assumed to be Markdown.
95−
96−## Character encoding
97−
98−Pandoc uses the UTF-8 character encoding for both input and output.
99−If your local character encoding is not UTF-8, you
100−should pipe input and output through [`iconv`]:
101−
102− iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
103−
104−Note that in some output formats (such as HTML, LaTeX, ConTeXt,
105−RTF, OPML, DocBook, and Texinfo), information about
106−the character encoding is included in the document header, which
107−will only be included if you use the `-s/--standalone` option.
108−
109−[`iconv`]: https://www.gnu.org/software/libiconv/
110−
111−## Creating a PDF
112−
113−To produce a PDF, specify an output file with a `.pdf` extension:
114−
115− pandoc test.txt -o test.pdf
116−
117−By default, pandoc will use LaTeX to create the PDF, which requires
118−that a LaTeX engine be installed (see `--pdf-engine` below).
119−Alternatively, pandoc can use ConTeXt, roff ms, or HTML as an
120−intermediate format. To do this, specify an output file with a
121−`.pdf` extension, as before, but add the `--pdf-engine` option
122−or `-t context`, `-t html`, or `-t ms` to the command line.
123−The tool used to generate the PDF from the intermediate format
124−may be specified using `--pdf-engine`.
125−
126−You can control the PDF style using variables, depending on
127−the intermediate format used: see [variables for LaTeX],
128−[variables for ConTeXt], [variables for `wkhtmltopdf`],
129−[variables for ms]. When HTML is used as an intermediate
130−format, the output can be styled using `--css`.
131−
132−To debug the PDF creation, it can be useful to look at the intermediate
133−representation: instead of `-o test.pdf`, use for example `-s -o test.tex`
134−to output the generated LaTeX. You can then test it with `pdflatex test.tex`.
135−
136−When using LaTeX, the following packages need to be available
137−(they are included with all recent versions of [TeX Live]):
138−[`amsfonts`], [`amsmath`], [`lm`], [`unicode-math`],
139−[`iftex`], [`listings`] (if the
140−`--listings` option is used), [`fancyvrb`], [`longtable`],
141−[`booktabs`], [`graphicx`] (if the document
142−contains images), [`hyperref`], [`xcolor`],
143−[`ulem`], [`geometry`] (with the `geometry` variable set),
144−[`setspace`] (with `linestretch`), and
145−[`babel`] (with `lang`). The use of `xelatex` or `lualatex` as
146−the PDF engine requires [`fontspec`]. `lualatex` uses
147−[`selnolig`]. `xelatex` uses [`polyglossia`] (with `lang`),
148−[`xecjk`], and [`bidi`] (with the `dir` variable set). If the
149−`mathspec` variable is set, `xelatex` will use [`mathspec`]
150−instead of [`unicode-math`]. The [`upquote`] and [`microtype`]
151−packages are used if available, and [`csquotes`] will be used
152−for [typography] if the `csquotes` variable or metadata field is
153−set to a true value. The [`natbib`], [`biblatex`], [`bibtex`],
154−and [`biber`] packages can optionally be used for [citation
155−rendering]. The following packages will be used to improve
156−output quality if present, but pandoc does not require them to
157−be present: [`upquote`] (for straight quotes in verbatim
158−environments), [`microtype`] (for better spacing adjustments),
159−[`parskip`] (for better inter-paragraph spaces), [`xurl`] (for
160−better line breaks in URLs), [`bookmark`] (for better PDF
161−bookmarks), and [`footnotehyper`] or [`footnote`] (to allow
162−footnotes in tables).
163−
164−[TeX Live]: https://www.tug.org/texlive/
165−[`amsfonts`]: https://ctan.org/pkg/amsfonts
166−[`amsmath`]: https://ctan.org/pkg/amsmath
167−[`babel`]: https://ctan.org/pkg/babel
168−[`biber`]: https://ctan.org/pkg/biber
169−[`biblatex`]: https://ctan.org/pkg/biblatex
170−[`bibtex`]: https://ctan.org/pkg/bibtex
171−[`bidi`]: https://ctan.org/pkg/bidi
172−[`bookmark`]: https://ctan.org/pkg/bookmark
173−[`booktabs`]: https://ctan.org/pkg/booktabs
174−[`csquotes`]: https://ctan.org/pkg/csquotes
175−[`fancyvrb`]: https://ctan.org/pkg/fancyvrb
176−[`fontspec`]: https://ctan.org/pkg/fontspec
177−[`footnote`]: https://ctan.org/pkg/footnote
178−[`footnotehyper`]: https://ctan.org/pkg/footnotehyper
179−[`geometry`]: https://ctan.org/pkg/geometry
180−[`graphicx`]: https://ctan.org/pkg/graphicx
181−[`grffile`]: https://ctan.org/pkg/grffile
182−[`hyperref`]: https://ctan.org/pkg/hyperref
183−[`iftex`]: https://ctan.org/pkg/iftex
184−[`listings`]: https://ctan.org/pkg/listings
185−[`lm`]: https://ctan.org/pkg/lm
186−[`longtable`]: https://ctan.org/pkg/longtable
187−[`mathspec`]: https://ctan.org/pkg/mathspec
188−[`microtype`]: https://ctan.org/pkg/microtype
189−[`natbib`]: https://ctan.org/pkg/natbib
190−[`parskip`]: https://ctan.org/pkg/parskip
191−[`polyglossia`]: https://ctan.org/pkg/polyglossia
192−[`prince`]: https://www.princexml.com/
193−[`setspace`]: https://ctan.org/pkg/setspace
194−[`ulem`]: https://ctan.org/pkg/ulem
195−[`unicode-math`]: https://ctan.org/pkg/unicode-math
196−[`upquote`]: https://ctan.org/pkg/upquote
197−[`weasyprint`]: https://weasyprint.org
198−[`wkhtmltopdf`]: https://wkhtmltopdf.org
199−[`xcolor`]: https://ctan.org/pkg/xcolor
200−[`xecjk`]: https://ctan.org/pkg/xecjk
201−[`xurl`]: https://ctan.org/pkg/xurl
202−[`selnolig`]: https://ctan.org/pkg/selnolig
203−
204−
205−
206−## Reading from the Web
207−
208−Instead of an input file, an absolute URI may be given. In this case
209−pandoc will fetch the content using HTTP:
210−
211− pandoc -f html -t markdown https://www.fsf.org
212−
213−It is possible to supply a custom User-Agent string or other
214−header when requesting a document from a URL:
215−
216− pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
217− https://www.fsf.org
218−
219−# Options
220−
221−## General options {.options}
222−
223−`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
224−
225−: Specify input format. *FORMAT* can be:
226−
227− ::: {#input-formats}
228− - `bibtex` ([BibTeX] bibliography)
229− - `biblatex` ([BibLaTeX] bibliography)
230− - `commonmark` ([CommonMark] Markdown)
231− - `commonmark_x` ([CommonMark] Markdown with extensions)
232− - `creole` ([Creole 1.0])
233− - `csljson` ([CSL JSON] bibliography)
234− - `csv` ([CSV] table)
235− - `docbook` ([DocBook])
236− - `docx` ([Word docx])
237− - `dokuwiki` ([DokuWiki markup])
238− - `epub` ([EPUB])
239− - `fb2` ([FictionBook2] e-book)
240− - `gfm` ([GitHub-Flavored Markdown]),
241− or the deprecated and less accurate `markdown_github`;
242− use [`markdown_github`](#markdown-variants) only
243− if you need extensions not supported in [`gfm`](#markdown-variants).
244− - `haddock` ([Haddock markup])
245− - `html` ([HTML])
246− - `ipynb` ([Jupyter notebook])
247− - `jats` ([JATS] XML)
248− - `jira` ([Jira]/Confluence wiki markup)
249− - `json` (JSON version of native AST)
250− - `latex` ([LaTeX])
251− - `markdown` ([Pandoc's Markdown])
252− - `markdown_mmd` ([MultiMarkdown])
253− - `markdown_phpextra` ([PHP Markdown Extra])
254− - `markdown_strict` (original unextended [Markdown])
255− - `mediawiki` ([MediaWiki markup])
256− - `man` ([roff man])
257− - `muse` ([Muse])
258− - `native` (native Haskell)
259− - `odt` ([ODT])
260− - `opml` ([OPML])
261− - `org` ([Emacs Org mode])
262− - `rst` ([reStructuredText])
263− - `t2t` ([txt2tags])
264− - `textile` ([Textile])
265− - `tikiwiki` ([TikiWiki markup])
266− - `twiki` ([TWiki markup])
267− - `vimwiki` ([Vimwiki])
268− :::
269−
270− Extensions can be individually enabled or disabled by
271− appending `+EXTENSION` or `-EXTENSION` to the format name.
272− See [Extensions] below, for a list of extensions and
273− their names. See `--list-input-formats` and `--list-extensions`,
274− below.
275−
276−`-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
277−
278−: Specify output format. *FORMAT* can be:
279−
280− ::: {#output-formats}
281− - `asciidoc` ([AsciiDoc]) or `asciidoctor` ([AsciiDoctor])
282− - `beamer` ([LaTeX beamer][`beamer`] slide show)
283− - `bibtex` ([BibTeX] bibliography)
284− - `biblatex` ([BibLaTeX] bibliography)
285− - `commonmark` ([CommonMark] Markdown)
286− - `commonmark_x` ([CommonMark] Markdown with extensions)
287− - `context` ([ConTeXt])
288− - `csljson` ([CSL JSON] bibliography)
289− - `docbook` or `docbook4` ([DocBook] 4)
290− - `docbook5` (DocBook 5)
291− - `docx` ([Word docx])
292− - `dokuwiki` ([DokuWiki markup])
293− - `epub` or `epub3` ([EPUB] v3 book)
294− - `epub2` (EPUB v2)
295− - `fb2` ([FictionBook2] e-book)
296− - `gfm` ([GitHub-Flavored Markdown]),
297− or the deprecated and less accurate `markdown_github`;
298− use [`markdown_github`](#markdown-variants) only
299− if you need extensions not supported in [`gfm`](#markdown-variants).
300− - `haddock` ([Haddock markup])
301− - `html` or `html5` ([HTML], i.e. [HTML5]/XHTML [polyglot markup])
302− - `html4` ([XHTML] 1.0 Transitional)
303− - `icml` ([InDesign ICML])
304− - `ipynb` ([Jupyter notebook])
305− - `jats_archiving` ([JATS] XML, Archiving and Interchange Tag Set)
306− - `jats_articleauthoring` ([JATS] XML, Article Authoring Tag Set)
307− - `jats_publishing` ([JATS] XML, Journal Publishing Tag Set)
308− - `jats` (alias for `jats_archiving`)
309− - `jira` ([Jira]/Confluence wiki markup)
310− - `json` (JSON version of native AST)
311− - `latex` ([LaTeX])
312− - `man` ([roff man])
313− - `markdown` ([Pandoc's Markdown])
314− - `markdown_mmd` ([MultiMarkdown])
315− - `markdown_phpextra` ([PHP Markdown Extra])
316− - `markdown_strict` (original unextended [Markdown])
317− - `mediawiki` ([MediaWiki markup])
318− - `ms` ([roff ms])
319− - `muse` ([Muse]),
320− - `native` (native Haskell),
321− - `odt` ([OpenOffice text document][ODT])
322− - `opml` ([OPML])
323− - `opendocument` ([OpenDocument])
324− - `org` ([Emacs Org mode])
325− - `pdf` ([PDF])
326− - `plain` (plain text),
327− - `pptx` ([PowerPoint] slide show)
328− - `rst` ([reStructuredText])
329− - `rtf` ([Rich Text Format])
330− - `texinfo` ([GNU Texinfo])
331− - `textile` ([Textile])
332− - `slideous` ([Slideous] HTML and JavaScript slide show)
333− - `slidy` ([Slidy] HTML and JavaScript slide show)
334− - `dzslides` ([DZSlides] HTML5 + JavaScript slide show),
335− - `revealjs` ([reveal.js] HTML5 + JavaScript slide show)
336− - `s5` ([S5] HTML and JavaScript slide show)
337− - `tei` ([TEI Simple])
338− - `xwiki` ([XWiki markup])
339− - `zimwiki` ([ZimWiki markup])
340− - the path of a custom Lua writer, see [Custom writers] below
341− :::
342−
343− Note that `odt`, `docx`, `epub`, and `pdf` output will not be directed
344− to *stdout* unless forced with `-o -`.
345−
346− Extensions can be individually enabled or
347− disabled by appending `+EXTENSION` or `-EXTENSION` to the format
348− name. See [Extensions] below, for a list of extensions and their
349− names. See `--list-output-formats` and `--list-extensions`, below.
350−
351−`-o` *FILE*, `--output=`*FILE*
352−
353−: Write output to *FILE* instead of *stdout*. If *FILE* is
354− `-`, output will go to *stdout*, even if a non-textual format
355− (`docx`, `odt`, `epub2`, `epub3`) is specified.
356−
357−`--data-dir=`*DIRECTORY*
358−
359−: Specify the user data directory to search for pandoc data files.
360− If this option is not specified, the default user data directory
361− will be used. On \*nix and macOS systems this will be the `pandoc`
362− subdirectory of the XDG data directory (by default,
363− `$HOME/.local/share`, overridable by setting the `XDG_DATA_HOME`
364− environment variable). If that directory does not exist and
365− `$HOME/.pandoc` exists, it will be used (for backwards compatibility).
366− On Windows the default user data directory is
367− `C:\Users\USERNAME\AppData\Roaming\pandoc`.
368− You can find the default user data directory on your system by
369− looking at the output of `pandoc --version`.
370− Data files placed in this directory (for example, `reference.odt`,
371− `reference.docx`, `epub.css`, `templates`) will override
372− pandoc's normal defaults.
373−
374−`-d` *FILE*, `--defaults=`*FILE*
375−
376−: Specify a set of default option settings. *FILE* is a YAML
377− file whose fields correspond to command-line option
378− settings. All options for document conversion, including input
379− and output files, can be set using a defaults file. The file will
380− be searched for first in the working directory, and then in
381− the `defaults` subdirectory of the user data directory
382− (see `--data-dir`). The `.yaml` extension may be omitted.
383− See the section [Default files] for more information on the
384− file format. Settings from the defaults file may be
385− overridden or extended by subsequent options on the command
386− line.
387−
388−`--bash-completion`
389−
390−: Generate a bash completion script. To enable bash completion
391− with pandoc, add this to your `.bashrc`:
392−
393− eval "$(pandoc --bash-completion)"
394−
395−`--verbose`
396−
397−: Give verbose debugging output.
398−
399−`--quiet`
400−
401−: Suppress warning messages.
402−
403−`--fail-if-warnings`
404−
405−: Exit with error status if there are any warnings.
406−
407−`--log=`*FILE*
408−
409−: Write log messages in machine-readable JSON format to
410− *FILE*. All messages above DEBUG level will be written,
411− regardless of verbosity settings (`--verbose`, `--quiet`).
412−
413−`--list-input-formats`
414−
415−: List supported input formats, one per line.
416−
417−`--list-output-formats`
418−
419−: List supported output formats, one per line.
420−
421−`--list-extensions`[`=`*FORMAT*]
422−
423−: List supported extensions for *FORMAT*, one per line, preceded
424− by a `+` or `-` indicating whether it is enabled by default
425− in *FORMAT*. If *FORMAT* is not specified, defaults for
426− pandoc's Markdown are given.
427−
428−`--list-highlight-languages`
429−
430−: List supported languages for syntax highlighting, one per
431− line.
432−
433−`--list-highlight-styles`
434−
435−: List supported styles for syntax highlighting, one per line.
436− See `--highlight-style`.
437−
438−`-v`, `--version`
439−
440−: Print version.
441−
442−`-h`, `--help`
443−
444−: Show usage message.
445−
446−[Markdown]: https://daringfireball.net/projects/markdown/
447−[CommonMark]: https://commonmark.org
448−[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/
449−[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/
450−[MultiMarkdown]: https://fletcherpenney.net/multimarkdown/
451−[reStructuredText]: https://docutils.sourceforge.io/docs/ref/rst/introduction.html
452−[S5]: https://meyerweb.com/eric/tools/s5/
453−[Slidy]: https://www.w3.org/Talks/Tools/Slidy2/
454−[Slideous]: https://goessner.net/articles/slideous/
455−[HTML]: https://www.w3.org/html/
456−[HTML5]: https://html.spec.whatwg.org/
457−[polyglot markup]: https://www.w3.org/TR/html-polyglot/
458−[XHTML]: https://www.w3.org/TR/xhtml1/
459−[LaTeX]: https://www.latex-project.org/
460−[`beamer`]: https://ctan.org/pkg/beamer
461−[Beamer User's Guide]: http://mirrors.ctan.org/macros/latex/contrib/beamer/doc/beameruserguide.pdf
462−[ConTeXt]: https://www.contextgarden.net/
463−[Rich Text Format]: https://en.wikipedia.org/wiki/Rich_Text_Format
464−[DocBook]: https://docbook.org
465−[JATS]: https://jats.nlm.nih.gov
466−[Jira]: https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all
467−[txt2tags]: https://txt2tags.org
468−[EPUB]: http://idpf.org/epub
469−[OPML]: http://dev.opml.org/spec2.html
470−[OpenDocument]: http://opendocument.xml.org
471−[ODT]: https://en.wikipedia.org/wiki/OpenDocument
472−[Textile]: https://www.promptworks.com/textile
473−[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting
474−[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
475−[ZimWiki markup]: https://zim-wiki.org/manual/Help/Wiki_Syntax.html
476−[XWiki markup]: https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/
477−[TWiki markup]: https://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
478−[TikiWiki markup]: https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wiki-Syntax
479−[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
480−[Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0
481−[CSV]: https://tools.ietf.org/html/rfc4180
482−[roff man]: https://man.cx/groff_man(7)
483−[roff ms]: https://man.cx/groff_ms(7)
484−[Haskell]: https://www.haskell.org
485−[GNU Texinfo]: https://www.gnu.org/software/texinfo/
486−[Emacs Org mode]: https://orgmode.org
487−[AsciiDoc]: https://www.methods.co.nz/asciidoc/
488−[AsciiDoctor]: https://asciidoctor.org/
489−[DZSlides]: https://paulrouget.com/dzslides/
490−[Word docx]: https://en.wikipedia.org/wiki/Office_Open_XML
491−[PDF]: https://www.adobe.com/pdf/
492−[reveal.js]: https://revealjs.com/
493−[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
494−[Jupyter notebook]: https://nbformat.readthedocs.io/en/latest/
495−[InDesign ICML]: https://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-cookbook.pdf
496−[TEI Simple]: https://github.com/TEIC/TEI-Simple
497−[Muse]: https://amusewiki.org/library/manual
498−[PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint
499−[Vimwiki]: https://vimwiki.github.io
500−[CSL JSON]: https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html
501−[BibTeX]: https://ctan.org/pkg/bibtex
502−[BibLaTeX]: https://ctan.org/pkg/biblatex
503−
504−## Reader options {.options}
505−
506−`--shift-heading-level-by=`*NUMBER*
507−
508−: Shift heading levels by a positive or negative integer.
509− For example, with `--shift-heading-level-by=-1`, level 2
510− headings become level 1 headings, and level 3 headings
511− become level 2 headings. Headings cannot have a level
512− less than 1, so a heading that would be shifted below level 1
513− becomes a regular paragraph. Exception: with a shift of -N,
514− a level-N heading at the beginning of the document
515− replaces the metadata title. `--shift-heading-level-by=-1`
516− is a good choice when converting HTML or Markdown documents that
517− use an initial level-1 heading for the document title and
518− level-2+ headings for sections. `--shift-heading-level-by=1`
519− may be a good choice for converting Markdown documents that
520− use level-1 headings for sections to HTML, since pandoc uses
521− a level-1 heading to render the document title.
522−
523−`--base-header-level=`*NUMBER*
524−
525−: *Deprecated. Use `--shift-heading-level-by`=X instead,
526− where X = NUMBER - 1.* Specify the base level for headings
527− (defaults to 1).
528−
529−`--strip-empty-paragraphs`
530−
531−: *Deprecated. Use the `+empty_paragraphs` extension instead.*
532− Ignore paragraphs with no content. This option is useful
533− for converting word processing documents where users have
534− used empty paragraphs to create inter-paragraph space.
535−
536−`--indented-code-classes=`*CLASSES*
537−
538−: Specify classes to use for indented code blocks--for example,
539− `perl,numberLines` or `haskell`. Multiple classes may be separated
540− by spaces or commas.
541−
542−`--default-image-extension=`*EXTENSION*
543−
544−: Specify a default extension to use when image paths/URLs have no
545− extension. This allows you to use the same source for formats that
546− require different kinds of images. Currently this option only affects
547− the Markdown and LaTeX readers.
548−
549−`--file-scope`
550−
551−: Parse each file individually before combining for multifile
552− documents. This will allow footnotes in different files with the
553− same identifiers to work as expected. If this option is set,
554− footnotes and links will not work across files. Reading binary
555− files (docx, odt, epub) implies `--file-scope`.
556−
557−`-F` *PROGRAM*, `--filter=`*PROGRAM*
558−
559−: Specify an executable to be used as a filter transforming the
560− pandoc AST after the input is parsed and before the output is
561− written. The executable should read JSON from stdin and write
562− JSON to stdout. The JSON must be formatted like pandoc's own
563− JSON input and output. The name of the output format will be
564− passed to the filter as the first argument. Hence,
565−
566− pandoc --filter ./caps.py -t latex
567−
568− is equivalent to
569−
570− pandoc -t json | ./caps.py latex | pandoc -f json -t latex
571−
572− The latter form may be useful for debugging filters.
573−
574− Filters may be written in any language. `Text.Pandoc.JSON`
575− exports `toJSONFilter` to facilitate writing filters in Haskell.
576− Those who would prefer to write filters in python can use the
577− module [`pandocfilters`], installable from PyPI. There are also
578− pandoc filter libraries in [PHP], [perl], and
579− [JavaScript/node.js].
580−
581− In order of preference, pandoc will look for filters in
582−
583− 1. a specified full or relative path (executable or
584− non-executable)
585−
586− 2. `$DATADIR/filters` (executable or non-executable)
587− where `$DATADIR` is the user data directory (see
588− `--data-dir`, above).
589−
590− 3. `$PATH` (executable only)
591−
592− Filters, Lua-filters, and citeproc processing are applied in
593− the order specified on the command line.
594−
595−`-L` *SCRIPT*, `--lua-filter=`*SCRIPT*
596−
597−: Transform the document in a similar fashion as JSON filters (see
598− `--filter`), but use pandoc's built-in Lua filtering system. The given
599− Lua script is expected to return a list of Lua filters which will be
600− applied in order. Each Lua filter must contain element-transforming
601− functions indexed by the name of the AST element on which the filter
602− function should be applied.
603−
604− The `pandoc` Lua module provides helper functions for element
605− creation. It is always loaded into the script's Lua environment.
606−
607− See the [Lua filters documentation] for further details.
608−
609− In order of preference, pandoc will look for Lua filters in
610−
611− 1. a specified full or relative path
612−
613− 2. `$DATADIR/filters` where `$DATADIR` is the user data
614− directory (see `--data-dir`, above).
615−
616− Filters, Lua filters, and citeproc processing are applied in
617− the order specified on the command line.
618−
619−`-M` *KEY*[`=`*VAL*], `--metadata=`*KEY*[`:`*VAL*]
620−
621−: Set the metadata field *KEY* to the value *VAL*. A value specified
622− on the command line overrides a value specified in the document
623− using [YAML metadata blocks][Extension: `yaml_metadata_block`].
624− Values will be parsed as YAML boolean or string values. If no value is
625− specified, the value will be treated as Boolean true. Like
626− `--variable`, `--metadata` causes template variables to be set.
627− But unlike `--variable`, `--metadata` affects the metadata of the
628− underlying document (which is accessible from filters and may be
629− printed in some output formats) and metadata values will be escaped
630− when inserted into the template.
631−
632−`--metadata-file=`*FILE*
633−
634−: Read metadata from the supplied YAML (or JSON) file. This
635− option can be used with every input format, but string scalars
636− in the YAML file will always be parsed as Markdown. Generally,
637− the input will be handled the same as in [YAML metadata
638− blocks][Extension: `yaml_metadata_block`]. This option can be
639− used repeatedly to include multiple metadata files; values in
640− files specified later on the command line will be preferred
641− over those specified in earlier files. Metadata values
642− specified inside the document, or by using `-M`, overwrite
643− values specified with this option.
644−
645−`-p`, `--preserve-tabs`
646−
647−: Preserve tabs instead of converting them to spaces. (By default, pandoc
648− converts tabs to spaces before parsing its input.) Note that this will
649− only affect tabs in literal code spans and code blocks. Tabs in regular
650− text are always treated as spaces.
651−
652−`--tab-stop=`*NUMBER*
653−
654−: Specify the number of spaces per tab (default is 4).
655−
656−`--track-changes=accept`|`reject`|`all`
657−
658−: Specifies what to do with insertions, deletions, and comments
659− produced by the MS Word "Track Changes" feature. `accept` (the
660− default) processes all the insertions and deletions.
661− `reject` ignores them. Both `accept` and `reject` ignore comments.
662− `all` includes all insertions, deletions, and comments, wrapped
663− in spans with `insertion`, `deletion`, `comment-start`, and
664− `comment-end` classes, respectively. The author and time of
665− change is included. `all` is useful for scripting: only
666− accepting changes from a certain reviewer, say, or before a
667− certain date. If a paragraph is inserted or deleted,
668− `track-changes=all` produces a span with the class
669− `paragraph-insertion`/`paragraph-deletion` before the
670− affected paragraph break. This option only affects the docx
671− reader.
672−
673−`--extract-media=`*DIR*
674−
675−: Extract images and other media contained in or linked from
676− the source document to the path *DIR*, creating it if
677− necessary, and adjust the images references in the document
678− so they point to the extracted files. Media are downloaded,
679− read from the file system, or extracted from a binary
680− container (e.g. docx), as needed. The original file paths
681− are used if they are relative paths not containing `..`.
682− Otherwise filenames are constructed from the SHA1 hash of
683− the contents.
684−
685−`--abbreviations=`*FILE*
686−
687−: Specifies a custom abbreviations file, with abbreviations
688− one to a line. If this option is not specified, pandoc will
689− read the data file `abbreviations` from the user data
690− directory or fall back on a system default. To see the
691− system default, use
692− `pandoc --print-default-data-file=abbreviations`. The only
693− use pandoc makes of this list is in the Markdown reader.
694− Strings found in this list will be followed by a nonbreaking
695− space, and the period will not produce sentence-ending space
696− in formats like LaTeX. The strings may not contain spaces.
697−
698−[`pandocfilters`]: https://github.com/jgm/pandocfilters
699−[PHP]: https://github.com/vinai/pandocfilters-php
700−[perl]: https://metacpan.org/pod/Pandoc::Filter
701−[JavaScript/node.js]: https://github.com/mvhenderson/pandoc-filter-node
702−[Lua filters documentation]: https://pandoc.org/lua-filters.html
703−
704−## General writer options {.options}
705−
706−`-s`, `--standalone`
707−
708−: Produce output with an appropriate header and footer (e.g. a
709− standalone HTML, LaTeX, TEI, or RTF file, not a fragment). This option
710− is set automatically for `pdf`, `epub`, `epub3`, `fb2`, `docx`, and `odt`
711− output. For `native` output, this option causes metadata to
712− be included; otherwise, metadata is suppressed.
713−
714−`--template=`*FILE*|*URL*
715−
716−: Use the specified file as a custom template for the generated document.
717− Implies `--standalone`. See [Templates], below, for a description
718− of template syntax. If no extension is specified, an extension
719− corresponding to the writer will be added, so that `--template=special`
720− looks for `special.html` for HTML output. If the template is not
721− found, pandoc will search for it in the `templates` subdirectory of
722− the user data directory (see `--data-dir`). If this option is not used,
723− a default template appropriate for the output format will be used (see
724− `-D/--print-default-template`).
725−
726−`-V` *KEY*[`=`*VAL*], `--variable=`*KEY*[`:`*VAL*]
727−
728−: Set the template variable *KEY* to the value *VAL* when rendering the
729− document in standalone mode. If no *VAL* is specified, the
730− key will be given the value `true`.
731−
732−`-D` *FORMAT*, `--print-default-template=`*FORMAT*
733−
734−: Print the system default template for an output *FORMAT*. (See `-t`
735− for a list of possible *FORMAT*s.) Templates in the user data
736− directory are ignored. This option may be used with
737− `-o`/`--output` to redirect output to a file, but
738− `-o`/`--output` must come before `--print-default-template`
739− on the command line.
740−
741− Note that some of the default templates use partials, for
742− example `styles.html`. To print the partials, use
743− `--print-default-data-file`: for example,
744− `--print-default-data-file=templates/styles.html`.
745−
746−`--print-default-data-file=`*FILE*
747−
748−: Print a system default data file. Files in the user data directory
749− are ignored. This option may be used with `-o`/`--output` to
750− redirect output to a file, but `-o`/`--output` must come before
751− `--print-default-data-file` on the command line.
752−
753−`--eol=crlf`|`lf`|`native`
754−
755−: Manually specify line endings: `crlf` (Windows), `lf`
756− (macOS/Linux/UNIX), or `native` (line endings appropriate
757− to the OS on which pandoc is being run). The default is
758− `native`.
759−
760−`--dpi`=*NUMBER*
761−
762−: Specify the default dpi (dots per inch) value for conversion
763− from pixels to inch/centimeters and vice versa. (Technically,
764− the correct term would be ppi: pixels per inch.) The default
765− is 96dpi. When images contain information about dpi
766− internally, the encoded value is used instead of the default
767− specified by this option.
768−
769−`--wrap=auto`|`none`|`preserve`
770−
771−: Determine how text is wrapped in the output (the source
772− code, not the rendered version). With `auto` (the default),
773− pandoc will attempt to wrap lines to the column width specified by
774− `--columns` (default 72). With `none`, pandoc will not wrap
775− lines at all. With `preserve`, pandoc will attempt to
776− preserve the wrapping from the source document (that is,
777− where there are nonsemantic newlines in the source, there
778− will be nonsemantic newlines in the output as well).
779− Automatic wrapping does not currently work in HTML output.
780− In `ipynb` output, this option affects wrapping of the
781− contents of markdown cells.
782−
783−`--columns=`*NUMBER*
784−
785−: Specify length of lines in characters. This affects text wrapping
786− in the generated source code (see `--wrap`). It also affects
787− calculation of column widths for plain text tables (see [Tables] below).
788−
789−`--toc`, `--table-of-contents`
790−
791−: Include an automatically generated table of contents (or, in
792− the case of `latex`, `context`, `docx`, `odt`,
793− `opendocument`, `rst`, or `ms`, an instruction to create
794− one) in the output document. This option has no effect
795− unless `-s/--standalone` is used, and it has no effect
796− on `man`, `docbook4`, `docbook5`, or `jats` output.
797−
798− Note that if you are producing a PDF via `ms`, the table
799− of contents will appear at the beginning of the
800− document, before the title. If you would prefer it to
801− be at the end of the document, use the option
802− `--pdf-engine-opt=--no-toc-relocation`.
803−
804−`--toc-depth=`*NUMBER*
805−
806−: Specify the number of section levels to include in the table
807− of contents. The default is 3 (which means that level-1, 2, and 3
808− headings will be listed in the contents).
809−
810−`--strip-comments`
811−
812−: Strip out HTML comments in the Markdown or Textile source,
813− rather than passing them on to Markdown, Textile or HTML
814− output as raw HTML. This does not apply to HTML comments
815− inside raw HTML blocks when the `markdown_in_html_blocks`
816− extension is not set.
817−
818−`--no-highlight`
819−
820−: Disables syntax highlighting for code blocks and inlines, even when
821− a language attribute is given.
822−
823−`--highlight-style=`*STYLE*|*FILE*
824−
825−: Specifies the coloring style to be used in highlighted source code.
826− Options are `pygments` (the default), `kate`, `monochrome`,
827− `breezeDark`, `espresso`, `zenburn`, `haddock`, and `tango`.
828− For more information on syntax highlighting in pandoc, see
829− [Syntax highlighting], below. See also
830− `--list-highlight-styles`.
831−
832− Instead of a *STYLE* name, a JSON file with extension
833− `.theme` may be supplied. This will be parsed as a KDE
834− syntax highlighting theme and (if valid) used as the
835− highlighting style.
836−
837− To generate the JSON version of an existing style,
838− use `--print-highlight-style`.
839−
840−`--print-highlight-style=`*STYLE*|*FILE*
841−
842−: Prints a JSON version of a highlighting style, which can
843− be modified, saved with a `.theme` extension, and used
844− with `--highlight-style`. This option may be used with
845− `-o`/`--output` to redirect output to a file, but
846− `-o`/`--output` must come before `--print-highlight-style`
847− on the command line.
848−
849−`--syntax-definition=`*FILE*
850−
851−: Instructs pandoc to load a KDE XML syntax definition file,
852− which will be used for syntax highlighting of appropriately
853− marked code blocks. This can be used to add support for
854− new languages or to use altered syntax definitions for
855− existing languages. This option may be repeated to add
856− multiple syntax definitions.
857−
858−`-H` *FILE*, `--include-in-header=`*FILE*|*URL*
859−
860−: Include contents of *FILE*, verbatim, at the end of the header.
861− This can be used, for example, to include special
862− CSS or JavaScript in HTML documents. This option can be used
863− repeatedly to include multiple files in the header. They will be
864− included in the order specified. Implies `--standalone`.
865−
866−`-B` *FILE*, `--include-before-body=`*FILE*|*URL*
867−
868−: Include contents of *FILE*, verbatim, at the beginning of the
869− document body (e.g. after the `<body>` tag in HTML, or the
870− `\begin{document}` command in LaTeX). This can be used to include
871− navigation bars or banners in HTML documents. This option can be
872− used repeatedly to include multiple files. They will be included in
873− the order specified. Implies `--standalone`.
874−
875−`-A` *FILE*, `--include-after-body=`*FILE*|*URL*
876−
877−: Include contents of *FILE*, verbatim, at the end of the document
878− body (before the `</body>` tag in HTML, or the
879− `\end{document}` command in LaTeX). This option can be used
880− repeatedly to include multiple files. They will be included in the
881− order specified. Implies `--standalone`.
882−
883−`--resource-path=`*SEARCHPATH*
884−
885−: List of paths to search for images and other resources.
886− The paths should be separated by `:` on Linux, UNIX, and
887− macOS systems, and by `;` on Windows. If `--resource-path`
888− is not specified, the default resource path is the working
889− directory. Note that, if `--resource-path` is specified,
890− the working directory must be explicitly listed or it
891− will not be searched. For example:
892− `--resource-path=.:test` will search the working directory
893− and the `test` subdirectory, in that order.
894− This option can be used repeatedly. Search path components
895− that come later on the command line will be searched before
896− those that come earlier, so
897− `--resource-path foo:bar --resource-path baz:bim` is
898− equivalent to `--resource-path baz:bim:foo:bar`.
899−
900−`--request-header=`*NAME*`:`*VAL*
901−
902−: Set the request header *NAME* to the value *VAL* when making
903− HTTP requests (for example, when a URL is given on the
904− command line, or when resources used in a document must be
905− downloaded). If you're behind a proxy, you also need to set
906− the environment variable `http_proxy` to `http://...`.
907−
908−`--no-check-certificate`
909−
910−: Disable the certificate verification to allow access to
911− unsecure HTTP resources (for example when the certificate
912− is no longer valid or self signed).
913−
914−## Options affecting specific writers {.options}
915−
916−`--self-contained`
917−
918−: Produce a standalone HTML file with no external dependencies, using
919− `data:` URIs to incorporate the contents of linked scripts, stylesheets,
920− images, and videos. Implies `--standalone`. The resulting file should be
921− "self-contained," in the sense that it needs no external files and no net
922− access to be displayed properly by a browser. This option works only with
923− HTML output formats, including `html4`, `html5`, `html+lhs`, `html5+lhs`,
924− `s5`, `slidy`, `slideous`, `dzslides`, and `revealjs`. Scripts, images,
925− and stylesheets at absolute URLs will be downloaded; those at relative
926− URLs will be sought relative to the working directory (if the first source
927− file is local) or relative to the base URL (if the first source
928− file is remote). Elements with the attribute
929− `data-external="1"` will be left alone; the documents they
930− link to will not be incorporated in the document.
931− Limitation: resources that are loaded dynamically through
932− JavaScript cannot be incorporated; as a result,
933− `--self-contained` does not work with `--mathjax`, and some
934− advanced features (e.g. zoom or speaker notes) may not work
935− in an offline "self-contained" `reveal.js` slide show.
936−
937−`--html-q-tags`
938−
939−: Use `<q>` tags for quotes in HTML. (This option only has an
940− effect if the `smart` extension is enabled for the input
941− format used.)
942−
943−`--ascii`
944−
945−: Use only ASCII characters in output. Currently supported for XML
946− and HTML formats (which use entities instead of UTF-8 when this
947− option is selected), CommonMark, gfm, and Markdown (which use
948− entities), roff ms (which use hexadecimal escapes), and to a
949− limited degree LaTeX (which uses standard commands for accented
950− characters when possible). roff man output uses ASCII by default.
951−
952−`--reference-links`
953−
954−: Use reference-style links, rather than inline links, in writing Markdown
955− or reStructuredText. By default inline links are used. The
956− placement of link references is affected by the
957− `--reference-location` option.
958−
959−`--reference-location=block`|`section`|`document`
960−
961−: Specify whether footnotes (and references, if `reference-links` is
962− set) are placed at the end of the current (top-level) block, the
963− current section, or the document. The default is
964− `document`. Currently only affects the markdown writer.
965−
966−`--markdown-headings=setext`|`atx`
967−
968−: Specify whether to use ATX-style (`#`-prefixed) or
969− Setext-style (underlined) headings for level 1 and 2
970− headings in Markdown output. (The default is `atx`.)
971− ATX-style headings are always used for levels 3+.
972− This option also affects Markdown cells in `ipynb` output.
973−
974−`--atx-headers`
975−
976−: *Deprecated synonym for `--markdown-headings=atx`.*
977−
978−`--top-level-division=default`|`section`|`chapter`|`part`
979−
980−: Treat top-level headings as the given division type in
981− LaTeX, ConTeXt, DocBook, and TEI output. The hierarchy
982− order is part, chapter, then section; all headings are
983− shifted such that the top-level heading becomes the
984− specified type. The default behavior is to determine the
985− best division type via heuristics: unless other conditions
986− apply, `section` is chosen. When the `documentclass`
987− variable is set to `report`, `book`, or `memoir` (unless the
988− `article` option is specified), `chapter` is implied as the
989− setting for this option. If `beamer` is the output format,
990− specifying either `chapter` or `part` will cause top-level
991− headings to become `\part{..}`, while second-level headings
992− remain as their default type.
993−
994−`-N`, `--number-sections`
995−
996−: Number section headings in LaTeX, ConTeXt, HTML, Docx, ms, or EPUB
997− output. By default, sections are not numbered. Sections with class
998− `unnumbered` will never be numbered, even if `--number-sections`
999− is specified.
1000−
1001−`--number-offset=`*NUMBER*[`,`*NUMBER*`,`*...*]
1002−
1003−: Offset for section headings in HTML output (ignored in other
1004− output formats). The first number is added to the section number for
1005− top-level headings, the second for second-level headings, and so on.
1006− So, for example, if you want the first top-level heading in your
1007− document to be numbered "6", specify `--number-offset=5`.
1008− If your document starts with a level-2 heading which you want to
1009− be numbered "1.5", specify `--number-offset=1,4`.
1010− Offsets are 0 by default. Implies `--number-sections`.
1011−
1012−`--listings`
1013−
1014−: Use the [`listings`] package for LaTeX code blocks. The package
1015− does not support multi-byte encoding for source code. To handle UTF-8
1016− you would need to use a custom template. This issue is fully
1017− documented here: [Encoding issue with the listings package].
1018−
1019−`-i`, `--incremental`
1020−
1021−: Make list items in slide shows display incrementally (one by one).
1022− The default is for lists to be displayed all at once.
1023−
1024−`--slide-level=`*NUMBER*
1025−
1026−: Specifies that headings with the specified level create
1027− slides (for `beamer`, `s5`, `slidy`, `slideous`, `dzslides`). Headings
1028− above this level in the hierarchy are used to divide the
1029− slide show into sections; headings below this level create
1030− subheads within a slide. Note that content that is
1031− not contained under slide-level headings will not appear in
1032− the slide show. The default is to set the slide level based
1033− on the contents of the document; see [Structuring the slide
1034− show].
1035−
1036−`--section-divs`
1037−
1038−: Wrap sections in `<section>` tags (or `<div>` tags for `html4`),
1039− and attach identifiers to the enclosing `<section>` (or `<div>`)
1040− rather than the heading itself. See
1041− [Heading identifiers], below.
1042−
1043−`--email-obfuscation=none`|`javascript`|`references`
1044−
1045−: Specify a method for obfuscating `mailto:` links in HTML documents.
1046− `none` leaves `mailto:` links as they are. `javascript` obfuscates
1047− them using JavaScript. `references` obfuscates them by printing their
1048− letters as decimal or hexadecimal character references. The default
1049− is `none`.
1050−
1051−`--id-prefix=`*STRING*
1052−
1053−: Specify a prefix to be added to all identifiers and internal links
1054− in HTML and DocBook output, and to footnote numbers in Markdown
1055− and Haddock output. This is useful for preventing duplicate
1056− identifiers when generating fragments to be included in other pages.
1057−
1058−`-T` *STRING*, `--title-prefix=`*STRING*
1059−
1060−: Specify *STRING* as a prefix at the beginning of the title
1061− that appears in the HTML header (but not in the title as it
1062− appears at the beginning of the HTML body). Implies `--standalone`.
1063−
1064−`-c` *URL*, `--css=`*URL*
1065−
1066−: Link to a CSS style sheet. This option can be used repeatedly to
1067− include multiple files. They will be included in the order specified.
1068−
1069− A stylesheet is required for generating EPUB. If none is
1070− provided using this option (or the `css` or `stylesheet`
1071− metadata fields), pandoc will look for a file `epub.css` in the
1072− user data directory (see `--data-dir`). If it is not
1073− found there, sensible defaults will be used.
1074−
1075−`--reference-doc=`*FILE*
1076−
1077−: Use the specified file as a style reference in producing a
1078− docx or ODT file.
1079−
1080− Docx
1081−
1082− : For best results, the reference docx should be a modified
1083− version of a docx file produced using pandoc. The contents
1084− of the reference docx are ignored, but its stylesheets and
1085− document properties (including margins, page size, header,
1086− and footer) are used in the new docx. If no reference docx
1087− is specified on the command line, pandoc will look for a
1088− file `reference.docx` in the user data directory (see
1089− `--data-dir`). If this is not found either, sensible
1090− defaults will be used.
1091−
1092− To produce a custom `reference.docx`, first get a copy of
1093− the default `reference.docx`: `pandoc
1094− -o custom-reference.docx --print-default-data-file reference.docx`.
1095− Then open `custom-reference.docx` in Word, modify the
1096− styles as you wish, and save the file. For best
1097− results, do not make changes to this file other than
1098− modifying the styles used by pandoc:
1099−
1100− Paragraph styles:
1101−
1102− - Normal
1103− - Body Text
1104− - First Paragraph
1105− - Compact
1106− - Title
1107− - Subtitle
1108− - Author
1109− - Date
1110− - Abstract
1111− - Bibliography
1112− - Heading 1
1113− - Heading 2
1114− - Heading 3
1115− - Heading 4
1116− - Heading 5
1117− - Heading 6
1118− - Heading 7
1119− - Heading 8
1120− - Heading 9
1121− - Block Text
1122− - Footnote Text
1123− - Definition Term
1124− - Definition
1125− - Caption
1126− - Table Caption
1127− - Image Caption
1128− - Figure
1129− - Captioned Figure
1130− - TOC Heading
1131−
1132− Character styles:
1133−
1134− - Default Paragraph Font
1135− - Body Text Char
1136− - Verbatim Char
1137− - Footnote Reference
1138− - Hyperlink
1139− - Section Number
1140−
1141− Table style:
1142−
1143− - Table
1144−
1145− ODT
1146−
1147− : For best results, the reference ODT should be a modified
1148− version of an ODT produced using pandoc. The contents of
1149− the reference ODT are ignored, but its stylesheets are used
1150− in the new ODT. If no reference ODT is specified on the
1151− command line, pandoc will look for a file `reference.odt` in
1152− the user data directory (see `--data-dir`). If this is not
1153− found either, sensible defaults will be used.
1154−
1155− To produce a custom `reference.odt`, first get a copy of
1156− the default `reference.odt`: `pandoc
1157− -o custom-reference.odt --print-default-data-file reference.odt`.
1158− Then open `custom-reference.odt` in LibreOffice, modify
1159− the styles as you wish, and save the file.
1160−
1161− PowerPoint
1162−
1163− : Templates included with Microsoft PowerPoint 2013 (either with
1164− `.pptx` or `.potx` extension) are known to work, as are most
1165− templates derived from these.
1166−
1167− The specific requirement is that the template should begin with
1168− the following first four layouts:
1169−
1170− 1. Title Slide
1171− 2. Title and Content
1172− 3. Section Header
1173− 4. Two Content
1174−
1175− All templates included with a recent version of MS PowerPoint
1176− will fit these criteria. (You can click on `Layout` under the
1177− `Home` menu to check.)
1178−
1179− You can also modify the default `reference.pptx`: first run
1180− `pandoc -o custom-reference.pptx --print-default-data-file
1181− reference.pptx`, and then modify `custom-reference.pptx`
1182− in MS PowerPoint (pandoc will use the first four layout
1183− slides, as mentioned above).
1184−
1185−`--epub-cover-image=`*FILE*
1186−
1187−: Use the specified image as the EPUB cover. It is recommended
1188− that the image be less than 1000px in width and height. Note that
1189− in a Markdown source document you can also specify `cover-image`
1190− in a YAML metadata block (see [EPUB Metadata], below).
1191−
1192−`--epub-metadata=`*FILE*
1193−
1194−: Look in the specified XML file for metadata for the EPUB.
1195− The file should contain a series of [Dublin Core elements].
1196− For example:
1197−
1198− <dc:rights>Creative Commons</dc:rights>
1199− <dc:language>es-AR</dc:language>
1200−
1201− By default, pandoc will include the following metadata elements:
1202− `<dc:title>` (from the document title), `<dc:creator>` (from the
1203− document authors), `<dc:date>` (from the document date, which should
1204− be in [ISO 8601 format]), `<dc:language>` (from the `lang`
1205− variable, or, if is not set, the locale), and `<dc:identifier
1206− id="BookId">` (a randomly generated UUID). Any of these may be
1207− overridden by elements in the metadata file.
1208−
1209− Note: if the source document is Markdown, a YAML metadata block
1210− in the document can be used instead. See below under
1211− [EPUB Metadata].
1212−
1213−`--epub-embed-font=`*FILE*
1214−
1215−: Embed the specified font in the EPUB. This option can be repeated
1216− to embed multiple fonts. Wildcards can also be used: for example,
1217− `DejaVuSans-*.ttf`. However, if you use wildcards on the command
1218− line, be sure to escape them or put the whole filename in single quotes,
1219− to prevent them from being interpreted by the shell. To use the
1220− embedded fonts, you will need to add declarations like the following
1221− to your CSS (see `--css`):
1222−
1223− @font-face {
1224− font-family: DejaVuSans;
1225− font-style: normal;
1226− font-weight: normal;
1227− src:url("DejaVuSans-Regular.ttf");
1228− }
1229− @font-face {
1230− font-family: DejaVuSans;
1231− font-style: normal;
1232− font-weight: bold;
1233− src:url("DejaVuSans-Bold.ttf");
1234− }
1235− @font-face {
1236− font-family: DejaVuSans;
1237− font-style: italic;
1238− font-weight: normal;
1239− src:url("DejaVuSans-Oblique.ttf");
1240− }
1241− @font-face {
1242− font-family: DejaVuSans;
1243− font-style: italic;
1244− font-weight: bold;
1245− src:url("DejaVuSans-BoldOblique.ttf");
1246− }
1247− body { font-family: "DejaVuSans"; }
1248−
1249−`--epub-chapter-level=`*NUMBER*
1250−
1251−: Specify the heading level at which to split the EPUB into separate
1252− "chapter" files. The default is to split into chapters at level-1
1253− headings. This option only affects the internal composition of the
1254− EPUB, not the way chapters and sections are displayed to users. Some
1255− readers may be slow if the chapter files are too large, so for large
1256− documents with few level-1 headings, one might want to use a chapter
1257− level of 2 or 3.
1258−
1259−`--epub-subdirectory=`*DIRNAME*
1260−
1261−: Specify the subdirectory in the OCF container that is to hold
1262− the EPUB-specific contents. The default is `EPUB`. To put
1263− the EPUB contents in the top level, use an empty string.
1264−
1265−`--ipynb-output=all|none|best`
1266−
1267−: Determines how ipynb output cells are treated. `all` means
1268− that all of the data formats included in the original are
1269− preserved. `none` means that the contents of data cells
1270− are omitted. `best` causes pandoc to try to pick the
1271− richest data block in each output cell that is compatible
1272− with the output format. The default is `best`.
1273−
1274−`--pdf-engine=`*PROGRAM*
1275−
1276−: Use the specified engine when producing PDF output.
1277− Valid values are `pdflatex`, `lualatex`, `xelatex`, `latexmk`,
1278− `tectonic`, `wkhtmltopdf`, `weasyprint`, `prince`, `context`,
1279− and `pdfroff`. If the engine is not in your PATH, the full
1280− path of the engine may be specified here. If this option
1281− is not specified, pandoc uses the following defaults
1282− depending on the output format specified using `-t/--to`:
1283−
1284− - `-t latex` or none: `pdflatex` (other options: `xelatex`, `lualatex`,
1285− `tectonic`, `latexmk`)
1286− - `-t context`: `context`
1287− - `-t html`: `wkhtmltopdf` (other options: `prince`, `weasyprint`;
1288− see [print-css.rocks](https://print-css.rocks) for a good
1289− introduction to PDF generation from HTML/CSS.)
1290− - `-t ms`: `pdfroff`
1291−
1292−`--pdf-engine-opt=`*STRING*
1293−
1294−: Use the given string as a command-line argument to the `pdf-engine`.
1295− For example, to use a persistent directory `foo` for `latexmk`'s
1296− auxiliary files, use `--pdf-engine-opt=-outdir=foo`.
1297− Note that no check for duplicate options is done.
1298−
1299−[Dublin Core elements]: https://www.dublincore.org/specifications/dublin-core/dces/
1300−[ISO 8601 format]: https://www.w3.org/TR/NOTE-datetime
1301−[Encoding issue with the listings package]:
1302− https://en.wikibooks.org/wiki/LaTeX/Source_Code_Listings#Encoding_issue
1303−
1304−## Citation rendering {.options}
1305−
1306−`-C`, `--citeproc`
1307−
1308−: Process the citations in the file, replacing them with
1309− rendered citations and adding a bibliography.
1310− Citation processing will not take place unless bibliographic
1311− data is supplied, either through an external file specified
1312− using the `--bibliography` option or the `bibliography`
1313− field in metadata, or via a `references` section in metadata
1314− containing a list of citations in CSL YAML format with
1315− Markdown formatting. The style is controlled by a [CSL]
1316− stylesheet specified using the `--csl` option or the `csl`
1317− field in metadata. (If no stylesheet is specified,
1318− the `chicago-author-date` style will be used by default.)
1319− The citation processing transformation may be applied before
1320− or after filters or Lua filters (see `--filter`,
1321− `--lua-filter`): these transformations are applied in the
1322− order they appear on the command line. For more
1323− information, see the section on [Citations].
1324−
1325−`--bibliography=`*FILE*
1326−
1327−: Set the `bibliography` field in the document's metadata to *FILE*,
1328− overriding any value set in the metadata. If you supply
1329− this argument multiple times, each *FILE* will be added to
1330− bibliography. If *FILE* is a URL, it will be fetched
1331− via HTTP. If *FILE* is not found relative to the
1332− working directory, it will be sought in the resource path
1333− (see `--resource-path`).
1334−
1335−`--csl=`*FILE*
1336−
1337−: Set the `csl` field in the document's metadata to *FILE*,
1338− overriding any value set in the metadata. (This is equivalent to
1339− `--metadata csl=FILE`.) If *FILE* is a URL, it will be
1340− fetched via HTTP. If *FILE* is not found relative to the
1341− working directory, it will be sought in the resource path
1342− (see `--resource-path`) and finally in the `csl`
1343− subdirectory of the pandoc user data directory.
1344−
1345−`--citation-abbreviations=`*FILE*
1346−
1347−: Set the `citation-abbreviations` field in the document's metadata to
1348− *FILE*, overriding any value set in the metadata. (This is equivalent to
1349− `--metadata citation-abbreviations=FILE`.)
1350− If *FILE* is a URL, it will be fetched via HTTP. If *FILE* is not
1351− found relative to the working directory, it will be sought
1352− in the resource path (see `--resource-path`) and finally in
1353− the `csl` subdirectory of the pandoc user data directory.
1354−
1355−`--natbib`
1356−
1357−: Use [`natbib`] for citations in LaTeX output. This option
1358− is not for use with the `--citeproc` option or with PDF
1359− output. It is intended for use in producing a LaTeX file
1360− that can be processed with [`bibtex`].
1361−
1362−`--biblatex`
1363−
1364−: Use [`biblatex`] for citations in LaTeX output. This option
1365− is not for use with the `--citeproc` option or with PDF
1366− output. It is intended for use in producing a LaTeX file
1367− that can be processed with [`bibtex`] or [`biber`].
1368−
1369−## Math rendering in HTML {.options}
1370−
1371−The default is to render TeX math as far as possible using
1372−Unicode characters. Formulas are put inside a `span` with
1373−`class="math"`, so that they may be styled differently from the
1374−surrounding text if needed. However, this gives acceptable
1375−results only for basic math, usually you will want to use
1376−`--mathjax` or another of the following options.
1377−
1378−`--mathjax`[`=`*URL*]
1379−
1380−: Use [MathJax] to display embedded TeX math in HTML output.
1381− TeX math will be put between `\(...\)` (for inline math)
1382− or `\[...\]` (for display math) and wrapped in `<span>` tags
1383− with class `math`. Then the MathJax JavaScript will render it.
1384− The *URL* should point to the `MathJax.js` load script.
1385− If a *URL* is not provided, a link to the Cloudflare CDN will
1386− be inserted.
1387−
1388−`--mathml`
1389−
1390−: Convert TeX math to [MathML] (in `epub3`, `docbook4`,
1391− `docbook5`, `jats`, `html4` and `html5`). This is the
1392− default in `odt` output. Note that currently only Firefox
1393− and Safari (and select e-book readers) natively support
1394− MathML.
1395−
1396−`--webtex`[`=`*URL*]
1397−
1398−: Convert TeX formulas to `<img>` tags that link to an external script
1399− that converts formulas to images. The formula will be URL-encoded
1400− and concatenated with the URL provided. For SVG images you can for
1401− example use `--webtex https://latex.codecogs.com/svg.latex?`.
1402− If no URL is specified, the CodeCogs URL generating PNGs
1403− will be used (`https://latex.codecogs.com/png.latex?`).
1404− Note: the `--webtex` option will affect Markdown output
1405− as well as HTML, which is useful if you're targeting a
1406− version of Markdown without native math support.
1407−
1408−`--katex`[`=`*URL*]
1409−
1410−: Use [KaTeX] to display embedded TeX math in HTML output.
1411− The *URL* is the base URL for the KaTeX library. That directory
1412− should contain a `katex.min.js` and a `katex.min.css` file.
1413− If a *URL* is not provided, a link to the KaTeX CDN will be inserted.
1414−
1415−`--gladtex`
1416−
1417−: Enclose TeX math in `<eq>` tags in HTML output. The resulting HTML
1418− can then be processed by [GladTeX] to produce SVG images of the typeset
1419− formulas and an HTML file with these images embedded.
1420−
1421− pandoc -s --gladtex input.md -o myfile.htex
1422− gladtex -d image_dir myfile.htex
1423− # produces myfile.html and images in image_dir
1424−
1425−[MathML]: https://www.w3.org/Math/
1426−[MathJax]: https://www.mathjax.org
1427−[KaTeX]: https://github.com/Khan/KaTeX
1428−[GladTeX]: https://humenda.github.io/GladTeX/
1429−
1430−## Options for wrapper scripts {.options}
1431−
1432−`--dump-args`
1433−
1434−: Print information about command-line arguments to *stdout*, then exit.
1435− This option is intended primarily for use in wrapper scripts.
1436− The first line of output contains the name of the output file specified
1437− with the `-o` option, or `-` (for *stdout*) if no output file was
1438− specified. The remaining lines contain the command-line arguments,
1439− one per line, in the order they appear. These do not include regular
1440− pandoc options and their arguments, but do include any options appearing
1441− after a `--` separator at the end of the line.
1442−
1443−`--ignore-args`
1444−
1445−: Ignore command-line arguments (for use in wrapper scripts).
1446− Regular pandoc options are not ignored. Thus, for example,
1447−
1448− pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1449−
1450− is equivalent to
1451−
1452− pandoc -o foo.html -s
1453−
1454−# Exit codes
1455−
1456−If pandoc completes successfully, it will return exit code 0.
1457−Nonzero exit codes have the following meanings:
1458−
1459− Code Error
1460−----- ------------------------------------
1461− 3 PandocFailOnWarningError
1462− 4 PandocAppError
1463− 5 PandocTemplateError
1464− 6 PandocOptionError
1465− 21 PandocUnknownReaderError
1466− 22 PandocUnknownWriterError
1467− 23 PandocUnsupportedExtensionError
1468− 24 PandocCiteprocError
1469− 31 PandocEpubSubdirectoryError
1470− 43 PandocPDFError
1471− 44 PandocXMLError
1472− 47 PandocPDFProgramNotFoundError
1473− 61 PandocHttpError
1474− 62 PandocShouldNeverHappenError
1475− 63 PandocSomeError
1476− 64 PandocParseError
1477− 65 PandocParsecError
1478− 66 PandocMakePDFError
1479− 67 PandocSyntaxMapError
1480− 83 PandocFilterError
1481− 91 PandocMacroLoop
1482− 92 PandocUTF8DecodingError
1483− 93 PandocIpynbDecodingError
1484− 94 PandocUnsupportedCharsetError
1485− 97 PandocCouldNotFindDataFileError
1486− 99 PandocResourceNotFound
1487−----- ------------------------------------
1488−
1489−# Default files
1490−
1491−The `--defaults` option may be used to specify a package
1492−of options. Here is a sample defaults file demonstrating all of
1493−the fields that may be used:
1494−
1495−``` yaml
1496−from: markdown+emoji
1497−# reader: may be used instead of from:
1498−to: html5
1499−# writer: may be used instead of to:
1500−
1501−# leave blank for output to stdout:
1502−output-file:
1503−# leave blank for input from stdin, use [] for no input:
1504−input-files:
1505−- preface.md
1506−- content.md
1507−# or you may use input-file: with a single value
1508−
1509−# Include options from the specified defaults files.
1510−# The files will be searched for first in the working directory
1511−# and then in the defaults subdirectory of the user data directory.
1512−# The files are included in the same order in which they appear in
1513−# the list. Options specified in this defaults file always have
1514−# priority over the included ones.
1515−defaults:
1516−- defsA
1517−- defsB
1518−
1519−template: letter
1520−standalone: true
1521−self-contained: false
1522−
1523−# note that structured variables may be specified:
1524−variables:
1525− documentclass: book
1526− classoption:
1527− - twosides
1528− - draft
1529−
1530−# metadata values specified here are parsed as literal
1531−# string text, not markdown:
1532−metadata:
1533− author:
1534− - Sam Smith
1535− - Julie Liu
1536−metadata-files:
1537−- boilerplate.yaml
1538−# or you may use metadata-file: with a single value
1539−
1540−# Note that these take files, not their contents:
1541−include-before-body: []
1542−include-after-body: []
1543−include-in-header: []
1544−resource-path: ["."]
1545−
1546−# turn on built-in citation processing. Note that if you need
1547−# control over when the citeproc processing is done relative
1548−# to other filters, you should instead use `citeproc` in the
1549−# list of `filters` (see below).
1550−citeproc: true
1551−csl: ieee
1552−bibliography:
1553−- foobar.bib
1554−- barbaz.json
1555−citation-abbreviations: abbrevs.json
1556−
1557−# Filters will be assumed to be Lua filters if they have
1558−# the .lua extension, and json filters otherwise. But
1559−# the filter type can also be specified explicitly, as shown.
1560−# Filters are run in the order specified.
1561−# To include the built-in citeproc filter, use either `citeproc`
1562−# or `{type: citeproc}`.
1563−filters:
1564−- wordcount.lua
1565−- type: json
1566− path: foo.lua
1567−
1568−file-scope: false
1569−
1570−data-dir:
1571−
1572−# ERROR, WARNING, or INFO
1573−verbosity: INFO
1574−log-file: log.json
1575−
1576−# citeproc, natbib, or biblatex. This only affects LaTeX
1577−# output. If you want to use citeproc to format citations,
1578−# you should also set 'citeproc: true' (see above).
1579−cite-method: citeproc
1580−
1581−# part, chapter, section, or default:
1582−top-level-division: chapter
1583−abbreviations:
1584−
1585−pdf-engine: pdflatex
1586−pdf-engine-opts:
1587−- "-shell-escape"
1588−# you may also use pdf-engine-opt: with a single option
1589−# pdf-engine-opt: "-shell-escape"
1590−
1591−# auto, preserve, or none
1592−wrap: auto
1593−columns: 78
1594−dpi: 72
1595−
1596−extract-media: mediadir
1597−
1598−table-of-contents: true
1599−toc-depth: 2
1600−number-sections: false
1601−# a list of offsets at each heading level
1602−number-offset: [0,0,0,0,0,0]
1603−# toc: may also be used instead of table-of-contents:
1604−shift-heading-level-by: 1
1605−section-divs: true
1606−identifier-prefix: foo
1607−title-prefix: ""
1608−strip-empty-paragraphs: true
1609−# lf, crlf, or native
1610−eol: lf
1611−strip-comments: false
1612−indented-code-classes: []
1613−ascii: true
1614−default-image-extension: ".jpg"
1615−
1616−# either a style name of a style definition file:
1617−highlight-style: pygments
1618−syntax-definitions:
1619−- c.xml
1620−# or you may use syntax-definition: with a single value
1621−listings: false
1622−
1623−reference-doc: myref.docx
1624−
1625−# method is plain, webtex, gladtex, mathml, mathjax, katex
1626−# you may specify a url with webtex, mathjax, katex
1627−html-math-method:
1628− method: mathjax
1629− url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
1630−# none, references, or javascript
1631−email-obfuscation: javascript
1632−
1633−tab-stop: 8
1634−preserve-tabs: true
1635−
1636−incremental: false
1637−slide-level: 2
1638−
1639−epub-subdirectory: EPUB
1640−epub-metadata: meta.xml
1641−epub-fonts:
1642−- foobar.otf
1643−epub-chapter-level: 1
1644−epub-cover-image: cover.jpg
1645−
1646−reference-links: true
1647−# block, section, or document
1648−reference-location: block
1649−markdown-headings: setext
1650−
1651−# accept, reject, or all
1652−track-changes: accept
1653−
1654−html-q-tags: false
1655−css:
1656−- site.css
1657−
1658−# none, all, or best
1659−ipynb-output: best
1660−
1661−# A list of two-element lists
1662−request-headers:
1663−- ["User-Agent", "Mozilla/5.0"]
1664−
1665−fail-if-warnings: false
1666−dump-args: false
1667−ignore-args: false
1668−trace: false
1669−```
1670−
1671−Fields that are omitted will just have their regular
1672−default values. So a defaults file can be as simple as
1673−one line:
1674−
1675−``` yaml
1676−verbosity: INFO
1677−```
1678−
1679−In fields that expect a file path (or list of file paths), the
1680−following syntax may be used to interpolate environment variables:
1681−
1682−``` yaml
1683−csl: ${HOME}/mycsldir/special.csl
1684−```
1685−
1686−`${USERDATA}` may also be used; this will always resolve to the
1687−user data directory that is current when the defaults file is
1688−parsed, regardless of the setting of the environment
1689−variable `USERDATA`.
1690−
1691−`${.}` will resolve to the directory containing the default
1692−file itself. This allows you to refer to resources contained
1693−in that directory:
1694−
1695−``` yaml
1696−epub-cover-image: ${.}/cover.jpg
1697−epub-metadata: ${.}/meta.xml
1698−resource-path:
1699−- . # the working directory from which pandoc is run
1700−- ${.}/images # the images subdirectory of the directory
1701− # containing this defaults file
1702−```
1703−
1704−This environment variable interpolation syntax *only* works in
1705−fields that expect file paths.
1706−
1707−Default files can be placed in the `defaults` subdirectory of
1708−the user data directory and used from any directory. For
1709−example, one could create a file specifying defaults for writing
1710−letters, save it as `letter.yaml` in the `defaults` subdirectory
1711−of the user data directory, and then invoke these defaults
1712−from any directory using `pandoc --defaults letter`
1713−or `pandoc -dletter`.
1714−
1715−When multiple defaults are used, their contents will be combined.
1716−
1717−Note that, where command-line arguments may be repeated
1718−(`--metadata-file`, `--css`, `--include-in-header`,
1719−`--include-before-body`, `--include-after-body`, `--variable`,
1720−`--metadata`, `--syntax-definition`), the values specified on
1721−the command line will combine with values specified in the
1722−defaults file, rather than replacing them.
1723−
1724−# Templates
1725−
1726−When the `-s/--standalone` option is used, pandoc uses a template to
1727−add header and footer material that is needed for a self-standing
1728−document. To see the default template that is used, just type
1729−
1730− pandoc -D *FORMAT*
1731−
1732−where *FORMAT* is the name of the output format. A custom template
1733−can be specified using the `--template` option. You can also override
1734−the system default templates for a given output format *FORMAT*
1735−by putting a file `templates/default.*FORMAT*` in the user data
1736−directory (see `--data-dir`, above). *Exceptions:*
1737−
1738−- For `odt` output, customize the `default.opendocument`
1739− template.
1740−- For `pdf` output, customize the `default.latex` template
1741− (or the `default.context` template, if you use `-t context`,
1742− or the `default.ms` template, if you use `-t ms`, or the
1743− `default.html` template, if you use `-t html`).
1744−- `docx` and `pptx` have no template (however, you can use
1745− `--reference-doc` to customize the output).
1746−
1747−Templates contain *variables*, which allow for the inclusion of
1748−arbitrary information at any point in the file. They may be set at the
1749−command line using the `-V/--variable` option. If a variable is not set,
1750−pandoc will look for the key in the document's metadata, which can be set
1751−using either [YAML metadata blocks][Extension: `yaml_metadata_block`]
1752−or with the `-M/--metadata` option. In addition, some variables
1753−are given default values by pandoc. See [Variables] below for
1754−a list of variables used in pandoc's default templates.
1755−
1756−If you use custom templates, you may need to revise them as pandoc
1757−changes. We recommend tracking the changes in the default templates,
1758−and modifying your custom templates accordingly. An easy way to do this
1759−is to fork the [pandoc-templates] repository and merge in
1760−changes after each pandoc release.
1761−
1762− [pandoc-templates]: https://github.com/jgm/pandoc-templates
1763−
1764−## Template syntax
1765−
1766−### Comments
1767−
1768−Anything between the sequence `$--` and the end of the
1769−line will be treated as a comment and omitted from the output.
1770−
1771−### Delimiters
1772−
1773−To mark variables and control structures in the template,
1774−either `$`...`$` or `${`...`}` may be used as delimiters.
1775−The styles may also be mixed in the same template, but the
1776−opening and closing delimiter must match in each case. The
1777−opening delimiter may be followed by one or more spaces
1778−or tabs, which will be ignored. The closing delimiter may
1779−be followed by one or more spaces or tabs, which will be
1780−ignored.
1781−
1782−To include a literal `$` in the document, use `$$`.
1783−
1784−### Interpolated variables
1785−
1786−A slot for an interpolated variable is a variable name surrounded
1787−by matched delimiters. Variable names must begin with a letter
1788−and can contain letters, numbers, `_`, `-`, and `.`. The
1789−keywords `it`, `if`, `else`, `endif`, `for`, `sep`, and `endfor` may
1790−not be used as variable names. Examples:
1791−
1792−```
1793−$foo$
1794−$foo.bar.baz$
1795−$foo_bar.baz-bim$
1796−$ foo $
1797−${foo}
1798−${foo.bar.baz}
1799−${foo_bar.baz-bim}
1800−${ foo }
1801−```
1802−
1803−Variable names with periods are used to get at structured
1804−variable values. So, for example, `employee.salary` will return the
1805−value of the `salary` field of the object that is the value of
1806−the `employee` field.
1807−
1808−- If the value of the variable is simple value, it will be
1809− rendered verbatim. (Note that no escaping is done;
1810− the assumption is that the calling program will escape
1811− the strings appropriately for the output format.)
1812−- If the value is a list, the values will be concatenated.
1813−- If the value is a map, the string `true` will be rendered.
1814−- Every other value will be rendered as the empty string.
1815−
1816−### Conditionals
1817−
1818−A conditional begins with `if(variable)` (enclosed in
1819−matched delimiters) and ends with `endif` (enclosed in matched
1820−delimiters). It may optionally contain an `else` (enclosed in
1821−matched delimiters). The `if` section is used if
1822−`variable` has a non-empty value, otherwise the `else`
1823−section is used (if present). Examples:
1824−
1825−```
1826−$if(foo)$bar$endif$
1827−
1828−$if(foo)$
1829− $foo$
1830−$endif$
1831−
1832−$if(foo)$
1833−part one
1834−$else$
1835−part two
1836−$endif$
1837−
1838−${if(foo)}bar${endif}
1839−
1840−${if(foo)}
1841− ${foo}
1842−${endif}
1843−
1844−${if(foo)}
1845−${ foo.bar }
1846−${else}
1847−no foo!
1848−${endif}
1849−```
1850−
1851−The keyword `elseif` may be used to simplify complex nested
1852−conditionals:
1853−
1854−```
1855−$if(foo)$
1856−XXX
1857−$elseif(bar)$
1858−YYY
1859−$else$
1860−ZZZ
1861−$endif$
1862−```
1863−
1864−### For loops
1865−
1866−A for loop begins with `for(variable)` (enclosed in
1867−matched delimiters) and ends with `endfor` (enclosed in matched
1868−delimiters.
1869−
1870−- If `variable` is an array, the material inside the loop will
1871− be evaluated repeatedly, with `variable` being set to each
1872− value of the array in turn, and concatenated.
1873−- If `variable` is a map, the material inside will be set to
1874− the map.
1875−- If the value of the associated variable is not an array or
1876− a map, a single iteration will be performed on its value.
1877−
1878−Examples:
1879−
1880−```
1881−$for(foo)$$foo$$sep$, $endfor$
1882−
1883−$for(foo)$
1884− - $foo.last$, $foo.first$
1885−$endfor$
1886−
1887−${ for(foo.bar) }
1888− - ${ foo.bar.last }, ${ foo.bar.first }
1889−${ endfor }
1890−
1891−$for(mymap)$
1892−$it.name$: $it.office$
1893−$endfor$
1894−```
1895−
1896−You may optionally specify a separator between consecutive
1897−values using `sep` (enclosed in matched delimiters). The
1898−material between `sep` and the `endfor` is the separator.
1899−
1900−```
1901−${ for(foo) }${ foo }${ sep }, ${ endfor }
1902−```
1903−
1904−Instead of using `variable` inside the loop, the special
1905−anaphoric keyword `it` may be used.
1906−
1907−```
1908−${ for(foo.bar) }
1909− - ${ it.last }, ${ it.first }
1910−${ endfor }
1911−```
1912−
1913−### Partials
1914−
1915−Partials (subtemplates stored in different files) may be
1916−included by using the name of the partial, followed
1917−by `()`, for example:
1918−
1919−```
1920−${ styles() }
1921−```
1922−
1923−Partials will be sought in the directory containing
1924−the main template. The file name will be assumed to
1925−have the same extension as the main template if it
1926−lacks an extension. When calling the partial, the
1927−full name including file extension can also be used:
1928−
1929−```
1930−${ styles.html() }
1931−```
1932−
1933−(If a partial is not found in the directory of the
1934−template and the template path is given as a relative
1935−path, it will also be sought in the `templates`
1936−subdirectory of the user data directory.)
1937−
1938−Partials may optionally be applied to variables using
1939−a colon:
1940−
1941−```
1942−${ date:fancy() }
1943−
1944−${ articles:bibentry() }
1945−```
1946−
1947−If `articles` is an array, this will iterate over its
1948−values, applying the partial `bibentry()` to each one. So the
1949−second example above is equivalent to
1950−
1951−```
1952−${ for(articles) }
1953−${ it:bibentry() }
1954−${ endfor }
1955−```
1956−
1957−Note that the anaphoric keyword `it` must be used when
1958−iterating over partials. In the above examples,
1959−the `bibentry` partial should contain `it.title`
1960−(and so on) instead of `articles.title`.
1961−
1962−Final newlines are omitted from included partials.
1963−
1964−Partials may include other partials.
1965−
1966−A separator between values of an array may be specified
1967−in square brackets, immediately after the variable name
1968−or partial:
1969−
1970−```
1971−${months[, ]}$
1972−
1973−${articles:bibentry()[; ]$
1974−```
1975−
1976−The separator in this case is literal and (unlike with `sep`
1977−in an explicit `for` loop) cannot contain interpolated
1978−variables or other template directives.
1979−
1980−### Nesting
1981−
1982−To ensure that content is "nested," that is, subsequent lines
1983−indented, use the `^` directive:
1984−
1985−```
1986−$item.number$ $^$$item.description$ ($item.price$)
1987−```
1988−
1989−In this example, if `item.description` has multiple lines,
1990−they will all be indented to line up with the first line:
1991−
1992−```
1993−00123 A fine bottle of 18-year old
1994− Oban whiskey. ($148)
1995−```
1996−
1997−To nest multiple lines to the same level, align them
1998−with the `^` directive in the template. For example:
1999−
2000−```
2001−$item.number$ $^$$item.description$ ($item.price$)
2002− (Available til $item.sellby$.)
2003−```
2004−
2005−will produce
2006−
2007−```
2008−00123 A fine bottle of 18-year old
2009− Oban whiskey. ($148)
2010− (Available til March 30, 2020.)
2011−```
2012−
2013−If a variable occurs by itself on a line, preceded by whitespace
2014−and not followed by further text or directives on the same line,
2015−and the variable's value contains multiple lines, it will be
2016−nested automatically.
2017−
2018−### Breakable spaces
2019−
2020−Normally, spaces in the template itself (as opposed to values of
2021−the interpolated variables) are not breakable, but they can be
2022−made breakable in part of the template by using the `~` keyword
2023−(ended with another `~`).
2024−
2025−```
2026−$~$This long line may break if the document is rendered
2027−with a short line length.$~$
2028−```
2029−
2030−### Pipes
2031−
2032−A pipe transforms the value of a variable or partial. Pipes are
2033−specified using a slash (`/`) between the variable name (or partial)
2034−and the pipe name. Example:
2035−
2036−```
2037−$for(name)$
2038−$name/uppercase$
2039−$endfor$
2040−
2041−$for(metadata/pairs)$
2042−- $it.key$: $it.value$
2043−$endfor$
2044−
2045−$employee:name()/uppercase$
2046−```
2047−
2048−Pipes may be chained:
2049−
2050−```
2051−$for(employees/pairs)$
2052−$it.key/alpha/uppercase$. $it.name$
2053−$endfor$
2054−```
2055−
2056−Some pipes take parameters:
2057−
2058−```
2059−|----------------------|------------|
2060−$for(employee)$
2061−$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
2062−$endfor$
2063−|----------------------|------------|
2064−```
2065−
2066−Currently the following pipes are predefined:
2067−
2068−- `pairs`: Converts a map or array to an array of maps,
2069− each with `key` and `value` fields. If the original
2070− value was an array, the `key` will be the array index,
2071− starting with 1.
2072−
2073−- `uppercase`: Converts text to uppercase.
2074−
2075−- `lowercase`: Converts text to lowercase.
2076−
2077−- `length`: Returns the length of the value: number
2078− of characters for a textual value, number of elements
2079− for a map or array.
2080−
2081−- `reverse`: Reverses a textual value or array,
2082− and has no effect on other values.
2083−
2084−- `first`: Returns the first value of an array, if
2085− applied to a non-empty array; otherwise returns
2086− the original value.
2087−
2088−- `last`: Returns the last value of an array, if
2089− applied to a non-empty array; otherwise returns
2090− the original value.
2091−
2092−- `rest`: Returns all but the first value of an array, if
2093− applied to a non-empty array; otherwise returns
2094− the original value.
2095−
2096−- `allbutlast`: Returns all but the last value of an array, if
2097− applied to a non-empty array; otherwise returns
2098− the original value.
2099−
2100−- `chomp`: Removes trailing newlines (and breakable space).
2101−
2102−- `nowrap`: Disables line wrapping on breakable spaces.
2103−
2104−- `alpha`: Converts textual values that can be
2105− read as an integer into lowercase alphabetic
2106− characters `a..z` (mod 26). This can be used to get lettered
2107− enumeration from array indices. To get uppercase
2108− letters, chain with `uppercase`.
2109−
2110−- `roman`: Converts textual values that can be
2111− read as an integer into lowercase roman numerials.
2112− This can be used to get lettered enumeration from array indices.
2113− To get uppercase roman, chain with `uppercase`.
2114−
2115−- `left n "leftborder" "rightborder"`: Renders a textual value
2116− in a block of width `n`, aligned to the left, with an optional
2117− left and right border. Has no effect on other values. This
2118− can be used to align material in tables. Widths are positive
2119− integers indicating the number of characters. Borders
2120− are strings inside double quotes; literal `"` and `\` characters
2121− must be backslash-escaped.
2122−
2123−- `right n "leftborder" "rightborder"`: Renders a textual value
2124− in a block of width `n`, aligned to the right, and has no
2125− effect on other values.
2126−
2127−- `center n "leftborder" "rightborder"`: Renders a textual
2128− value in a block of width `n`, aligned to the center, and has
2129− no effect on other values.
2130−
2131−
2132−## Variables
2133−
2134−### Metadata variables
2135−
2136−`title`, `author`, `date`
2137−: allow identification of basic aspects of the document. Included
2138− in PDF metadata through LaTeX and ConTeXt. These can be set
2139− through a [pandoc title block][Extension: `pandoc_title_block`],
2140− which allows for multiple authors, or through a
2141− [YAML metadata block][Extension: `yaml_metadata_block`]:
2142−
2143− ---
2144− author:
2145− - Aristotle
2146− - Peter Abelard
2147− ...
2148−
2149− Note that if you just want to set PDF or HTML metadata, without
2150− including a title block in the document itself, you can
2151− set the `title-meta`, `author-meta`, and `date-meta`
2152− variables. (By default these are set automatically, based
2153− on `title`, `author`, and `date`.) The page title in HTML
2154− is set by `pagetitle`, which is equal to `title` by default.
2155−
2156−`subtitle`
2157−: document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx
2158− documents
2159−
2160−`abstract`
2161−: document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx
2162− documents
2163−
2164−`keywords`
2165−: list of keywords to be included in HTML, PDF, ODT, pptx, docx
2166− and AsciiDoc metadata; repeat as for `author`, above
2167−
2168−`subject`
2169−: document subject, included in ODT, PDF, docx and pptx metadata
2170−
2171−`description`
2172−: document description, included in ODT, docx and pptx metadata. Some
2173− applications show this as `Comments` metadata.
2174−
2175−`category`
2176−: document category, included in docx and pptx metadata
2177−
2178−Additionally,
2179−any root-level string metadata, not included in ODT, docx
2180−or pptx metadata is added as a *custom property*.
2181−The following [YAML] metadata block for instance:
2182−
2183− ---
2184− title: 'This is the title'
2185− subtitle: "This is the subtitle"
2186− author:
2187− - Author One
2188− - Author Two
2189− description: |
2190− This is a long
2191− description.
2192−
2193− It consists of two paragraphs
2194− ...
2195−
2196−will include `title`, `author` and `description` as standard document
2197−properties and `subtitle` as a custom property when converting to docx,
2198−ODT or pptx.
2199−
2200−### Language variables
2201−
2202−`lang`
2203−: identifies the main language of the document using IETF language
2204− tags (following the [BCP 47] standard), such as `en` or `en-GB`.
2205− The [Language subtag lookup] tool can look up or verify these tags.
2206− This affects most formats, and controls hyphenation in PDF output
2207− when using LaTeX (through [`babel`] and [`polyglossia`]) or ConTeXt.
2208−
2209− Use native pandoc [Divs and Spans] with the `lang` attribute to
2210− switch the language:
2211−
2212− ---
2213− lang: en-GB
2214− ...
2215−
2216− Text in the main document language (British English).
2217−
2218− ::: {lang=fr-CA}
2219− > Cette citation est écrite en français canadien.
2220− :::
2221−
2222− More text in English. ['Zitat auf Deutsch.']{lang=de}
2223−
2224−`dir`
2225−: the base script direction, either `rtl` (right-to-left)
2226− or `ltr` (left-to-right).
2227−
2228− For bidirectional documents, native pandoc `span`s and
2229− `div`s with the `dir` attribute (value `rtl` or `ltr`) can
2230− be used to override the base direction in some output
2231− formats. This may not always be necessary if the final
2232− renderer (e.g. the browser, when generating HTML) supports
2233− the [Unicode Bidirectional Algorithm].
2234−
2235− When using LaTeX for bidirectional documents, only the
2236− `xelatex` engine is fully supported (use
2237− `--pdf-engine=xelatex`).
2238−
2239−[BCP 47]: https://tools.ietf.org/html/bcp47
2240−[Unicode Bidirectional Algorithm]: https://www.w3.org/International/articles/inline-bidi-markup/uba-basics
2241−[Language subtag lookup]: https://r12a.github.io/app-subtags/
2242−
2243−### Variables for HTML
2244−
2245−`document-css`
2246−: Enables inclusion of most of the [CSS] in the `styles.html`
2247− [partial](#partials) (have a look with
2248− `pandoc --print-default-data-file=templates/styles.html`).
2249− Unless you use [`--css`](#option--css), this variable
2250− is set to `true` by default. You can disable it with
2251− e.g. `pandoc -M document-css=false`.
2252−
2253−`mainfont`
2254−: sets the CSS `font-family` property on the `html` element.
2255−
2256−`fontsize`
2257−: sets the base CSS `font-size`, which you'd usually set
2258− to e.g. `20px`, but it also accepts `pt`
2259− (12pt = 16px in most browsers).
2260−
2261−`fontcolor`
2262−: sets the CSS `color` property on the `html` element.
2263−
2264−`linkcolor`
2265−: sets the CSS `color` property on all links.
2266−
2267−`monofont`
2268−: sets the CSS `font-family` property on `code` elements.
2269−
2270−`monobackgroundcolor`
2271−: sets the CSS `background-color` property on `code` elements
2272− and adds extra padding.
2273−
2274−`linestretch`
2275−: sets the CSS `line-height` property on the `html` element,
2276− which is preferred to be unitless.
2277−
2278−`backgroundcolor`
2279−: sets the CSS `background-color` property on the `html` element.
2280−
2281−`margin-left`, `margin-right`, `margin-top`, `margin-bottom`
2282−: sets the corresponding CSS `padding` properties on the `body` element.
2283−
2284−To override or extend some [CSS] for just one document, include for example:
2285−
2286− ---
2287− header-includes: |
2288− <style>
2289− blockquote {
2290− font-style: italic;
2291− }
2292− tr.even {
2293− background-color: #f0f0f0;
2294− }
2295− td, th {
2296− padding: 0.5em 2em 0.5em 0.5em;
2297− }
2298− tbody {
2299− border-bottom: none;
2300− }
2301− </style>
2302− ---
2303−
2304−[CSS]: https://developer.mozilla.org/en-US/docs/Learn/CSS
2305−
2306−### Variables for HTML math
2307−
2308−`classoption`
2309−: when using [KaTeX](#option--katex), you can render display
2310−math equations flush left using [YAML metadata](#layout) or with
2311−`-M classoption=fleqn`.
2312−
2313−### Variables for HTML slides
2314−
2315−These affect HTML output when [producing slide shows with pandoc].
2316−
2317−`institute`
2318−: author affiliations: can be a list when there are multiple authors
2319−
2320−`revealjs-url`
2321−: base URL for reveal.js documents (defaults to
2322− `https://unpkg.com/reveal.js@^4/`)
2323−
2324−`s5-url`
2325−: base URL for S5 documents (defaults to `s5/default`)
2326−
2327−`slidy-url`
2328−: base URL for Slidy documents (defaults to
2329− `https://www.w3.org/Talks/Tools/Slidy2`)
2330−
2331−`slideous-url`
2332−: base URL for Slideous documents (defaults to `slideous`)
2333−
2334−`title-slide-attributes`
2335−: additional attributes for the title slide of reveal.js slide shows.
2336− See [background in reveal.js and beamer] for an example.
2337−
2338−All [reveal.js configuration options] are available as variables.
2339−To turn off boolean flags that default to true in reveal.js, use `0`.
2340−
2341−[reveal.js configuration options]: https://revealjs.com/config/
2342−
2343−### Variables for Beamer slides
2344−
2345−These variables change the appearance of PDF slides using [`beamer`].
2346−
2347−`aspectratio`
2348−: slide aspect ratio (`43` for 4:3 [default], `169` for 16:9,
2349− `1610` for 16:10, `149` for 14:9, `141` for 1.41:1, `54` for 5:4,
2350− `32` for 3:2)
2351−
2352−`beamerarticle`
2353−: produce an article from Beamer slides
2354−
2355−`beameroption`
2356−: add extra beamer option with `\setbeameroption{}`
2357−
2358−`institute`
2359−: author affiliations: can be a list when there are multiple authors
2360−
2361−`logo`
2362−: logo image for slides
2363−
2364−`navigation`
2365−: controls navigation symbols (default is `empty` for no navigation
2366− symbols; other valid values are `frame`, `vertical`, and `horizontal`)
2367−
2368−`section-titles`
2369−: enables "title pages" for new sections (default is true)
2370−
2371−`theme`, `colortheme`, `fonttheme`, `innertheme`, `outertheme`
2372−: beamer themes
2373−
2374−`themeoptions`
2375−: options for LaTeX beamer themes (a list).
2376−
2377−`titlegraphic`
2378−: image for title slide
2379−
2380−### Variables for PowerPoint
2381−
2382−These variables control the visual aspects of a slide show that
2383−are not easily controlled via templates.
2384−
2385−`monofont`
2386−: font to use for code.
2387−
2388−### Variables for LaTeX
2389−
2390−Pandoc uses these variables when [creating a PDF] with a LaTeX engine.
2391−
2392−#### Layout
2393−
2394−`block-headings`
2395−: make `\paragraph` and `\subparagraph` (fourth- and
2396− fifth-level headings, or fifth- and sixth-level with book
2397− classes) free-standing rather than run-in; requires further
2398− formatting to distinguish from `\subsubsection` (third- or
2399− fourth-level headings). Instead of using this option,
2400− [KOMA-Script] can adjust headings more extensively:
2401−
2402− ---
2403− documentclass: scrartcl
2404− header-includes: |
2405− \RedeclareSectionCommand[
2406− beforeskip=-10pt plus -2pt minus -1pt,
2407− afterskip=1sp plus -1sp minus 1sp,
2408− font=\normalfont\itshape]{paragraph}
2409− \RedeclareSectionCommand[
2410− beforeskip=-10pt plus -2pt minus -1pt,
2411− afterskip=1sp plus -1sp minus 1sp,
2412− font=\normalfont\scshape,
2413− indent=0pt]{subparagraph}
2414− ...
2415−
2416−`classoption`
2417−: option for document class, e.g. `oneside`; repeat for multiple options:
2418−
2419− ---
2420− classoption:
2421− - twocolumn
2422− - landscape
2423− ...
2424−
2425−`documentclass`
2426−: document class: usually one of the standard classes,
2427− [`article`], [`book`], and [`report`]; the [KOMA-Script]
2428− equivalents, `scrartcl`, `scrbook`, and `scrreprt`, which
2429− default to smaller margins; or [`memoir`]
2430−
2431−`geometry`
2432−: option for [`geometry`] package, e.g. `margin=1in`;
2433− repeat for multiple options:
2434−
2435− ---
2436− geometry:
2437− - top=30mm
2438− - left=20mm
2439− - heightrounded
2440− ...
2441−
2442−`hyperrefoptions`
2443−: option for [`hyperref`] package, e.g. `linktoc=all`;
2444− repeat for multiple options:
2445−
2446− ---
2447− hyperrefoptions:
2448− - linktoc=all
2449− - pdfwindowui
2450− - pdfpagemode=FullScreen
2451− ...
2452−
2453−`indent`
2454−: if true, pandoc will use document class settings for
2455− indentation (the default LaTeX template otherwise removes
2456− indentation and adds space between paragraphs)
2457−
2458−`linestretch`
2459−: adjusts line spacing using the [`setspace`]
2460− package, e.g. `1.25`, `1.5`
2461−
2462−`margin-left`, `margin-right`, `margin-top`, `margin-bottom`
2463−: sets margins if `geometry` is not used (otherwise `geometry`
2464− overrides these)
2465−
2466−`pagestyle`
2467−: control `\pagestyle{}`: the default article class
2468− supports `plain` (default), `empty` (no running heads or page numbers),
2469− and `headings` (section titles in running heads)
2470−
2471−`papersize`
2472−: paper size, e.g. `letter`, `a4`
2473−
2474−`secnumdepth`
2475−: numbering depth for sections (with `--number-sections` option
2476− or `numbersections` variable)
2477−
2478−#### Fonts
2479−
2480−`fontenc`
2481−: allows font encoding to be specified through `fontenc` package (with
2482− `pdflatex`); default is `T1` (see [LaTeX font encodings guide])
2483−
2484−`fontfamily`
2485−: font package for use with `pdflatex`:
2486− [TeX Live] includes many options, documented in the [LaTeX Font Catalogue].
2487− The default is [Latin Modern][`lm`].
2488−
2489−`fontfamilyoptions`
2490−: options for package used as `fontfamily`; repeat for multiple options.
2491− For example, to use the Libertine font with proportional lowercase
2492− (old-style) figures through the [`libertinus`] package:
2493−
2494− ---
2495− fontfamily: libertinus
2496− fontfamilyoptions:
2497− - osf
2498− - p
2499− ...
2500−
2501−`fontsize`
2502−: font size for body text. The standard classes allow 10pt, 11pt, and
2503− 12pt. To use another size, set `documentclass` to one of
2504− the [KOMA-Script] classes, such as `scrartcl` or `scrbook`.
2505−
2506−`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`
2507−: font families for use with `xelatex` or
2508− `lualatex`: take the name of any system font, using the
2509− [`fontspec`] package. `CJKmainfont` uses the [`xecjk`] package.
2510−
2511−`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions`
2512−: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`,
2513− `CJKmainfont` in `xelatex` and `lualatex`. Allow for any
2514− choices available through [`fontspec`]; repeat for multiple
2515− options. For example, to use the [TeX Gyre] version of
2516− Palatino with lowercase figures:
2517−
2518− ---
2519− mainfont: TeX Gyre Pagella
2520− mainfontoptions:
2521− - Numbers=Lowercase
2522− - Numbers=Proportional
2523− ...
2524−
2525−`microtypeoptions`
2526−: options to pass to the microtype package
2527−
2528−#### Links
2529−
2530−`colorlinks`
2531−: add color to link text; automatically enabled if any of
2532− `linkcolor`, `filecolor`, `citecolor`, `urlcolor`, or `toccolor` are set
2533−
2534−`linkcolor`, `filecolor`, `citecolor`, `urlcolor`, `toccolor`
2535−: color for internal links, external links, citation links, linked
2536− URLs, and links in table of contents, respectively: uses options
2537− allowed by [`xcolor`], including the `dvipsnames`, `svgnames`, and
2538− `x11names` lists
2539−
2540−`links-as-notes`
2541−: causes links to be printed as footnotes
2542−
2543−#### Front matter
2544−
2545−`lof`, `lot`
2546−: include list of figures, list of tables
2547−
2548−`thanks`
2549−: contents of acknowledgments footnote after document title
2550−
2551−`toc`
2552−: include table of contents (can also be set using
2553− `--toc/--table-of-contents`)
2554−
2555−`toc-depth`
2556−: level of section to include in table of contents
2557−
2558−#### BibLaTeX Bibliographies
2559−
2560−These variables function when using BibLaTeX for [citation rendering].
2561−
2562−`biblatexoptions`
2563−: list of options for biblatex
2564−
2565−`biblio-style`
2566−: bibliography style, when used with `--natbib` and `--biblatex`.
2567−
2568−`biblio-title`
2569−: bibliography title, when used with `--natbib` and `--biblatex`.
2570−
2571−`bibliography`
2572−: bibliography to use for resolving references
2573−
2574−`natbiboptions`
2575−: list of options for natbib
2576−
2577−[KOMA-Script]: https://ctan.org/pkg/koma-script
2578−[LaTeX Font Catalogue]: https://tug.org/FontCatalogue/
2579−[LaTeX font encodings guide]: https://ctan.org/pkg/encguide
2580−[TeX Gyre]: http://www.gust.org.pl/projects/e-foundry/tex-gyre
2581−[`article`]: https://ctan.org/pkg/article
2582−[`book`]: https://ctan.org/pkg/book
2583−[`libertinus`]: https://ctan.org/pkg/libertinus
2584−[`memoir`]: https://ctan.org/pkg/memoir
2585−[`report`]: https://ctan.org/pkg/report
2586−
2587−### Variables for ConTeXt
2588−
2589−Pandoc uses these variables when [creating a PDF] with ConTeXt.
2590−
2591−`fontsize`
2592−: font size for body text (e.g. `10pt`, `12pt`)
2593−
2594−`headertext`, `footertext`
2595−: text to be placed in running header or footer (see [ConTeXt Headers and
2596− Footers]); repeat up to four times for different placement
2597−
2598−`indenting`
2599−: controls indentation of paragraphs, e.g. `yes,small,next` (see
2600− [ConTeXt Indentation]); repeat for multiple options
2601−
2602−`interlinespace`
2603−: adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]);
2604− repeat for multiple options
2605−
2606−`layout`
2607−: options for page margins and text arrangement (see [ConTeXt Layout]);
2608− repeat for multiple options
2609−
2610−`linkcolor`, `contrastcolor`
2611−: color for links outside and inside a page, e.g. `red`, `blue` (see
2612− [ConTeXt Color])
2613−
2614−`linkstyle`
2615−: typeface style for links, e.g. `normal`, `bold`, `slanted`, `boldslanted`,
2616− `type`, `cap`, `small`
2617−
2618−`lof`, `lot`
2619−: include list of figures, list of tables
2620−
2621−`mainfont`, `sansfont`, `monofont`, `mathfont`
2622−: font families: take the name of any system font (see
2623− [ConTeXt Font Switching])
2624−
2625−`margin-left`, `margin-right`, `margin-top`, `margin-bottom`
2626−: sets margins, if `layout` is not used (otherwise `layout`
2627− overrides these)
2628−
2629−`pagenumbering`
2630−: page number style and location (using [`setuppagenumbering`]);
2631− repeat for multiple options
2632−
2633−`papersize`
2634−: paper size, e.g. `letter`, `A4`, `landscape` (see [ConTeXt Paper Setup]);
2635− repeat for multiple options
2636−
2637−`pdfa`
2638−: adds to the preamble the setup necessary to generate PDF/A
2639− of the type specified, e.g. `1a:2005`, `2a`. If no type is
2640− specified (i.e. the value is set to True, by e.g.
2641− `--metadata=pdfa` or `pdfa: true` in a YAML metadata block),
2642− `1b:2005` will be used as default, for reasons of backwards
2643− compatibility. Using `--variable=pdfa` without specified value
2644− is not supported. To successfully generate PDF/A the required
2645− ICC color profiles have to be available and the content and all
2646− included files (such as images) have to be standard conforming.
2647− The ICC profiles and output intent may be specified using the
2648− variables `pdfaiccprofile` and `pdfaintent`. See also [ConTeXt
2649− PDFA] for more details.
2650−
2651−`pdfaiccprofile`
2652−: when used in conjunction with `pdfa`, specifies the ICC profile to use
2653− in the PDF, e.g. `default.cmyk`. If left unspecified, `sRGB.icc` is
2654− used as default. May be repeated to include multiple profiles. Note that
2655− the profiles have to be available on the system. They can be obtained
2656− from [ConTeXt ICC Profiles].
2657−
2658−`pdfaintent`
2659−: when used in conjunction with `pdfa`, specifies the output intent for
2660− the colors, e.g. `ISO coated v2 300\letterpercent\space (ECI)`
2661− If left unspecified, `sRGB IEC61966-2.1` is used as default.
2662−
2663−`toc`
2664−: include table of contents (can also be set using
2665− `--toc/--table-of-contents`)
2666−
2667−`whitespace`
2668−: spacing between paragraphs, e.g. `none`, `small` (using
2669− [`setupwhitespace`])
2670−
2671−`includesource`
2672−: include all source documents as file attachments in the PDF file
2673−
2674−[ConTeXt Paper Setup]: https://wiki.contextgarden.net/PaperSetup
2675−[ConTeXt Layout]: https://wiki.contextgarden.net/Layout
2676−[ConTeXt Font Switching]: https://wiki.contextgarden.net/Font_Switching
2677−[ConTeXt Color]: https://wiki.contextgarden.net/Color
2678−[ConTeXt Headers and Footers]: https://wiki.contextgarden.net/Headers_and_Footers
2679−[ConTeXt Indentation]: https://wiki.contextgarden.net/Indentation
2680−[ConTeXt ICC Profiles]: https://wiki.contextgarden.net/PDFX#ICC_profiles
2681−[ConTeXt PDFA]: https://wiki.contextgarden.net/PDF/A
2682−[`setupwhitespace`]: https://wiki.contextgarden.net/Command/setupwhitespace
2683−[`setupinterlinespace`]: https://wiki.contextgarden.net/Command/setupinterlinespace
2684−[`setuppagenumbering`]: https://wiki.contextgarden.net/Command/setuppagenumbering
2685−
2686−### Variables for `wkhtmltopdf`
2687−
2688−Pandoc uses these variables when [creating a PDF] with [`wkhtmltopdf`].
2689−The `--css` option also affects the output.
2690−
2691−`footer-html`, `header-html`
2692−: add information to the header and footer
2693−
2694−`margin-left`, `margin-right`, `margin-top`, `margin-bottom`
2695−: set the page margins
2696−
2697−`papersize`
2698−: sets the PDF paper size
2699−
2700−### Variables for man pages
2701−
2702−`adjusting`
2703−: adjusts text to left (`l`), right (`r`), center (`c`),
2704− or both (`b`) margins
2705−
2706−`footer`
2707−: footer in man pages
2708−
2709−`header`
2710−: header in man pages
2711−
2712−`hyphenate`
2713−: if `true` (the default), hyphenation will be used
2714−
2715−`section`
2716−: section number in man pages
2717−
2718−### Variables for ms
2719−
2720−`fontfamily`
2721−: font family (e.g. `T` or `P`)
2722−
2723−`indent`
2724−: paragraph indent (e.g. `2m`)
2725−
2726−`lineheight`
2727−: line height (e.g. `12p`)
2728−
2729−`pointsize`
2730−: point size (e.g. `10p`)
2731−
2732−### Variables set automatically
2733−
2734−Pandoc sets these variables automatically in response to [options] or
2735−document contents; users can also modify them. These vary depending
2736−on the output format, and include the following:
2737−
2738−`body`
2739−: body of document
2740−
2741−`date-meta`
2742−: the `date` variable converted to ISO 8601 YYYY-MM-DD,
2743− included in all HTML based formats (dzslides, epub,
2744− html, html4, html5, revealjs, s5, slideous, slidy).
2745− The recognized formats for `date` are: `mm/dd/yyyy`,
2746− `mm/dd/yy`, `yyyy-mm-dd` (ISO 8601), `dd MM yyyy`
2747− (e.g. either `02 Apr 2018` or `02 April 2018`),
2748− `MM dd, yyyy` (e.g. `Apr. 02, 2018` or `April 02, 2018),
2749− `yyyy[mm[dd]]]` (e.g. `20180402, `201804` or `2018`).
2750−
2751−`header-includes`
2752−: contents specified by `-H/--include-in-header` (may have multiple
2753− values)
2754−
2755−`include-before`
2756−: contents specified by `-B/--include-before-body` (may have
2757− multiple values)
2758−
2759−`include-after`
2760−: contents specified by `-A/--include-after-body` (may have
2761− multiple values)
2762−
2763−`meta-json`
2764−: JSON representation of all of the document's metadata. Field
2765− values are transformed to the selected output format.
2766−
2767−`numbersections`
2768−: non-null value if `-N/--number-sections` was specified
2769−
2770−`sourcefile`, `outputfile`
2771−: source and destination filenames, as given on the command line.
2772− `sourcefile` can also be a list if input comes from multiple files,
2773− or empty if input is from stdin. You can use the following snippet in
2774− your template to distinguish them:
2775−
2776− $if(sourcefile)$
2777− $for(sourcefile)$
2778− $sourcefile$
2779− $endfor$
2780− $else$
2781− (stdin)
2782− $endif$
2783−
2784− Similarly, `outputfile` can be `-` if output goes to the terminal.
2785−
2786− If you need absolute paths, use e.g. `$curdir$/$sourcefile$`.
2787−
2788−`curdir`
2789−: working directory from which pandoc is run.
2790−
2791−`toc`
2792−: non-null value if `--toc/--table-of-contents` was specified
2793−
2794−`toc-title`
2795−: title of table of contents (works only with EPUB,
2796− HTML, opendocument, odt, docx, pptx, beamer, LaTeX)
2797−
2798−[pandoc-templates]: https://github.com/jgm/pandoc-templates
2799−
2800−# Extensions
2801−
2802−The behavior of some of the readers and writers can be adjusted by
2803−enabling or disabling various extensions.
2804−
2805−An extension can be enabled by adding `+EXTENSION`
2806−to the format name and disabled by adding `-EXTENSION`. For example,
2807−`--from markdown_strict+footnotes` is strict Markdown with footnotes
2808−enabled, while `--from markdown-footnotes-pipe_tables` is pandoc's
2809−Markdown without footnotes or pipe tables.
2810−
2811−The markdown reader and writer make by far the most use of extensions.
2812−Extensions only used by them are therefore covered in the
2813−section [Pandoc's Markdown] below (See [Markdown variants] for
2814−`commonmark` and `gfm`.) In the following, extensions that also work
2815−for other formats are covered.
2816−
2817−Note that markdown extensions added to the `ipynb` format
2818−affect Markdown cells in Jupyter notebooks (as do command-line
2819−options like `--atx-headers`).
2820−
2821−## Typography
2822−
2823−#### Extension: `smart` ####
2824−
2825−Interpret straight quotes as curly quotes, `---` as em-dashes,
2826−`--` as en-dashes, and `...` as ellipses. Nonbreaking spaces are
2827−inserted after certain abbreviations, such as "Mr."
2828−
2829−This extension can be enabled/disabled for the following formats:
2830−
2831−input formats
2832−: `markdown`, `commonmark`, `latex`, `mediawiki`, `org`, `rst`, `twiki`
2833−
2834−output formats
2835−: `markdown`, `latex`, `context`, `rst`
2836−
2837−enabled by default in
2838−: `markdown`, `latex`, `context` (both input and output)
2839−
2840−Note: If you are *writing* Markdown, then the `smart` extension
2841−has the reverse effect: what would have been curly quotes comes
2842−out straight.
2843−
2844−In LaTeX, `smart` means to use the standard TeX ligatures
2845−for quotation marks (` `` ` and ` '' ` for double quotes,
2846−`` ` `` and `` ' `` for single quotes) and dashes (`--` for
2847−en-dash and `---` for em-dash). If `smart` is disabled,
2848−then in reading LaTeX pandoc will parse these characters
2849−literally. In writing LaTeX, enabling `smart` tells pandoc
2850−to use the ligatures when possible; if `smart` is disabled
2851−pandoc will use unicode quotation mark and dash characters.
2852−
2853−## Headings and sections
2854−
2855−#### Extension: `auto_identifiers` ####
2856−
2857−A heading without an explicitly specified identifier will be
2858−automatically assigned a unique identifier based on the heading text.
2859−
2860−This extension can be enabled/disabled for the following formats:
2861−
2862−input formats
2863−: `markdown`, `latex`, `rst`, `mediawiki`, `textile`
2864−
2865−output formats
2866−: `markdown`, `muse`
2867−
2868−enabled by default in
2869−: `markdown`, `muse`
2870−
2871−The default algorithm used to derive the identifier from the
2872−heading text is:
2873−
2874− - Remove all formatting, links, etc.
2875− - Remove all footnotes.
2876− - Remove all non-alphanumeric characters,
2877− except underscores, hyphens, and periods.
2878− - Replace all spaces and newlines with hyphens.
2879− - Convert all alphabetic characters to lowercase.
2880− - Remove everything up to the first letter (identifiers may
2881− not begin with a number or punctuation mark).
2882− - If nothing is left after this, use the identifier `section`.
2883−
2884−Thus, for example,
2885−
2886− Heading Identifier
2887− ------------------------------- ----------------------------
2888− `Heading identifiers in HTML` `heading-identifiers-in-html`
2889− `Maître d'hôtel` `maître-dhôtel`
2890− `*Dogs*?--in *my* house?` `dogs--in-my-house`
2891− `[HTML], [S5], or [RTF]?` `html-s5-or-rtf`
2892− `3. Applications` `applications`
2893− `33` `section`
2894−
2895−These rules should, in most cases, allow one to determine the identifier
2896−from the heading text. The exception is when several headings have the
2897−same text; in this case, the first will get an identifier as described
2898−above; the second will get the same identifier with `-1` appended; the
2899−third with `-2`; and so on.
2900−
2901−(However, a different algorithm is used if
2902−`gfm_auto_identifiers` is enabled; see below.)
2903−
2904−These identifiers are used to provide link targets in the table of
2905−contents generated by the `--toc|--table-of-contents` option. They
2906−also make it easy to provide links from one section of a document to
2907−another. A link to this section, for example, might look like this:
2908−
2909− See the section on
2910− [heading identifiers](#heading-identifiers-in-html-latex-and-context).
2911−
2912−Note, however, that this method of providing links to sections works
2913−only in HTML, LaTeX, and ConTeXt formats.
2914−
2915−If the `--section-divs` option is specified, then each section will
2916−be wrapped in a `section` (or a `div`, if `html4` was specified),
2917−and the identifier will be attached to the enclosing `<section>`
2918−(or `<div>`) tag rather than the heading itself. This allows entire
2919−sections to be manipulated using JavaScript or treated differently in
2920−CSS.
2921−
2922−#### Extension: `ascii_identifiers` ####
2923−
2924−Causes the identifiers produced by `auto_identifiers` to be pure ASCII.
2925−Accents are stripped off of accented Latin letters, and non-Latin
2926−letters are omitted.
2927−
2928−#### Extension: `gfm_auto_identifiers` ####
2929−
2930−Changes the algorithm used by `auto_identifiers` to conform to
2931−GitHub's method. Spaces are converted to dashes (`-`),
2932−uppercase characters to lowercase characters, and punctuation
2933−characters other than `-` and `_` are removed.
2934−Emojis are replaced by their names.
2935−
2936−## Math Input
2937−
2938−The extensions [`tex_math_dollars`](#extension-tex_math_dollars),
2939−[`tex_math_single_backslash`](#extension-tex_math_single_backslash), and
2940−[`tex_math_double_backslash`](#extension-tex_math_double_backslash)
2941−are described in the section about Pandoc's Markdown.
2942−
2943−However, they can also be used with HTML input. This is handy for
2944−reading web pages formatted using MathJax, for example.
2945−
2946−## Raw HTML/TeX
2947−
2948−The following extensions are described in more detail in
2949−their respective sections of [Pandoc's Markdown]:
2950−
2951−- [`raw_html`](#extension-raw_html) allows HTML elements which
2952− are not representable in pandoc's AST to be parsed as raw HTML.
2953− By default, this is disabled for HTML input.
2954−
2955−- [`raw_tex`](#extension-raw_tex) allows raw LaTeX, TeX, and ConTeXt
2956− to be included in a document. This extension can be enabled/disabled
2957− for the following formats (in addition to `markdown`):
2958−
2959− input formats
2960− : `latex`, `textile`, `html` (environments, `\ref`, and
2961− `\eqref` only), `ipynb`
2962−
2963− output formats
2964− : `textile`, `commonmark`
2965−
2966− Note: as applied to `ipynb`, `raw_html` and `raw_tex` affect not
2967− only raw TeX in markdown cells, but data with mime type
2968− `text/html` in output cells. Since the `ipynb` reader attempts
2969− to preserve the richest possible outputs when several options
2970− are given, you will get best results if you disable `raw_html`
2971− and `raw_tex` when converting to formats like `docx` which don't
2972− allow raw `html` or `tex`.
2973−
2974−- [`native_divs`](#extension-native_divs) causes HTML `div`
2975− elements to be parsed as native pandoc Div blocks.
2976− If you want them to be parsed as raw HTML, use
2977− `-f html-native_divs+raw_html`.
2978−
2979−- [`native_spans`](#extension-native_spans) causes HTML `span`
2980− elements to be parsed as native pandoc Span inlines.
2981− If you want them to be parsed as raw HTML, use
2982− `-f html-native_spans+raw_html`. If you want to drop all
2983− `div`s and `span`s when converting HTML to Markdown, you
2984− can use `pandoc -f html-native_divs-native_spans -t markdown`.
2985−
2986−## Literate Haskell support
2987−
2988−#### Extension: `literate_haskell` ####
2989−
2990−Treat the document as literate Haskell source.
2991−
2992−This extension can be enabled/disabled for the following formats:
2993−
2994−input formats
2995−: `markdown`, `rst`, `latex`
2996−
2997−output formats
2998−: `markdown`, `rst`, `latex`, `html`
2999−
3000−If you append `+lhs` (or `+literate_haskell`) to one of the formats
3001−above, pandoc will treat the document as literate Haskell source.
3002−This means that
3003−
3004− - In Markdown input, "bird track" sections will be parsed as Haskell
3005− code rather than block quotations. Text between `\begin{code}`
3006− and `\end{code}` will also be treated as Haskell code. For
3007− ATX-style headings the character '=' will be used instead of '#'.
3008−
3009− - In Markdown output, code blocks with classes `haskell` and `literate`
3010− will be rendered using bird tracks, and block quotations will be
3011− indented one space, so they will not be treated as Haskell code.
3012− In addition, headings will be rendered setext-style (with underlines)
3013− rather than ATX-style (with '#' characters). (This is because ghc
3014− treats '#' characters in column 1 as introducing line numbers.)
3015−
3016− - In restructured text input, "bird track" sections will be parsed
3017− as Haskell code.
3018−
3019− - In restructured text output, code blocks with class `haskell` will
3020− be rendered using bird tracks.
3021−
3022− - In LaTeX input, text in `code` environments will be parsed as
3023− Haskell code.
3024−
3025− - In LaTeX output, code blocks with class `haskell` will be rendered
3026− inside `code` environments.
3027−
3028− - In HTML output, code blocks with class `haskell` will be rendered
3029− with class `literatehaskell` and bird tracks.
3030−
3031−Examples:
3032−
3033− pandoc -f markdown+lhs -t html
3034−
3035−reads literate Haskell source formatted with Markdown conventions and writes
3036−ordinary HTML (without bird tracks).
3037−
3038− pandoc -f markdown+lhs -t html+lhs
3039−
3040−writes HTML with the Haskell code in bird tracks, so it can be copied
3041−and pasted as literate Haskell source.
3042−
3043−Note that GHC expects the bird tracks in the first column, so indented
3044−literate code blocks (e.g. inside an itemized environment) will not be
3045−picked up by the Haskell compiler.
3046−
3047−## Other extensions
3048−
3049−#### Extension: `empty_paragraphs` ####
3050−
3051−Allows empty paragraphs. By default empty paragraphs are
3052−omitted.
3053−
3054−This extension can be enabled/disabled for the following formats:
3055−
3056−input formats
3057−: `docx`, `html`
3058−
3059−output formats
3060−: `docx`, `odt`, `opendocument`, `html`
3061−
3062−#### Extension: `native_numbering` ####
3063−
3064−Enables native numbering of figures and tables. Enumeration
3065−starts at 1.
3066−
3067−This extension can be enabled/disabled for the following formats:
3068−
3069−output formats
3070−: `odt`, `opendocument`
3071−
3072−#### Extension: `xrefs_name` ####
3073−
3074−Links to headings, figures and tables inside the document are
3075−substituted with cross-references that will use the name or caption
3076−of the referenced item. The original link text is replaced once
3077−the generated document is refreshed. This extension can be combined
3078−with `xrefs_number` in which case numbers will appear before the
3079−name.
3080−
3081−Text in cross-references is only made consistent with the referenced
3082−item once the document has been refreshed.
3083−
3084−This extension can be enabled/disabled for the following formats:
3085−
3086−output formats
3087−: `odt`, `opendocument`
3088−
3089−#### Extension: `xrefs_number` ####
3090−
3091−Links to headings, figures and tables inside the document are
3092−substituted with cross-references that will use the number
3093−of the referenced item. The original link text is discarded.
3094−This extension can be combined with `xrefs_name` in which case
3095−the name or caption numbers will appear after the number.
3096−
3097−For the `xrefs_number` to be useful heading numbers must be enabled
3098−in the generated document, also table and figure captions must be enabled
3099−using for example the `native_numbering` extension.
3100−
3101−Numbers in cross-references are only visible in the final document once
3102−it has been refreshed.
3103−
3104−This extension can be enabled/disabled for the following formats:
3105−
3106−output formats
3107−: `odt`, `opendocument`
3108−
3109−#### Extension: `styles` #### {#ext-styles}
3110−
3111−When converting from docx, read all docx styles as divs (for
3112−paragraph styles) and spans (for character styles) regardless
3113−of whether pandoc understands the meaning of these styles.
3114−This can be used with [docx custom styles](#custom-styles).
3115−Disabled by default.
3116−
3117−input formats
3118−: `docx`
3119−
3120−#### Extension: `amuse` ####
3121−
3122−In the `muse` input format, this enables Text::Amuse
3123−extensions to Emacs Muse markup.
3124−
3125−#### Extension: `raw_markdown` ####
3126−
3127−In the `ipynb` input format, this causes Markdown cells
3128−to be included as raw Markdown blocks (allowing lossless
3129−round-tripping) rather than being parsed. Use this only
3130−when you are targeting `ipynb` or a markdown-based
3131−output format.
3132−
3133−#### Extension: `citations` {#org-citations}
3134−
3135−Some aspects of [Pandoc's Markdown citation syntax](#citations)
3136−are also accepted in `org` input.
3137−
3138−#### Extension: `element_citations` ####
3139−
3140−In the `jats` output formats, this causes reference items to
3141−be replaced with `<element-citation>` elements. These
3142−elements are not influenced by CSL styles, but all information
3143−on the item is included in tags.
3144−
3145−#### Extension: `ntb` ####
3146−
3147−In the `context` output format this enables the use of [Natural Tables
3148−(TABLE)](https://wiki.contextgarden.net/TABLE) instead of the default
3149−[Extreme Tables (xtables)](https://wiki.contextgarden.net/xtables).
3150−Natural tables allow more fine-grained global customization but come
3151−at a performance penalty compared to extreme tables.
3152−
3153−
3154−# Pandoc's Markdown
3155−
3156−Pandoc understands an extended and slightly revised version of
3157−John Gruber's [Markdown] syntax. This document explains the syntax,
3158−noting differences from standard Markdown. Except where noted, these
3159−differences can be suppressed by using the `markdown_strict` format instead
3160−of `markdown`. Extensions can be enabled or disabled to specify the
3161−behavior more granularly. They are described in the following. See also
3162−[Extensions] above, for extensions that work also on other formats.
3163−
3164−## Philosophy
3165−
3166−Markdown is designed to be easy to write, and, even more importantly,
3167−easy to read:
3168−
3169−> A Markdown-formatted document should be publishable as-is, as plain
3170−> text, without looking like it's been marked up with tags or formatting
3171−> instructions.
3172−> -- [John Gruber](https://daringfireball.net/projects/markdown/syntax#philosophy)
3173−
3174−This principle has guided pandoc's decisions in finding syntax for
3175−tables, footnotes, and other extensions.
3176−
3177−There is, however, one respect in which pandoc's aims are different
3178−from the original aims of Markdown. Whereas Markdown was originally
3179−designed with HTML generation in mind, pandoc is designed for multiple
3180−output formats. Thus, while pandoc allows the embedding of raw HTML,
3181−it discourages it, and provides other, non-HTMLish ways of representing
3182−important document elements like definition lists, tables, mathematics, and
3183−footnotes.
3184−
3185−## Paragraphs
3186−
3187−A paragraph is one or more lines of text followed by one or more blank lines.
3188−Newlines are treated as spaces, so you can reflow your paragraphs as you like.
3189−If you need a hard line break, put two or more spaces at the end of a line.
3190−
3191−#### Extension: `escaped_line_breaks` ####
3192−
3193−A backslash followed by a newline is also a hard line break.
3194−Note: in multiline and grid table cells, this is the only way
3195−to create a hard line break, since trailing spaces in the cells
3196−are ignored.
3197−
3198−## Headings
3199−
3200−There are two kinds of headings: Setext and ATX.
3201−
3202−### Setext-style headings ###
3203−
3204−A setext-style heading is a line of text "underlined" with a row of `=` signs
3205−(for a level-one heading) or `-` signs (for a level-two heading):
3206−
3207− A level-one heading
3208− ===================
3209−
3210− A level-two heading
3211− -------------------
3212−
3213−The heading text can contain inline formatting, such as emphasis (see
3214−[Inline formatting], below).
3215−
3216−
3217−### ATX-style headings ###
3218−
3219−An ATX-style heading consists of one to six `#` signs and a line of
3220−text, optionally followed by any number of `#` signs. The number of
3221−`#` signs at the beginning of the line is the heading level:
3222−
3223− ## A level-two heading
3224−
3225− ### A level-three heading ###
3226−
3227−As with setext-style headings, the heading text can contain formatting:
3228−
3229− # A level-one heading with a [link](/url) and *emphasis*
3230−
3231−#### Extension: `blank_before_header` ####
3232−
3233−Standard Markdown syntax does not require a blank line before a heading.
3234−Pandoc does require this (except, of course, at the beginning of the
3235−document). The reason for the requirement is that it is all too easy for a
3236−`#` to end up at the beginning of a line by accident (perhaps through line
3237−wrapping). Consider, for example:
3238−
3239− I like several of their flavors of ice cream:
3240− #22, for example, and #5.
3241−
3242−#### Extension: `space_in_atx_header` ####
3243−
3244−Many Markdown implementations do not require a space between the
3245−opening `#`s of an ATX heading and the heading text, so that
3246−`#5 bolt` and `#hashtag` count as headings. With this extension,
3247−pandoc does require the space.
3248−
3249−### Heading identifiers ###
3250−
3251−See also the [`auto_identifiers`
3252−extension](#extension-auto_identifiers) above.
3253−
3254−#### Extension: `header_attributes` ####
3255−
3256−Headings can be assigned attributes using this syntax at the end
3257−of the line containing the heading text:
3258−
3259− {#identifier .class .class key=value key=value}
3260−
3261−Thus, for example, the following headings will all be assigned the identifier
3262−`foo`:
3263−
3264− # My heading {#foo}
3265−
3266− ## My heading ## {#foo}
3267−
3268− My other heading {#foo}
3269− ---------------
3270−
3271−(This syntax is compatible with [PHP Markdown Extra].)
3272−
3273−Note that although this syntax allows assignment of classes and key/value
3274−attributes, writers generally don't use all of this information. Identifiers,
3275−classes, and key/value attributes are used in HTML and HTML-based formats such
3276−as EPUB and slidy. Identifiers are used for labels and link anchors in the
3277−LaTeX, ConTeXt, Textile, Jira markup, and AsciiDoc writers.
3278−
3279−Headings with the class `unnumbered` will not be numbered, even if
3280−`--number-sections` is specified. A single hyphen (`-`) in an attribute
3281−context is equivalent to `.unnumbered`, and preferable in non-English
3282−documents. So,
3283−
3284− # My heading {-}
3285−
3286−is just the same as
3287−
3288− # My heading {.unnumbered}
3289−
3290−If the `unlisted` class is present in addition to `unnumbered`,
3291−the heading will not be included in a table of contents.
3292−(Currently this feature is only implemented for certain
3293−formats: those based on LaTeX and HTML, PowerPoint, and RTF.)
3294−
3295−#### Extension: `implicit_header_references` ####
3296−
3297−Pandoc behaves as if reference links have been defined for each heading.
3298−So, to link to a heading
3299−
3300− # Heading identifiers in HTML
3301−
3302−you can simply write
3303−
3304− [Heading identifiers in HTML]
3305−
3306−or
3307−
3308− [Heading identifiers in HTML][]
3309−
3310−or
3311−
3312− [the section on heading identifiers][heading identifiers in
3313− HTML]
3314−
3315−instead of giving the identifier explicitly:
3316−
3317− [Heading identifiers in HTML](#heading-identifiers-in-html)
3318−
3319−If there are multiple headings with identical text, the corresponding
3320−reference will link to the first one only, and you will need to use explicit
3321−links to link to the others, as described above.
3322−
3323−Like regular reference links, these references are case-insensitive.
3324−
3325−Explicit link reference definitions always take priority over
3326−implicit heading references. So, in the following example, the
3327−link will point to `bar`, not to `#foo`:
3328−
3329− # Foo
3330−
3331− [foo]: bar
3332−
3333− See [foo]
3334−
3335−## Block quotations
3336−
3337−Markdown uses email conventions for quoting blocks of text.
3338−A block quotation is one or more paragraphs or other block elements
3339−(such as lists or headings), with each line preceded by a `>` character
3340−and an optional space. (The `>` need not start at the left margin, but
3341−it should not be indented more than three spaces.)
3342−
3343− > This is a block quote. This
3344− > paragraph has two lines.
3345− >
3346− > 1. This is a list inside a block quote.
3347− > 2. Second item.
3348−
3349−A "lazy" form, which requires the `>` character only on the first
3350−line of each block, is also allowed:
3351−
3352− > This is a block quote. This
3353− paragraph has two lines.
3354−
3355− > 1. This is a list inside a block quote.
3356− 2. Second item.
3357−
3358−Among the block elements that can be contained in a block quote are
3359−other block quotes. That is, block quotes can be nested:
3360−
3361− > This is a block quote.
3362− >
3363− > > A block quote within a block quote.
3364−
3365−If the `>` character is followed by an optional space, that space
3366−will be considered part of the block quote marker and not part of
3367−the indentation of the contents. Thus, to put an indented code
3368−block in a block quote, you need five spaces after the `>`:
3369−
3370− > code
3371−
3372−#### Extension: `blank_before_blockquote` ####
3373−
3374−Standard Markdown syntax does not require a blank line before a
3375−block quote. Pandoc does require this (except, of course, at
3376−the beginning of the document). The reason for the requirement
3377−is that it is all too easy for a `>` to end up at the beginning
3378−of a line by accident (perhaps through line wrapping). So,
3379−unless the `markdown_strict` format is used, the following does
3380−not produce a nested block quote in pandoc:
3381−
3382− > This is a block quote.
3383− >> Nested.
3384−
3385−
3386−## Verbatim (code) blocks
3387−
3388−### Indented code blocks ###
3389−
3390−A block of text indented four spaces (or one tab) is treated as verbatim
3391−text: that is, special characters do not trigger special formatting,
3392−and all spaces and line breaks are preserved. For example,
3393−
3394− if (a > 3) {
3395− moveShip(5 * gravity, DOWN);
3396− }
3397−
3398−The initial (four space or one tab) indentation is not considered part
3399−of the verbatim text, and is removed in the output.
3400−
3401−Note: blank lines in the verbatim text need not begin with four spaces.
3402−
3403−
3404−### Fenced code blocks ###
3405−
3406−#### Extension: `fenced_code_blocks` ####
3407−
3408−In addition to standard indented code blocks, pandoc supports
3409−*fenced* code blocks. These begin with a row of three or more
3410−tildes (`~`) and end with a row of tildes that must be at least as long as
3411−the starting row. Everything between these lines is treated as code. No
3412−indentation is necessary:
3413−
3414− ~~~~~~~
3415− if (a > 3) {
3416− moveShip(5 * gravity, DOWN);
3417− }
3418− ~~~~~~~
3419−
3420−Like regular code blocks, fenced code blocks must be separated
3421−from surrounding text by blank lines.
3422−
3423−If the code itself contains a row of tildes or backticks, just use a longer
3424−row of tildes or backticks at the start and end:
3425−
3426− ~~~~~~~~~~~~~~~~
3427− ~~~~~~~~~~
3428− code including tildes
3429− ~~~~~~~~~~
3430− ~~~~~~~~~~~~~~~~
3431−
3432−#### Extension: `backtick_code_blocks` ####
3433−
3434−Same as `fenced_code_blocks`, but uses backticks (`` ` ``) instead of tildes
3435−(`~`).
3436−
3437−#### Extension: `fenced_code_attributes` ####
3438−
3439−Optionally, you may attach attributes to fenced or backtick code block using
3440−this syntax:
3441−
3442− ~~~~ {#mycode .haskell .numberLines startFrom="100"}
3443− qsort [] = []
3444− qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
3445− qsort (filter (>= x) xs)
3446− ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3447−
3448−Here `mycode` is an identifier, `haskell` and `numberLines` are
3449−classes, and `startFrom` is an attribute with value `100`. Some
3450−output formats can use this information to do syntax
3451−highlighting. Currently, the only output formats that uses this
3452−information are HTML, LaTeX, Docx, Ms, and PowerPoint. If
3453−highlighting is supported for your output format and language,
3454−then the code block above will appear highlighted, with numbered
3455−lines. (To see which languages are supported, type `pandoc
3456−--list-highlight-languages`.) Otherwise, the code block above
3457−will appear as follows:
3458−
3459− <pre id="mycode" class="haskell numberLines" startFrom="100">
3460− <code>
3461− ...
3462− </code>
3463− </pre>
3464−
3465−The `numberLines` (or `number-lines`) class will cause the lines
3466−of the code block to be numbered, starting with `1` or the value
3467−of the `startFrom` attribute. The `lineAnchors` (or
3468−`line-anchors`) class will cause the lines to be clickable
3469−anchors in HTML output.
3470−
3471−A shortcut form can also be used for specifying the language of
3472−the code block:
3473−
3474− ```haskell
3475− qsort [] = []
3476− ```
3477−
3478−This is equivalent to:
3479−
3480− ``` {.haskell}
3481− qsort [] = []
3482− ```
3483−
3484−If the `fenced_code_attributes` extension is disabled, but
3485−input contains class attribute(s) for the code block, the first
3486−class attribute will be printed after the opening fence as a bare
3487−word.
3488−
3489−To prevent all highlighting, use the `--no-highlight` flag.
3490−To set the highlighting style, use `--highlight-style`.
3491−For more information on highlighting, see [Syntax highlighting],
3492−below.
3493−
3494−## Line blocks
3495−
3496−#### Extension: `line_blocks` ####
3497−
3498−A line block is a sequence of lines beginning with a vertical bar (`|`)
3499−followed by a space. The division into lines will be preserved in
3500−the output, as will any leading spaces; otherwise, the lines will
3501−be formatted as Markdown. This is useful for verse and addresses:
3502−
3503− | The limerick packs laughs anatomical
3504− | In space that is quite economical.
3505− | But the good ones I've seen
3506− | So seldom are clean
3507− | And the clean ones so seldom are comical
3508−
3509− | 200 Main St.
3510− | Berkeley, CA 94718
3511−
3512−The lines can be hard-wrapped if needed, but the continuation
3513−line must begin with a space.
3514−
3515− | The Right Honorable Most Venerable and Righteous Samuel L.
3516− Constable, Jr.
3517− | 200 Main St.
3518− | Berkeley, CA 94718
3519−
3520−Inline formatting (such as emphasis) is allowed in the content,
3521−but not block-level formatting (such as block quotes or lists).
3522−
3523−This syntax is borrowed from [reStructuredText].
3524−
3525−## Lists
3526−
3527−### Bullet lists ###
3528−
3529−A bullet list is a list of bulleted list items. A bulleted list
3530−item begins with a bullet (`*`, `+`, or `-`). Here is a simple
3531−example:
3532−
3533− * one
3534− * two
3535− * three
3536−
3537−This will produce a "compact" list. If you want a "loose" list, in which
3538−each item is formatted as a paragraph, put spaces between the items:
3539−
3540− * one
3541−
3542− * two
3543−
3544− * three
3545−
3546−The bullets need not be flush with the left margin; they may be
3547−indented one, two, or three spaces. The bullet must be followed
3548−by whitespace.
3549−
3550−List items look best if subsequent lines are flush with the first
3551−line (after the bullet):
3552−
3553− * here is my first
3554− list item.
3555− * and my second.
3556−
3557−But Markdown also allows a "lazy" format:
3558−
3559− * here is my first
3560− list item.
3561− * and my second.
3562−
3563−### Block content in list items ###
3564−
3565−A list item may contain multiple paragraphs and other block-level
3566−content. However, subsequent paragraphs must be preceded by a blank line
3567−and indented to line up with the first non-space content after
3568−the list marker.
3569−
3570− * First paragraph.
3571−
3572− Continued.
3573−
3574− * Second paragraph. With a code block, which must be indented
3575− eight spaces:
3576−
3577− { code }
3578−
3579−Exception: if the list marker is followed by an indented code
3580−block, which must begin 5 spaces after the list marker, then
3581−subsequent paragraphs must begin two columns after the last
3582−character of the list marker:
3583−
3584− * code
3585−
3586− continuation paragraph
3587−
3588−List items may include other lists. In this case the preceding blank
3589−line is optional. The nested list must be indented to line up with
3590−the first non-space character after the list marker of the
3591−containing list item.
3592−
3593− * fruits
3594− + apples
3595− - macintosh
3596− - red delicious
3597− + pears
3598− + peaches
3599− * vegetables
3600− + broccoli
3601− + chard
3602−
3603−As noted above, Markdown allows you to write list items "lazily," instead of
3604−indenting continuation lines. However, if there are multiple paragraphs or
3605−other blocks in a list item, the first line of each must be indented.
3606−
3607− + A lazy, lazy, list
3608− item.
3609−
3610− + Another one; this looks
3611− bad but is legal.
3612−
3613− Second paragraph of second
3614− list item.
3615−
3616−### Ordered lists ###
3617−
3618−Ordered lists work just like bulleted lists, except that the items
3619−begin with enumerators rather than bullets.
3620−
3621−In standard Markdown, enumerators are decimal numbers followed
3622−by a period and a space. The numbers themselves are ignored, so
3623−there is no difference between this list:
3624−
3625− 1. one
3626− 2. two
3627− 3. three
3628−
3629−and this one:
3630−
3631− 5. one
3632− 7. two
3633− 1. three
3634−
3635−#### Extension: `fancy_lists` ####
3636−
3637−Unlike standard Markdown, pandoc allows ordered list items to be marked
3638−with uppercase and lowercase letters and roman numerals, in addition to
3639−Arabic numerals. List markers may be enclosed in parentheses or followed by a
3640−single right-parentheses or period. They must be separated from the
3641−text that follows by at least one space, and, if the list marker is a
3642−capital letter with a period, by at least two spaces.[^2]
3643−
3644−[^2]: The point of this rule is to ensure that normal paragraphs
3645− starting with people's initials, like
3646−
3647− B. Russell was an English philosopher.
3648−
3649− do not get treated as list items.
3650−
3651− This rule will not prevent
3652−
3653− (C) 2007 Joe Smith
3654−
3655− from being interpreted as a list item. In this case, a backslash
3656− escape can be used:
3657−
3658− (C\) 2007 Joe Smith
3659−
3660−The `fancy_lists` extension also allows '`#`' to be used as an
3661−ordered list marker in place of a numeral:
3662−
3663− #. one
3664− #. two
3665−
3666−#### Extension: `startnum` ####
3667−
3668−Pandoc also pays attention to the type of list marker used, and to the
3669−starting number, and both of these are preserved where possible in the
3670−output format. Thus, the following yields a list with numbers followed
3671−by a single parenthesis, starting with 9, and a sublist with lowercase
3672−roman numerals:
3673−
3674− 9) Ninth
3675− 10) Tenth
3676− 11) Eleventh
3677− i. subone
3678− ii. subtwo
3679− iii. subthree
3680−
3681−Pandoc will start a new list each time a different type of list
3682−marker is used. So, the following will create three lists:
3683−
3684− (2) Two
3685− (5) Three
3686− 1. Four
3687− * Five
3688−
3689−If default list markers are desired, use `#.`:
3690−
3691− #. one
3692− #. two
3693− #. three
3694−
3695−#### Extension: `task_lists` ####
3696−
3697−Pandoc supports task lists, using the syntax of GitHub-Flavored Markdown.
3698−
3699− - [ ] an unchecked task list item
3700− - [x] checked item
3701−
3702−### Definition lists ###
3703−
3704−#### Extension: `definition_lists` ####
3705−
3706−Pandoc supports definition lists, using the syntax of
3707−[PHP Markdown Extra] with some extensions.[^3]
3708−
3709− Term 1
3710−
3711− : Definition 1
3712−
3713− Term 2 with *inline markup*
3714−
3715− : Definition 2
3716−
3717− { some code, part of Definition 2 }
3718−
3719− Third paragraph of definition 2.
3720−
3721−Each term must fit on one line, which may optionally be followed by
3722−a blank line, and must be followed by one or more definitions.
3723−A definition begins with a colon or tilde, which may be indented one
3724−or two spaces.
3725−
3726−A term may have multiple definitions, and each definition may
3727−consist of one or more block elements (paragraph, code block,
3728−list, etc.), each indented four spaces or one tab stop. The
3729−body of the definition (including the first line, aside from the
3730−colon or tilde) should be indented four spaces. However, as with
3731−other Markdown lists, you can "lazily" omit indentation except
3732−at the beginning of a paragraph or other block element:
3733−
3734− Term 1
3735−
3736− : Definition
3737− with lazy continuation.
3738−
3739− Second paragraph of the definition.
3740−
3741−If you leave space before the definition (as in the example above),
3742−the text of the definition will be treated as a paragraph. In some
3743−output formats, this will mean greater spacing between term/definition
3744−pairs. For a more compact definition list, omit the space before the
3745−definition:
3746−
3747− Term 1
3748− ~ Definition 1
3749−
3750− Term 2
3751− ~ Definition 2a
3752− ~ Definition 2b
3753−
3754−Note that space between items in a definition list is required.
3755−(A variant that loosens this requirement, but disallows "lazy"
3756−hard wrapping, can be activated with `compact_definition_lists`: see
3757−[Non-default extensions], below.)
3758−
3759−[^3]: I have been influenced by the suggestions of [David
3760− Wheeler](https://justatheory.com/2009/02/modest-markdown-proposal/).
3761−
3762−### Numbered example lists ###
3763−
3764−#### Extension: `example_lists` ####
3765−
3766−The special list marker `@` can be used for sequentially numbered
3767−examples. The first list item with a `@` marker will be numbered '1',
3768−the next '2', and so on, throughout the document. The numbered examples
3769−need not occur in a single list; each new list using `@` will take up
3770−where the last stopped. So, for example:
3771−
3772− (@) My first example will be numbered (1).
3773− (@) My second example will be numbered (2).
3774−
3775− Explanation of examples.
3776−
3777− (@) My third example will be numbered (3).
3778−
3779−Numbered examples can be labeled and referred to elsewhere in the
3780−document:
3781−
3782− (@good) This is a good example.
3783−
3784− As (@good) illustrates, ...
3785−
3786−The label can be any string of alphanumeric characters, underscores,
3787−or hyphens.
3788−
3789−Note: continuation paragraphs in example lists must always
3790−be indented four spaces, regardless of the length of the
3791−list marker. That is, example lists always behave as if the
3792−`four_space_rule` extension is set. This is because example
3793−labels tend to be long, and indenting content to the
3794−first non-space character after the label would be awkward.
3795−
3796−
3797−### Ending a list ###
3798−
3799−What if you want to put an indented code block after a list?
3800−
3801− - item one
3802− - item two
3803−
3804− { my code block }
3805−
3806−Trouble! Here pandoc (like other Markdown implementations) will treat
3807−`{ my code block }` as the second paragraph of item two, and not as
3808−a code block.
3809−
3810−To "cut off" the list after item two, you can insert some non-indented
3811−content, like an HTML comment, which won't produce visible output in
3812−any format:
3813−
3814− - item one
3815− - item two
3816−
3817− <!-- end of list -->
3818−
3819− { my code block }
3820−
3821−You can use the same trick if you want two consecutive lists instead
3822−of one big list:
3823−
3824− 1. one
3825− 2. two
3826− 3. three
3827−
3828− <!-- -->
3829−
3830− 1. uno
3831− 2. dos
3832− 3. tres
3833−
3834−## Horizontal rules
3835−
3836−A line containing a row of three or more `*`, `-`, or `_` characters
3837−(optionally separated by spaces) produces a horizontal rule:
3838−
3839− * * * *
3840−
3841− ---------------
3842−
3843−
3844−## Tables
3845−
3846−Four kinds of tables may be used. The first three kinds presuppose the use of
3847−a fixed-width font, such as Courier. The fourth kind can be used with
3848−proportionally spaced fonts, as it does not require lining up columns.
3849−
3850−#### Extension: `table_captions` ####
3851−
3852−A caption may optionally be provided with all 4 kinds of tables (as
3853−illustrated in the examples below). A caption is a paragraph beginning
3854−with the string `Table:` (or just `:`), which will be stripped off.
3855−It may appear either before or after the table.
3856−
3857−#### Extension: `simple_tables` ####
3858−
3859−Simple tables look like this:
3860−
3861− Right Left Center Default
3862− ------- ------ ---------- -------
3863− 12 12 12 12
3864− 123 123 123 123
3865− 1 1 1 1
3866−
3867− Table: Demonstration of simple table syntax.
3868−
3869−The header and table rows must each fit on one line. Column
3870−alignments are determined by the position of the header text relative
3871−to the dashed line below it:[^4]
3872−
3873− - If the dashed line is flush with the header text on the right side
3874− but extends beyond it on the left, the column is right-aligned.
3875− - If the dashed line is flush with the header text on the left side
3876− but extends beyond it on the right, the column is left-aligned.
3877− - If the dashed line extends beyond the header text on both sides,
3878− the column is centered.
3879− - If the dashed line is flush with the header text on both sides,
3880− the default alignment is used (in most cases, this will be left).
3881−
3882−[^4]: This scheme is due to Michel Fortin, who proposed it on the
3883− [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html).
3884−
3885−The table must end with a blank line, or a line of dashes followed by
3886−a blank line.
3887−
3888−The column header row may be omitted, provided a dashed line is used
3889−to end the table. For example:
3890−
3891− ------- ------ ---------- -------
3892− 12 12 12 12
3893− 123 123 123 123
3894− 1 1 1 1
3895− ------- ------ ---------- -------
3896−
3897−When the header row is omitted, column alignments are determined on the basis
3898−of the first line of the table body. So, in the tables above, the columns
3899−would be right, left, center, and right aligned, respectively.
3900−
3901−#### Extension: `multiline_tables` ####
3902−
3903−Multiline tables allow header and table rows to span multiple lines
3904−of text (but cells that span multiple columns or rows of the table are
3905−not supported). Here is an example:
3906−
3907− -------------------------------------------------------------
3908− Centered Default Right Left
3909− Header Aligned Aligned Aligned
3910− ----------- ------- --------------- -------------------------
3911− First row 12.0 Example of a row that
3912− spans multiple lines.
3913−
3914− Second row 5.0 Here's another one. Note
3915− the blank line between
3916− rows.
3917− -------------------------------------------------------------
3918−
3919− Table: Here's the caption. It, too, may span
3920− multiple lines.
3921−
3922−These work like simple tables, but with the following differences:
3923−
3924− - They must begin with a row of dashes, before the header text
3925− (unless the header row is omitted).
3926− - They must end with a row of dashes, then a blank line.
3927− - The rows must be separated by blank lines.
3928−
3929−In multiline tables, the table parser pays attention to the widths of
3930−the columns, and the writers try to reproduce these relative widths in
3931−the output. So, if you find that one of the columns is too narrow in the
3932−output, try widening it in the Markdown source.
3933−
3934−The header may be omitted in multiline tables as well as simple tables:
3935−
3936− ----------- ------- --------------- -------------------------
3937− First row 12.0 Example of a row that
3938− spans multiple lines.
3939−
3940− Second row 5.0 Here's another one. Note
3941− the blank line between
3942− rows.
3943− ----------- ------- --------------- -------------------------
3944−
3945− : Here's a multiline table without a header.
3946−
3947−It is possible for a multiline table to have just one row, but the row
3948−should be followed by a blank line (and then the row of dashes that ends
3949−the table), or the table may be interpreted as a simple table.
3950−
3951−#### Extension: `grid_tables` ####
3952−
3953−Grid tables look like this:
3954−
3955− : Sample grid table.
3956−
3957− +---------------+---------------+--------------------+
3958− | Fruit | Price | Advantages |
3959− +===============+===============+====================+
3960− | Bananas | $1.34 | - built-in wrapper |
3961− | | | - bright color |
3962− +---------------+---------------+--------------------+
3963− | Oranges | $2.10 | - cures scurvy |
3964− | | | - tasty |
3965− +---------------+---------------+--------------------+
3966−
3967−The row of `=`s separates the header from the table body, and can be
3968−omitted for a headerless table. The cells of grid tables may contain
3969−arbitrary block elements (multiple paragraphs, code blocks, lists,
3970−etc.). Cells that span multiple columns or rows are not
3971−supported. Grid tables can be created easily using Emacs' table-mode
3972−(`M-x table-insert`).
3973−
3974−Alignments can be specified as with pipe tables, by putting
3975−colons at the boundaries of the separator line after the
3976−header:
3977−
3978− +---------------+---------------+--------------------+
3979− | Right | Left | Centered |
3980− +==============:+:==============+:==================:+
3981− | Bananas | $1.34 | built-in wrapper |
3982− +---------------+---------------+--------------------+
3983−
3984−For headerless tables, the colons go on the top line instead:
3985−
3986− +--------------:+:--------------+:------------------:+
3987− | Right | Left | Centered |
3988− +---------------+---------------+--------------------+
3989−
3990−##### Grid Table Limitations #####
3991−
3992−Pandoc does not support grid tables with row spans or column spans.
3993−This means that neither variable numbers of columns across rows nor
3994−variable numbers of rows across columns are supported by Pandoc.
3995−All grid tables must have the same number of columns in each row,
3996−and the same number of rows in each column. For example, the
3997−Docutils [sample grid tables] will not render as expected with
3998−Pandoc.
3999−
4000−[sample grid tables]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables
4001−
4002−
4003−#### Extension: `pipe_tables` ####
4004−
4005−Pipe tables look like this:
4006−
4007− | Right | Left | Default | Center |
4008− |------:|:-----|---------|:------:|
4009− | 12 | 12 | 12 | 12 |
4010− | 123 | 123 | 123 | 123 |
4011− | 1 | 1 | 1 | 1 |
4012−
4013− : Demonstration of pipe table syntax.
4014−
4015−The syntax is identical to [PHP Markdown Extra tables]. The beginning and
4016−ending pipe characters are optional, but pipes are required between all
4017−columns. The colons indicate column alignment as shown. The header
4018−cannot be omitted. To simulate a headerless table, include a header
4019−with blank cells.
4020−
4021−Since the pipes indicate column boundaries, columns need not be vertically
4022−aligned, as they are in the above example. So, this is a perfectly
4023−legal (though ugly) pipe table:
4024−
4025− fruit| price
4026− -----|-----:
4027− apple|2.05
4028− pear|1.37
4029− orange|3.09
4030−
4031−The cells of pipe tables cannot contain block elements like paragraphs
4032−and lists, and cannot span multiple lines. If a pipe table contains a
4033−row whose Markdown content is wider than the column width (see
4034−`--columns`), then the table will take up the full text width and
4035−the cell contents will wrap, with the relative cell widths determined
4036−by the number of dashes in the line separating the table header from
4037−the table body. (For example `---|-` would make the first column 3/4
4038−and the second column 1/4 of the full text width.)
4039−On the other hand, if no lines are wider than column width, then
4040−cell contents will not be wrapped, and the cells will be sized
4041−to their contents.
4042−
4043−Note: pandoc also recognizes pipe tables of the following
4044−form, as can be produced by Emacs' orgtbl-mode:
4045−
4046− | One | Two |
4047− |-----+-------|
4048− | my | table |
4049− | is | nice |
4050−
4051−The difference is that `+` is used instead of `|`. Other orgtbl features
4052−are not supported. In particular, to get non-default column alignment,
4053−you'll need to add colons as above.
4054−
4055−[PHP Markdown Extra tables]: https://michelf.ca/projects/php-markdown/extra/#table
4056−
4057−## Metadata blocks
4058−
4059−#### Extension: `pandoc_title_block` ####
4060−
4061−If the file begins with a title block
4062−
4063− % title
4064− % author(s) (separated by semicolons)
4065− % date
4066−
4067−it will be parsed as bibliographic information, not regular text. (It
4068−will be used, for example, in the title of standalone LaTeX or HTML
4069−output.) The block may contain just a title, a title and an author,
4070−or all three elements. If you want to include an author but no
4071−title, or a title and a date but no author, you need a blank line:
4072−
4073−```
4074−%
4075−% Author
4076−```
4077−
4078−```
4079−% My title
4080−%
4081−% June 15, 2006
4082−```
4083−
4084−The title may occupy multiple lines, but continuation lines must
4085−begin with leading space, thus:
4086−
4087−```
4088−% My title
4089− on multiple lines
4090−```
4091−
4092−If a document has multiple authors, the authors may be put on
4093−separate lines with leading space, or separated by semicolons, or
4094−both. So, all of the following are equivalent:
4095−
4096−```
4097−% Author One
4098− Author Two
4099−```
4100−
4101−```
4102−% Author One; Author Two
4103−```
4104−
4105−```
4106−% Author One;
4107− Author Two
4108−```
4109−
4110−The date must fit on one line.
4111−
4112−All three metadata fields may contain standard inline formatting
4113−(italics, links, footnotes, etc.).
4114−
4115−Title blocks will always be parsed, but they will affect the output only
4116−when the `--standalone` (`-s`) option is chosen. In HTML output, titles
4117−will appear twice: once in the document head -- this is the title that
4118−will appear at the top of the window in a browser -- and once at the
4119−beginning of the document body. The title in the document head can have
4120−an optional prefix attached (`--title-prefix` or `-T` option). The title
4121−in the body appears as an H1 element with class "title", so it can be
4122−suppressed or reformatted with CSS. If a title prefix is specified with
4123−`-T` and no title block appears in the document, the title prefix will
4124−be used by itself as the HTML title.
4125−
4126−The man page writer extracts a title, man page section number, and
4127−other header and footer information from the title line. The title
4128−is assumed to be the first word on the title line, which may optionally
4129−end with a (single-digit) section number in parentheses. (There should
4130−be no space between the title and the parentheses.) Anything after
4131−this is assumed to be additional footer and header text. A single pipe
4132−character (`|`) should be used to separate the footer text from the header
4133−text. Thus,
4134−
4135− % PANDOC(1)
4136−
4137−will yield a man page with the title `PANDOC` and section 1.
4138−
4139− % PANDOC(1) Pandoc User Manuals
4140−
4141−will also have "Pandoc User Manuals" in the footer.
4142−
4143− % PANDOC(1) Pandoc User Manuals | Version 4.0
4144−
4145−will also have "Version 4.0" in the header.
4146−
4147−#### Extension: `yaml_metadata_block` ####
4148−
4149−A [YAML] metadata block is a valid YAML object, delimited by a line of three
4150−hyphens (`---`) at the top and a line of three hyphens (`---`) or three dots
4151−(`...`) at the bottom. A YAML metadata block may occur anywhere in the
4152−document, but if it is not at the beginning, it must be preceded by a blank
4153−line. (Note that, because of the way pandoc concatenates input files when
4154−several are provided, you may also keep the metadata in a separate YAML file
4155−and pass it to pandoc as an argument, along with your Markdown files:
4156−
4157− pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
4158−
4159−Just be sure that the YAML file begins with `---` and ends with `---` or
4160−`...`.) Alternatively, you can use the `--metadata-file` option. Using
4161−that approach however, you cannot reference content (like footnotes)
4162−from the main markdown input document.
4163−
4164−Metadata will be taken from the fields of the YAML object and added to any
4165−existing document metadata. Metadata can contain lists and objects (nested
4166−arbitrarily), but all string scalars will be interpreted as Markdown. Fields
4167−with names ending in an underscore will be ignored by pandoc. (They may be
4168−given a role by external processors.) Field names must not be
4169−interpretable as YAML numbers or boolean values (so, for
4170−example, `yes`, `True`, and `15` cannot be used as field names).
4171−
4172−A document may contain multiple metadata blocks. If two
4173−metadata blocks attempt to set the same field, the value from
4174−the second block will be taken.
4175−
4176−When pandoc is used with `-t markdown` to create a Markdown document,
4177−a YAML metadata block will be produced only if the `-s/--standalone`
4178−option is used. All of the metadata will appear in a single block
4179−at the beginning of the document.
4180−
4181−Note that [YAML] escaping rules must be followed. Thus, for example,
4182−if a title contains a colon, it must be quoted, and if it contains a
4183−backslash escape, then it must be ensured that it is not treated as a
4184−[YAML escape sequence]. The pipe character (`|`) can be used to begin
4185−an indented block that will be interpreted literally, without need for
4186−escaping. This form is necessary when the field contains blank lines
4187−or block-level formatting:
4188−
4189− ---
4190− title: 'This is the title: it contains a colon'
4191− author:
4192− - Author One
4193− - Author Two
4194− keywords: [nothing, nothingness]
4195− abstract: |
4196− This is the abstract.
4197−
4198− It consists of two paragraphs.
4199− ...
4200−
4201−The literal block after the `|` must be indented relative to the
4202−line containing the `|`. If it is not, the YAML will be invalid
4203−and pandoc will not interpret it as metadata. For an overview
4204−of the complex rules governing YAML, see the [Wikipedia entry on
4205−YAML syntax].
4206−
4207−Template variables will be set automatically from the metadata. Thus, for
4208−example, in writing HTML, the variable `abstract` will be set to the HTML
4209−equivalent of the Markdown in the `abstract` field:
4210−
4211− <p>This is the abstract.</p>
4212− <p>It consists of two paragraphs.</p>
4213−
4214−Variables can contain arbitrary YAML structures, but the template must match
4215−this structure. The `author` variable in the default templates expects a
4216−simple list or string, but can be changed to support more complicated
4217−structures. The following combination, for example, would add an affiliation
4218−to the author if one is given:
4219−
4220− ---
4221− title: The document title
4222− author:
4223− - name: Author One
4224− affiliation: University of Somewhere
4225− - name: Author Two
4226− affiliation: University of Nowhere
4227− ...
4228−
4229−To use the structured authors in the example above, you would need a custom
4230−template:
4231−
4232− $for(author)$
4233− $if(author.name)$
4234− $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
4235− $else$
4236− $author$
4237− $endif$
4238− $endfor$
4239−
4240−Raw content to include in the document's header may be specified
4241−using `header-includes`; however, it is important to mark up
4242−this content as raw code for a particular output format, using
4243−the [`raw_attribute` extension](#extension-raw_attribute)), or it
4244−will be interpreted as markdown. For example:
4245−
4246− header-includes:
4247− - |
4248− ```{=latex}
4249− \let\oldsection\section
4250− \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
4251− ```
4252−
4253−Note: the `yaml_metadata_block` extension works with
4254−`commonmark` as well as `markdown` (and it is enabled by default
4255−in `gfm` and `commonmark_x`). However, in these formats the
4256−following restrictions apply:
4257−
4258−- The YAML metadata block must occur at the beginning of the
4259− document (and there can be only one). If multiple files are
4260− given as arguments to pandoc, only the first can be a YAML
4261− metadata block.
4262−
4263−- The leaf nodes of the YAML structure are parsed in isolation from
4264− each other and from the rest of the document. So, for
4265− example, you can't use a reference link in these contexts
4266− if the link definition is somewhere else in the document.
4267−
4268−[YAML escape sequence]: https://yaml.org/spec/1.2/spec.html#id2776092
4269−[Wikipedia entry on YAML syntax]: https://en.m.wikipedia.org/wiki/YAML#Syntax
4270−
4271−## Backslash escapes
4272−
4273−#### Extension: `all_symbols_escapable` ####
4274−
4275−Except inside a code block or inline code, any punctuation or space
4276−character preceded by a backslash will be treated literally, even if it
4277−would normally indicate formatting. Thus, for example, if one writes
4278−
4279− *\*hello\**
4280−
4281−one will get
4282−
4283− <em>*hello*</em>
4284−
4285−instead of
4286−
4287− <strong>hello</strong>
4288−
4289−This rule is easier to remember than standard Markdown's rule,
4290−which allows only the following characters to be backslash-escaped:
4291−
4292− \`*_{}[]()>#+-.!
4293−
4294−(However, if the `markdown_strict` format is used, the standard Markdown rule
4295−will be used.)
4296−
4297−A backslash-escaped space is parsed as a nonbreaking space. In TeX output,
4298−it will appear as `~`. In HTML and XML output, it will appear as a
4299−literal unicode nonbreaking space character (note that it will thus
4300−actually look "invisible" in the generated HTML source; you can still
4301−use the `--ascii` command-line option to make it appear as an explicit
4302−entity).
4303−
4304−A backslash-escaped newline (i.e. a backslash occurring at the end of
4305−a line) is parsed as a hard line break. It will appear in TeX output as
4306−`\\` and in HTML as `<br />`. This is a nice alternative to
4307−Markdown's "invisible" way of indicating hard line breaks using
4308−two trailing spaces on a line.
4309−
4310−Backslash escapes do not work in verbatim contexts.
4311−
4312−## Inline formatting
4313−
4314−### Emphasis ###
4315−
4316−To *emphasize* some text, surround it with `*`s or `_`, like this:
4317−
4318− This text is _emphasized with underscores_, and this
4319− is *emphasized with asterisks*.
4320−
4321−Double `*` or `_` produces **strong emphasis**:
4322−
4323− This is **strong emphasis** and __with underscores__.
4324−
4325−A `*` or `_` character surrounded by spaces, or backslash-escaped,
4326−will not trigger emphasis:
4327−
4328− This is * not emphasized *, and \*neither is this\*.
4329−
4330−#### Extension: `intraword_underscores` ####
4331−
4332−Because `_` is sometimes used inside words and identifiers,
4333−pandoc does not interpret a `_` surrounded by alphanumeric
4334−characters as an emphasis marker. If you want to emphasize
4335−just part of a word, use `*`:
4336−
4337− feas*ible*, not feas*able*.
4338−
4339−
4340−### Strikeout ###
4341−
4342−#### Extension: `strikeout` ####
4343−
4344−To strikeout a section of text with a horizontal line, begin and end it
4345−with `~~`. Thus, for example,
4346−
4347− This ~~is deleted text.~~
4348−
4349−
4350−### Superscripts and subscripts ###
4351−
4352−#### Extension: `superscript`, `subscript` ####
4353−
4354−Superscripts may be written by surrounding the superscripted text by `^`
4355−characters; subscripts may be written by surrounding the subscripted
4356−text by `~` characters. Thus, for example,
4357−
4358− H~2~O is a liquid. 2^10^ is 1024.
4359−
4360−The text between `^...^` or `~...~` may not contain spaces or
4361−newlines. If the superscripted or subscripted text contains
4362−spaces, these spaces must be escaped with backslashes. (This is
4363−to prevent accidental superscripting and subscripting through
4364−the ordinary use of `~` and `^`, and also bad interactions with
4365−footnotes.) Thus, if you want the letter P with 'a cat' in
4366−subscripts, use `P~a\ cat~`, not `P~a cat~`.
4367−
4368−### Verbatim ###
4369−
4370−To make a short span of text verbatim, put it inside backticks:
4371−
4372− What is the difference between `>>=` and `>>`?
4373−
4374−If the verbatim text includes a backtick, use double backticks:
4375−
4376− Here is a literal backtick `` ` ``.
4377−
4378−(The spaces after the opening backticks and before the closing
4379−backticks will be ignored.)
4380−
4381−The general rule is that a verbatim span starts with a string
4382−of consecutive backticks (optionally followed by a space)
4383−and ends with a string of the same number of backticks (optionally
4384−preceded by a space).
4385−
4386−Note that backslash-escapes (and other Markdown constructs) do not
4387−work in verbatim contexts:
4388−
4389− This is a backslash followed by an asterisk: `\*`.
4390−
4391−#### Extension: `inline_code_attributes` ####
4392−
4393−Attributes can be attached to verbatim text, just as with
4394−[fenced code blocks]:
4395−
4396− `<$>`{.haskell}
4397−
4398−### Small caps ###
4399−
4400−To write small caps, use the `smallcaps` class:
4401−
4402− [Small caps]{.smallcaps}
4403−
4404−Or, without the `bracketed_spans` extension:
4405−
4406− <span class="smallcaps">Small caps</span>
4407−
4408−For compatibility with other Markdown flavors, CSS is also supported:
4409−
4410− <span style="font-variant:small-caps;">Small caps</span>
4411−
4412−This will work in all output formats that support small caps.
4413−
4414−
4415−## Math
4416−
4417−#### Extension: `tex_math_dollars` ####
4418−
4419−Anything between two `$` characters will be treated as TeX math. The
4420−opening `$` must have a non-space character immediately to its right,
4421−while the closing `$` must have a non-space character immediately to its
4422−left, and must not be followed immediately by a digit. Thus,
4423−`$20,000 and $30,000` won't parse as math. If for some reason
4424−you need to enclose text in literal `$` characters, backslash-escape
4425−them and they won't be treated as math delimiters.
4426−
4427−For display math, use `$$` delimiters. (In this case, the delimiters
4428−may be separated from the formula by whitespace. However, there can be
4429−no blank lines betwen the opening and closing `$$` delimiters.)
4430−
4431−TeX math will be printed in all output formats. How it is rendered
4432−depends on the output format:
4433−
4434−LaTeX
4435− ~ It will appear verbatim surrounded by `\(...\)` (for inline
4436− math) or `\[...\]` (for display math).
4437−
4438−Markdown, Emacs Org mode, ConTeXt, ZimWiki
4439− ~ It will appear verbatim surrounded by `$...$` (for inline
4440− math) or `$$...$$` (for display math).
4441−
4442−XWiki
4443− ~ It will appear verbatim surrounded by `{{formula}}..{{/formula}}`.
4444−
4445−reStructuredText
4446− ~ It will be rendered using an [interpreted text role `:math:`].
4447−
4448−AsciiDoc
4449− ~ For AsciiDoc output format (`-t asciidoc`) it will appear verbatim
4450− surrounded by `latexmath:[$...$]` (for inline math) or
4451− `[latexmath]++++\[...\]+++` (for display math).
4452− For AsciiDoctor output format (`-t asciidoctor`) the LaTex delimiters
4453− (`$..$` and `\[..\]`) are omitted.
4454−
4455−Texinfo
4456− ~ It will be rendered inside a `@math` command.
4457−
4458−roff man, Jira markup
4459− ~ It will be rendered verbatim without `$`'s.
4460−
4461−MediaWiki, DokuWiki
4462− ~ It will be rendered inside `<math>` tags.
4463−
4464−Textile
4465− ~ It will be rendered inside `<span class="math">` tags.
4466−
4467−RTF, OpenDocument
4468− ~ It will be rendered, if possible, using Unicode characters,
4469− and will otherwise appear verbatim.
4470−
4471−ODT
4472− ~ It will be rendered, if possible, using MathML.
4473−
4474−DocBook
4475− ~ If the `--mathml` flag is used, it will be rendered using MathML
4476− in an `inlineequation` or `informalequation` tag. Otherwise it
4477− will be rendered, if possible, using Unicode characters.
4478−
4479−Docx
4480− ~ It will be rendered using OMML math markup.
4481−
4482−FictionBook2
4483− ~ If the `--webtex` option is used, formulas are rendered as images
4484− using CodeCogs or other compatible web service, downloaded
4485− and embedded in the e-book. Otherwise, they will appear verbatim.
4486−
4487−HTML, Slidy, DZSlides, S5, EPUB
4488− ~ The way math is rendered in HTML will depend on the
4489− command-line options selected. Therefore see [Math rendering in HTML]
4490− above.
4491−
4492−[interpreted text role `:math:`]: https://docutils.sourceforge.io/docs/ref/rst/roles.html#math
4493−
4494−## Raw HTML
4495−
4496−#### Extension: `raw_html` ####
4497−
4498−Markdown allows you to insert raw HTML (or DocBook) anywhere in a document
4499−(except verbatim contexts, where `<`, `>`, and `&` are interpreted
4500−literally). (Technically this is not an extension, since standard
4501−Markdown allows it, but it has been made an extension so that it can
4502−be disabled if desired.)
4503−
4504−The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
4505−DZSlides, EPUB, Markdown, CommonMark, Emacs Org mode, and Textile
4506−output, and suppressed in other formats.
4507−
4508−For a more explicit way of including raw HTML in a Markdown
4509−document, see the [`raw_attribute` extension][Extension: `raw_attribute`].
4510−
4511−In the CommonMark format, if `raw_html` is enabled, superscripts,
4512−subscripts, strikeouts and small capitals will be represented as HTML.
4513−Otherwise, plain-text fallbacks will be used. Note that even if
4514−`raw_html` is disabled, tables will be rendered with HTML syntax if
4515−they cannot use pipe syntax.
4516−
4517−#### Extension: `markdown_in_html_blocks` ####
4518−
4519−Standard Markdown allows you to include HTML "blocks": blocks
4520−of HTML between balanced tags that are separated from the surrounding text
4521−with blank lines, and start and end at the left margin. Within
4522−these blocks, everything is interpreted as HTML, not Markdown;
4523−so (for example), `*` does not signify emphasis.
4524−
4525−Pandoc behaves this way when the `markdown_strict` format is used; but
4526−by default, pandoc interprets material between HTML block tags as Markdown.
4527−Thus, for example, pandoc will turn
4528−
4529− <table>
4530− <tr>
4531− <td>*one*</td>
4532− <td>[a link](https://google.com)</td>
4533− </tr>
4534− </table>
4535−
4536−into
4537−
4538− <table>
4539− <tr>
4540− <td><em>one</em></td>
4541− <td><a href="https://google.com">a link</a></td>
4542− </tr>
4543− </table>
4544−
4545−whereas `Markdown.pl` will preserve it as is.
4546−
4547−There is one exception to this rule: text between `<script>`,
4548−`<style>`, and `<textarea>` tags is not interpreted as Markdown.
4549−
4550−This departure from standard Markdown should make it easier to mix
4551−Markdown with HTML block elements. For example, one can surround
4552−a block of Markdown text with `<div>` tags without preventing it
4553−from being interpreted as Markdown.
4554−
4555−#### Extension: `native_divs` ####
4556−
4557−Use native pandoc `Div` blocks for content inside `<div>` tags.
4558−For the most part this should give the same output as
4559−`markdown_in_html_blocks`, but it makes it easier to write pandoc
4560−filters to manipulate groups of blocks.
4561−
4562−#### Extension: `native_spans` ####
4563−
4564−Use native pandoc `Span` blocks for content inside `<span>` tags.
4565−For the most part this should give the same output as `raw_html`,
4566−but it makes it easier to write pandoc filters to manipulate groups
4567−of inlines.
4568−
4569−#### Extension: `raw_tex` ####
4570−
4571−In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
4572−included in a document. Inline TeX commands will be preserved and passed
4573−unchanged to the LaTeX and ConTeXt writers. Thus, for example, you can use
4574−LaTeX to include BibTeX citations:
4575−
4576− This result was proved in \cite{jones.1967}.
4577−
4578−Note that in LaTeX environments, like
4579−
4580− \begin{tabular}{|l|l|}\hline
4581− Age & Frequency \\ \hline
4582− 18--25 & 15 \\
4583− 26--35 & 33 \\
4584− 36--45 & 22 \\ \hline
4585− \end{tabular}
4586−
4587−the material between the begin and end tags will be interpreted as raw
4588−LaTeX, not as Markdown.
4589−
4590−For a more explicit and flexible way of including raw TeX in a
4591−Markdown document, see the [`raw_attribute`
4592−extension][Extension: `raw_attribute`].
4593−
4594−Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
4595−Emacs Org mode, and ConTeXt.
4596−
4597−### Generic raw attribute ###
4598−
4599−#### Extension: `raw_attribute` ####
4600−
4601−Inline spans and fenced code blocks with a special
4602−kind of attribute will be parsed as raw content with the
4603−designated format. For example, the following produces a raw
4604−roff `ms` block:
4605−
4606− ```{=ms}
4607− .MYMACRO
4608− blah blah
4609− ```
4610−And the following produces a raw `html` inline element:
4611−
4612− This is `<a>html</a>`{=html}
4613−
4614−This can be useful to insert raw xml into `docx` documents, e.g.
4615−a pagebreak:
4616−
4617− ```{=openxml}
4618− <w:p>
4619− <w:r>
4620− <w:br w:type="page"/>
4621− </w:r>
4622− </w:p>
4623− ```
4624−
4625−The format name should match the target format name (see
4626−`-t/--to`, above, for a list, or use `pandoc
4627−--list-output-formats`). Use `openxml` for `docx` output,
4628−`opendocument` for `odt` output, `html5` for `epub3` output,
4629−`html4` for `epub2` output, and `latex`, `beamer`,
4630−`ms`, or `html5` for `pdf` output (depending on what you
4631−use for `--pdf-engine`).
4632−
4633−This extension presupposes that the relevant kind of
4634−inline code or fenced code block is enabled. Thus, for
4635−example, to use a raw attribute with a backtick code block,
4636−`backtick_code_blocks` must be enabled.
4637−
4638−The raw attribute cannot be combined with regular attributes.
4639−
4640−## LaTeX macros
4641−
4642−#### Extension: `latex_macros` ####
4643−
4644−When this extension is enabled, pandoc will parse LaTeX
4645−macro definitions and apply the resulting macros to all LaTeX
4646−math and raw LaTeX. So, for example, the following will work in
4647−all output formats, not just LaTeX:
4648−
4649− \newcommand{\tuple}[1]{\langle #1 \rangle}
4650−
4651− $\tuple{a, b, c}$
4652−
4653−Note that LaTeX macros will not be applied if they occur
4654−inside a raw span or block marked with the
4655−[`raw_attribute` extension](#extension-raw_attribute).
4656−
4657−When `latex_macros` is disabled, the raw LaTeX and math will
4658−not have macros applied. This is usually a better approach when
4659−you are targeting LaTeX or PDF.
4660−
4661−Macro definitions in LaTeX will be passed through as raw LaTeX
4662−only if `latex_macros` is not enabled. Macro definitions in
4663−Markdown source (or other formats allowing `raw_tex`) will
4664−be passed through regardless of whether `latex_macros` is
4665−enabled.
4666−
4667−## Links
4668−
4669−Markdown allows links to be specified in several ways.
4670−
4671−### Automatic links ###
4672−
4673−If you enclose a URL or email address in pointy brackets, it
4674−will become a link:
4675−
4676− <https://google.com>
4677− <sam@green.eggs.ham>
4678−
4679−### Inline links ###
4680−
4681−An inline link consists of the link text in square brackets,
4682−followed by the URL in parentheses. (Optionally, the URL can
4683−be followed by a link title, in quotes.)
4684−
4685− This is an [inline link](/url), and here's [one with
4686− a title](https://fsf.org "click here for a good time!").
4687−
4688−There can be no space between the bracketed part and the parenthesized part.
4689−The link text can contain formatting (such as emphasis), but the title cannot.
4690−
4691−Email addresses in inline links are not autodetected, so they have to be
4692−prefixed with `mailto`:
4693−
4694− [Write me!](mailto:sam@green.eggs.ham)
4695−
4696−### Reference links ###
4697−
4698−An *explicit* reference link has two parts, the link itself and the link
4699−definition, which may occur elsewhere in the document (either
4700−before or after the link).
4701−
4702−The link consists of link text in square brackets, followed by a label in
4703−square brackets. (There cannot be space between the two unless the
4704−`spaced_reference_links` extension is enabled.) The link definition
4705−consists of the bracketed label, followed by a colon and a space, followed by
4706−the URL, and optionally (after a space) a link title either in quotes or in
4707−parentheses. The label must not be parseable as a citation (assuming
4708−the `citations` extension is enabled): citations take precedence over
4709−link labels.
4710−
4711−Here are some examples:
4712−
4713− [my label 1]: /foo/bar.html "My title, optional"
4714− [my label 2]: /foo
4715− [my label 3]: https://fsf.org (The free software foundation)
4716− [my label 4]: /bar#special 'A title in single quotes'
4717−
4718−The URL may optionally be surrounded by angle brackets:
4719−
4720− [my label 5]: <http://foo.bar.baz>
4721−
4722−The title may go on the next line:
4723−
4724− [my label 3]: https://fsf.org
4725− "The free software foundation"
4726−
4727−Note that link labels are not case sensitive. So, this will work:
4728−
4729− Here is [my link][FOO]
4730−
4731− [Foo]: /bar/baz
4732−
4733−In an *implicit* reference link, the second pair of brackets is
4734−empty:
4735−
4736− See [my website][].
4737−
4738− [my website]: http://foo.bar.baz
4739−
4740−Note: In `Markdown.pl` and most other Markdown implementations,
4741−reference link definitions cannot occur in nested constructions
4742−such as list items or block quotes. Pandoc lifts this arbitrary
4743−seeming restriction. So the following is fine in pandoc, though
4744−not in most other implementations:
4745−
4746− > My block [quote].
4747− >
4748− > [quote]: /foo
4749−
4750−#### Extension: `shortcut_reference_links` ####
4751−
4752−In a *shortcut* reference link, the second pair of brackets may
4753−be omitted entirely:
4754−
4755− See [my website].
4756−
4757− [my website]: http://foo.bar.baz
4758−
4759−### Internal links ###
4760−
4761−To link to another section of the same document, use the automatically
4762−generated identifier (see [Heading identifiers]). For example:
4763−
4764− See the [Introduction](#introduction).
4765−
4766−or
4767−
4768− See the [Introduction].
4769−
4770− [Introduction]: #introduction
4771−
4772−Internal links are currently supported for HTML formats (including
4773−HTML slide shows and EPUB), LaTeX, and ConTeXt.
4774−
4775−## Images
4776−
4777−A link immediately preceded by a `!` will be treated as an image.
4778−The link text will be used as the image's alt text:
4779−
4780− 
4781−
4782− ![movie reel]
4783−
4784− [movie reel]: movie.gif
4785−
4786−#### Extension: `implicit_figures` ####
4787−
4788−An image with nonempty alt text, occurring by itself in a
4789−paragraph, will be rendered as a figure with a caption. The
4790−image's alt text will be used as the caption.
4791−
4792− 
4793−
4794−How this is rendered depends on the output format. Some output
4795−formats (e.g. RTF) do not yet support figures. In those
4796−formats, you'll just get an image in a paragraph by itself, with
4797−no caption.
4798−
4799−If you just want a regular inline image, just make sure it is not
4800−the only thing in the paragraph. One way to do this is to insert a
4801−nonbreaking space after the image:
4802−
4803− \
4804−
4805−Note that in reveal.js slide shows, an image in a paragraph
4806−by itself that has the `stretch` class will fill the screen,
4807−and the caption and figure tags will be omitted.
4808−
4809−#### Extension: `link_attributes` ####
4810−
4811−Attributes can be set on links and images:
4812−
4813− An inline {#id .class width=30 height=20px}
4814− and a reference ![image][ref] with attributes.
4815−
4816− [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
4817−
4818−(This syntax is compatible with [PHP Markdown Extra] when only `#id`
4819−and `.class` are used.)
4820−
4821−For HTML and EPUB, all known HTML5 attributes except `width` and
4822−`height` (but including `srcset` and `sizes`) are passed through
4823−as is. Unknown attributes are passed through as custom
4824−attributes, with `data-` prepended. The other writers ignore
4825−attributes that are not specifically supported by their output format.
4826−
4827−The `width` and `height` attributes on images are treated specially. When
4828−used without a unit, the unit is assumed to be pixels. However, any of
4829−the following unit identifiers can be used: `px`, `cm`, `mm`, `in`, `inch`
4830−and `%`. There must not be any spaces between the number and the unit.
4831−For example:
4832−
4833−```
4834−{ width=50% }
4835−```
4836−
4837−- Dimensions may be converted to a form that is compatible with
4838− the output format (for example, dimensions given in pixels will
4839− be converted to inches when converting HTML to LaTeX). Conversion
4840− between pixels and physical measurements is affected by the
4841− `--dpi` option (by default, 96 dpi is assumed, unless the image
4842− itself contains dpi information).
4843−- The `%` unit is generally relative to some available space.
4844− For example the above example will render to the following.
4845− - HTML: `<img href="file.jpg" style="width: 50%;" />`
4846− - LaTeX: `\includegraphics[width=0.5\textwidth,height=\textheight]{file.jpg}`
4847− (If you're using a custom template, you need to configure `graphicx`
4848− as in the default template.)
4849− - ConTeXt: `\externalfigure[file.jpg][width=0.5\textwidth]`
4850−- Some output formats have a notion of a class
4851− ([ConTeXt](https://wiki.contextgarden.net/Using_Graphics#Multiple_Image_Settings))
4852− or a unique identifier (LaTeX `\caption`), or both (HTML).
4853−- When no `width` or `height` attributes are specified, the fallback
4854− is to look at the image resolution and the dpi metadata embedded in
4855− the image file.
4856−
4857−## Divs and Spans
4858−
4859−Using the `native_divs` and `native_spans` extensions
4860−(see [above][Extension: `native_divs`]), HTML syntax can
4861−be used as part of markdown to create native `Div` and `Span`
4862−elements in the pandoc AST (as opposed to raw HTML).
4863−However, there is also nicer syntax available:
4864−
4865−#### Extension: `fenced_divs` ####
4866−
4867−Allow special fenced syntax for native `Div` blocks. A Div
4868−starts with a fence containing at least three consecutive
4869−colons plus some attributes. The attributes may optionally
4870−be followed by another string of consecutive colons.
4871−The attribute syntax is exactly as in fenced code blocks (see
4872−[Extension: `fenced_code_attributes`]). As with fenced
4873−code blocks, one can use either attributes in curly braces
4874−or a single unbraced word, which will be treated as a class
4875−name. The Div ends with another line containing a string of at
4876−least three consecutive colons. The fenced Div should be
4877−separated by blank lines from preceding and following blocks.
4878−
4879−Example:
4880−
4881− ::::: {#special .sidebar}
4882− Here is a paragraph.
4883−
4884− And another.
4885− :::::
4886−
4887−Fenced divs can be nested. Opening fences are distinguished
4888−because they *must* have attributes:
4889−
4890− ::: Warning ::::::
4891− This is a warning.
4892−
4893− ::: Danger
4894− This is a warning within a warning.
4895− :::
4896− ::::::::::::::::::
4897−
4898−Fences without attributes are always closing fences. Unlike
4899−with fenced code blocks, the number of colons in the closing
4900−fence need not match the number in the opening fence. However,
4901−it can be helpful for visual clarity to use fences of different
4902−lengths to distinguish nested divs from their parents.
4903−
4904−
4905−#### Extension: `bracketed_spans` ####
4906−
4907−A bracketed sequence of inlines, as one would use to begin
4908−a link, will be treated as a `Span` with attributes if it is
4909−followed immediately by attributes:
4910−
4911− [This is *some text*]{.class key="val"}
4912−
4913−## Footnotes
4914−
4915−#### Extension: `footnotes` ####
4916−
4917−Pandoc's Markdown allows footnotes, using the following syntax:
4918−
4919− Here is a footnote reference,[^1] and another.[^longnote]
4920−
4921− [^1]: Here is the footnote.
4922−
4923− [^longnote]: Here's one with multiple blocks.
4924−
4925− Subsequent paragraphs are indented to show that they
4926− belong to the previous footnote.
4927−
4928− { some.code }
4929−
4930− The whole paragraph can be indented, or just the first
4931− line. In this way, multi-paragraph footnotes work like
4932− multi-paragraph list items.
4933−
4934− This paragraph won't be part of the note, because it
4935− isn't indented.
4936−
4937−The identifiers in footnote references may not contain spaces, tabs,
4938−or newlines. These identifiers are used only to correlate the
4939−footnote reference with the note itself; in the output, footnotes
4940−will be numbered sequentially.
4941−
4942−The footnotes themselves need not be placed at the end of the
4943−document. They may appear anywhere except inside other block elements
4944−(lists, block quotes, tables, etc.). Each footnote should be
4945−separated from surrounding content (including other footnotes)
4946−by blank lines.
4947−
4948−#### Extension: `inline_notes` ####
4949−
4950−Inline footnotes are also allowed (though, unlike regular notes,
4951−they cannot contain multiple paragraphs). The syntax is as follows:
4952−
4953− Here is an inline note.^[Inlines notes are easier to write, since
4954− you don't have to pick an identifier and move down to type the
4955− note.]
4956−
4957−Inline and regular footnotes may be mixed freely.
4958−
4959−## Citation syntax
4960−
4961−#### Extension: `citations` ####
4962−
4963−To cite a bibliographic item with an identifier foo, use the
4964−syntax `@foo`. Normal citations should be included in square
4965−brackets, with semicolons separating distinct items:
4966−
4967− Blah blah [@doe99; @smith2000; @smith2004].
4968−
4969−How this is rendered depends on the citation style. In an
4970−author-date style, it might render as
4971−
4972− Blah blah (Doe 1999, Smith 2000, 2004).
4973−
4974−In a footnote style, it might render as
4975−
4976− Blah blah.[^1]
4977−
4978− [^1]: John Doe, "Frogs," *Journal of Amphibians* 44 (1999);
4979− Susan Smith, "Flies," *Journal of Insects* (2000);
4980− Susan Smith, "Bees," *Journal of Insects* (2004).
4981−
4982−See the [CSL user documentation] for more information about CSL
4983−styles and how they affect rendering.
4984−
4985−Unless a citation key start with a letter, digit, or `_`,
4986−and contains only alphanumerics and internal punctuation
4987−characters (`:.#$%&-+?<>~/`), it must be surrounded
4988−by curly braces, which are not considered part of the key.
4989−In `@Foo_bar.baz.`, the key is `Foo_bar.baz`. The final
4990−period is not *internal* punctuation, so it is not included in
4991−the key. In `@{Foo_bar.baz.}`, the key is `Foo_bar.baz.`, including
4992−the final period. The curly braces are recommended if you use URLs as
4993−keys: `[@{https://example.com/bib?name=foobar&date=2000}, p. 33]`.
4994−
4995−Citation items may optionally include a prefix, a locator, and
4996−a suffix. In
4997−
4998− Blah blah [see @doe99, pp. 33-35 and *passim*; @smith04, chap. 1].
4999−
5000−The first item (`doe99`) has prefix `see `, locator `pp. 33-35`,
5001−and suffix `and *passim*`. The second item (`smith04`) has
5002−locator `chap. 1` and no prefix or suffix.
5003−
5004−Pandoc uses some heuristics to separate the locator from the
5005−rest of the subject. It is sensitive to the locator terms
5006−defined in the [CSL locale files]. Either abbreviated or
5007−unabbreviated forms are accepted. In the `en-US` locale, locator
5008−terms can be written in either singular or plural forms, as
5009−`book`, `bk.`/`bks.`; `chapter`, `chap.`/`chaps.`; `column`,
5010−`col.`/`cols.`; `figure`, `fig.`/`figs.`; `folio`,
5011−`fol.`/`fols.`; `number`, `no.`/`nos.`; `line`, `l.`/`ll.`;
5012−`note`, `n.`/`nn.`; `opus`, `op.`/`opp.`; `page`, `p.`/`pp.`;
5013−`paragraph`, `para.`/`paras.`; `part`, `pt.`/`pts.`; `section`,
5014−`sec.`/`secs.`; `sub verbo`, `s.v.`/`s.vv.`; `verse`,
5015−`v.`/`vv.`; `volume`, `vol.`/`vols.`; `¶`/`¶¶`; `§`/`§§`. If no
5016−locator term is used, "page" is assumed.
5017−
5018−In complex cases, you can force something to be treated as
5019−a locator by enclosing it in curly braces or prevent parsing
5020−the suffix as locator by prepending curly braces:
5021−
5022− [@smith{ii, A, D-Z}, with a suffix]
5023− [@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
5024− [@smith{}, 99 years later]
5025−
5026−A minus sign (`-`) before the `@` will suppress mention of
5027−the author in the citation. This can be useful when the
5028−author is already mentioned in the text:
5029−
5030− Smith says blah [-@smith04].
5031−
5032−You can also write an author-in-text citation, by omitting the
5033−square brackets:
5034−
5035− @smith04 says blah.
5036−
5037− @smith04 [p. 33] says blah.
5038−
5039−This will cause the author's name to be rendered, followed by
5040−the bibliographical details. Use this form when you want to
5041−make the citation the subject of a sentence.
5042−
5043−When you are using a note style, it is usually better to let
5044−citeproc create the footnotes from citations rather than writing
5045−an explicit note. If you do write an explicit note that
5046−contains a citation, note that normal citations will be put in
5047−parentheses, while author-in-text citations will not. For
5048−this reason, it is sometimes preferable to use the
5049−author-in-text style inside notes when using a note style.
5050−
5051−[CSL user documentation]: https://citationstyles.org/authors/
5052−[CSL]: https://docs.citationstyles.org/en/stable/specification.html
5053−[CSL markup specs]: https://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields
5054−[Chicago Manual of Style]: https://chicagomanualofstyle.org
5055−[Citation Style Language]: https://citationstyles.org
5056−[Zotero Style Repository]: https://www.zotero.org/styles
5057−[finding and editing styles]: https://citationstyles.org/authors/
5058−[CSL locale files]: https://github.com/citation-style-language/locales
5059−
5060−## Non-default extensions
5061−
5062−The following Markdown syntax extensions are not enabled by default
5063−in pandoc, but may be enabled by adding `+EXTENSION` to the format
5064−name, where `EXTENSION` is the name of the extension. Thus, for
5065−example, `markdown+hard_line_breaks` is Markdown with hard line breaks.
5066−
5067−#### Extension: `rebase_relative_paths` ####
5068−
5069−Rewrite relative paths for Markdown links and images, depending
5070−on the path of the file containing the link or image link. For
5071−each link or image, pandoc will compute the directory of the
5072−containing file, relative to the working directory, and prepend
5073−the resulting path to the link or image path.
5074−
5075−The use of this extension is best understood by example.
5076−Suppose you have a a subdirectory for each chapter of a book,
5077−`chap1`, `chap2`, `chap3`. Each contains a file `text.md` and a
5078−number of images used in the chapter. You would like to have
5079−`` in `chap1/text.md` refer to
5080−`chap1/spider.jpg` and `` in `chap2/text.md`
5081−refer to `chap2/spider.jpg`. To do this, use
5082−
5083− pandoc chap*/*.md -f markdown+rebase_relative_paths
5084−
5085−Without this extension, you would have to use
5086−`` in `chap1/text.md` and
5087−`` in `chap2/text.md`. Links with
5088−relative paths will be rewritten in the same way as images.
5089−
5090−Absolute paths and URLs are not changed. Neither are empty
5091−paths or paths consisting entirely of a fragment, e.g., `#foo`.
5092−
5093−Note that relative paths in reference links and images will
5094−be rewritten relative to the file containing the link
5095−reference definition, not the file containing the reference link
5096−or image itself, if these differ.
5097−
5098−#### Extension: `attributes` ####
5099−
5100−Allows attributes to be attached to any inline or block-level
5101−element. The syntax for the attributes is the same as that
5102−used in [`header_attributes`][Extension: `header_attributes`].
5103−
5104−- Attributes that occur immediately after an inline
5105− element affect that element. If they follow a space, then they
5106− belong to the space. (Hence, this option subsumes
5107− `inline_code_attributes` and `link_attributes`.)
5108−- Attributes that occur immediately before a block
5109− element, on a line by themselves, affect that
5110− element.
5111−- Consecutive attribute specifiers may be used,
5112− either for blocks or for inlines. Their attributes
5113− will be combined.
5114−- Attributes that occur at the end of the text of
5115− a Setext or ATX heading (separated by whitespace
5116− from the text) affect the heading element. (Hence, this
5117− option subsumes `header_attributes`.)
5118−- Attributes that occur after the opening fence
5119− in a fenced code block affect the code block element. (Hence,
5120− this option subsumes `fenced_code_attributes`.)
5121−- Attributes that occur at the end of a reference
5122− link definition affect links that refer to that
5123− definition.
5124−
5125−Note that pandoc's AST does not currently allow attributes
5126−to be attached to arbitrary elements. Hence a Span or Div
5127−container will be added if needed.
5128−
5129−#### Extension: `old_dashes` ####
5130−
5131−Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
5132−`-` before a numeral is an en-dash, and `--` is an em-dash.
5133−This option only has an effect if `smart` is enabled. It is
5134−selected automatically for `textile` input.
5135−
5136−#### Extension: `angle_brackets_escapable` ####
5137−
5138−Allow `<` and `>` to be backslash-escaped, as they can be in
5139−GitHub flavored Markdown but not original Markdown. This is
5140−implied by pandoc's default `all_symbols_escapable`.
5141−
5142−#### Extension: `lists_without_preceding_blankline` ####
5143−
5144−Allow a list to occur right after a paragraph, with no intervening
5145−blank space.
5146−
5147−#### Extension: `four_space_rule` ####
5148−
5149−Selects the pandoc <= 2.0 behavior for parsing lists, so that
5150−four spaces indent are needed for list item continuation
5151−paragraphs.
5152−
5153−#### Extension: `spaced_reference_links` ####
5154−
5155−Allow whitespace between the two components of a reference link,
5156−for example,
5157−
5158− [foo] [bar].
5159−
5160−#### Extension: `hard_line_breaks` ####
5161−
5162−Causes all newlines within a paragraph to be interpreted as hard line
5163−breaks instead of spaces.
5164−
5165−#### Extension: `ignore_line_breaks` ####
5166−
5167−Causes newlines within a paragraph to be ignored, rather than being
5168−treated as spaces or as hard line breaks. This option is intended for
5169−use with East Asian languages where spaces are not used between words,
5170−but text is divided into lines for readability.
5171−
5172−#### Extension: `east_asian_line_breaks` ####
5173−
5174−Causes newlines within a paragraph to be ignored, rather than
5175−being treated as spaces or as hard line breaks, when they occur
5176−between two East Asian wide characters. This is a better choice
5177−than `ignore_line_breaks` for texts that include a mix of East
5178−Asian wide characters and other characters.
5179−
5180−#### Extension: `emoji` ####
5181−
5182−Parses textual emojis like `:smile:` as Unicode emoticons.
5183−
5184−#### Extension: `tex_math_single_backslash` ####
5185−
5186−Causes anything between `\(` and `\)` to be interpreted as inline
5187−TeX math, and anything between `\[` and `\]` to be interpreted
5188−as display TeX math. Note: a drawback of this extension is that
5189−it precludes escaping `(` and `[`.
5190−
5191−#### Extension: `tex_math_double_backslash` ####
5192−
5193−Causes anything between `\\(` and `\\)` to be interpreted as inline
5194−TeX math, and anything between `\\[` and `\\]` to be interpreted
5195−as display TeX math.
5196−
5197−#### Extension: `markdown_attribute` ####
5198−
5199−By default, pandoc interprets material inside block-level tags as Markdown.
5200−This extension changes the behavior so that Markdown is only parsed
5201−inside block-level tags if the tags have the attribute `markdown=1`.
5202−
5203−#### Extension: `mmd_title_block` ####
5204−
5205−Enables a [MultiMarkdown] style title block at the top of
5206−the document, for example:
5207−
5208− Title: My title
5209− Author: John Doe
5210− Date: September 1, 2008
5211− Comment: This is a sample mmd title block, with
5212− a field spanning multiple lines.
5213−
5214−See the MultiMarkdown documentation for details. If `pandoc_title_block` or
5215−`yaml_metadata_block` is enabled, it will take precedence over
5216−`mmd_title_block`.
5217−
5218−#### Extension: `abbreviations` ####
5219−
5220−Parses PHP Markdown Extra abbreviation keys, like
5221−
5222− *[HTML]: Hypertext Markup Language
5223−
5224−Note that the pandoc document model does not support
5225−abbreviations, so if this extension is enabled, abbreviation keys are
5226−simply skipped (as opposed to being parsed as paragraphs).
5227−
5228−#### Extension: `autolink_bare_uris` ####
5229−
5230−Makes all absolute URIs into links, even when not surrounded by
5231−pointy braces `<...>`.
5232−
5233−#### Extension: `mmd_link_attributes` ####
5234−
5235−Parses multimarkdown style key-value attributes on link
5236−and image references. This extension should not be confused with the
5237−[`link_attributes`](#extension-link_attributes) extension.
5238−
5239− This is a reference ![image][ref] with multimarkdown attributes.
5240−
5241− [ref]: https://path.to/image "Image title" width=20px height=30px
5242− id=myId class="myClass1 myClass2"
5243−
5244−#### Extension: `mmd_header_identifiers` ####
5245−
5246−Parses multimarkdown style heading identifiers (in square brackets,
5247−after the heading but before any trailing `#`s in an ATX heading).
5248−
5249−#### Extension: `compact_definition_lists` ####
5250−
5251−Activates the definition list syntax of pandoc 1.12.x and earlier.
5252−This syntax differs from the one described above under [Definition lists]
5253−in several respects:
5254−
5255− - No blank line is required between consecutive items of the
5256− definition list.
5257− - To get a "tight" or "compact" list, omit space between consecutive
5258− items; the space between a term and its definition does not affect
5259− anything.
5260− - Lazy wrapping of paragraphs is not allowed: the entire definition must
5261− be indented four spaces.[^6]
5262−
5263−[^6]: To see why laziness is incompatible with relaxing the requirement
5264− of a blank line between items, consider the following example:
5265−
5266− bar
5267− : definition
5268− foo
5269− : definition
5270−
5271− Is this a single list item with two definitions of "bar," the first of
5272− which is lazily wrapped, or two list items? To remove the ambiguity
5273− we must either disallow lazy wrapping or require a blank line between
5274− list items.
5275−
5276−#### Extension: `gutenberg` ####
5277−
5278−Use [Project Gutenberg] conventions for `plain` output:
5279−all-caps for strong emphasis, surround by underscores
5280−for regular emphasis, add extra blank space around headings.
5281−
5282− [Project Gutenberg]: https://www.gutenberg.org
5283−
5284−#### Extension: `sourcepos` ####
5285−
5286−Include source position attributes when parsing `commonmark`.
5287−For elements that accept attributes, a `data-pos` attribute
5288−is added; other elements are placed in a surrounding
5289−Div or Span elemnet with a `data-pos` attribute.
5290−
5291−## Markdown variants
5292−
5293−In addition to pandoc's extended Markdown, the following Markdown
5294−variants are supported:
5295−
5296−- `markdown_phpextra` (PHP Markdown Extra)
5297−- `markdown_github` (deprecated GitHub-Flavored Markdown)
5298−- `markdown_mmd` (MultiMarkdown)
5299−- `markdown_strict` (Markdown.pl)
5300−- `commonmark` (CommonMark)
5301−- `gfm` (Github-Flavored Markdown)
5302−- `commonmark_x` (CommonMark with many pandoc extensions)
5303−
5304−To see which extensions are supported for a given format,
5305−and which are enabled by default, you can use the command
5306−
5307− pandoc --list-extensions=FORMAT
5308−
5309−where `FORMAT` is replaced with the name of the format.
5310−
5311−Note that the list of extensions for `commonmark`,
5312−`gfm`, and `commonmark_x` are defined relative to default
5313−commonmark. So, for example, `backtick_code_blocks`
5314−does not appear as an extension, since it is enabled by
5315−default and cannot be disabled.
5316−
5317−# Citations
5318−
5319−When the `--citeproc` option is used, pandoc can automatically generate
5320−citations and a bibliography in a number of styles. Basic usage is
5321−
5322− pandoc --citeproc myinput.txt
5323−
5324−To use this feature, you will need to have
5325−
5326−- a document containing citations (see [Extension: `citations`]);
5327−- a source of bibliographic data: either an external bibliography
5328− file or a list of `references` in the document's YAML metadata
5329−- optionally, a [CSL] citation style.
5330−
5331−## Specifying bibliographic data
5332−
5333−You can specify an external bibliography using the
5334−`bibliography` metadata field in a YAML metadata section or the
5335−`--bibliography` command line argument. If you want to use
5336−multiple bibliography files, you can supply multiple
5337−`--bibliography` arguments or set `bibliography` metadata field
5338−to YAML array. A bibliography may have any of these formats:
5339−
5340− Format File extension
5341− ------------ --------------
5342− BibLaTeX .bib
5343− BibTeX .bibtex
5344− CSL JSON .json
5345− CSL YAML .yaml
5346−
5347−Note that `.bib` can be used with both BibTeX and BibLaTeX files;
5348−use the extension `.bibtex` to force interpretation as BibTeX.
5349−
5350−In BibTeX and BibLaTeX databases, pandoc parses LaTeX markup
5351−inside fields such as `title`; in CSL YAML databases, pandoc
5352−Markdown; and in CSL JSON databases, an [HTML-like markup][CSL
5353−markup specs]:
5354−
5355−`<i>...</i>`
5356−: italics
5357−
5358−`<b>...</b>`
5359−: bold
5360−
5361−`<span style="font-variant:small-caps;">...</span>` or `<sc>...</sc>`
5362−: small capitals
5363−
5364−`<sub>...</sub>`
5365−: subscript
5366−
5367−`<sup>...</sup>`
5368−: superscript
5369−
5370−`<span class="nocase">...</span>`
5371−: prevent a phrase from being capitalized as title case
5372−
5373−As an alternative to specifying a bibliography file using
5374−`--bibliography` or the YAML metadata field `bibliography`, you
5375−can include the citation data directly in the `references` field
5376−of the document's YAML metadata. The field should contain an
5377−array of YAML-encoded references, for example:
5378−
5379− ---
5380− references:
5381− - type: article-journal
5382− id: WatsonCrick1953
5383− author:
5384− - family: Watson
5385− given: J. D.
5386− - family: Crick
5387− given: F. H. C.
5388− issued:
5389− date-parts:
5390− - - 1953
5391− - 4
5392− - 25
5393− title: 'Molecular structure of nucleic acids: a structure for
5394− deoxyribose nucleic acid'
5395− title-short: Molecular structure of nucleic acids
5396− container-title: Nature
5397− volume: 171
5398− issue: 4356
5399− page: 737-738
5400− DOI: 10.1038/171737a0
5401− URL: https://www.nature.com/articles/171737a0
5402− language: en-GB
5403− ...
5404−
5405−If both an external bibliography and inline (YAML metadata)
5406−references are provided, both will be used. In case of
5407−conflicting `id`s, the inline references will take precedence.
5408−
5409−Note that `pandoc` can be used to produce such a YAML metadata
5410−section from a BibTeX, BibLaTeX, or CSL JSON bibliography:
5411−
5412− pandoc chem.bib -s -f biblatex -t markdown
5413− pandoc chem.json -s -f csljson -t markdown
5414−
5415−Indeed, `pandoc` can convert between any of these
5416−citation formats:
5417−
5418− pandoc chem.bib -s -f biblatex -t csljson
5419− pandoc chem.yaml -s -f markdown -t biblatex
5420−
5421−Running pandoc on a bibliography file with the `--citeproc`
5422−option will create a formatted bibliography in the format
5423−of your choice:
5424−
5425− pandoc chem.bib -s --citeproc -o chem.html
5426− pandoc chem.bib -s --citeproc -o chem.pdf
5427−
5428−### Capitalization in titles
5429−
5430−If you are using a bibtex or biblatex bibliography, then observe
5431−the following rules:
5432−
5433− - English titles should be in title case. Non-English titles should
5434− be in sentence case, and the `langid` field in biblatex should be
5435− set to the relevant language. (The following values are treated
5436− as English: `american`, `british`, `canadian`, `english`,
5437− `australian`, `newzealand`, `USenglish`, or `UKenglish`.)
5438−
5439− - As is standard with bibtex/biblatex, proper names should be
5440− protected with curly braces so that they won't be lowercased
5441− in styles that call for sentence case. For example:
5442−
5443− title = {My Dinner with {Andre}}
5444−
5445− - In addition, words that should remain lowercase (or camelCase)
5446− should be protected:
5447−
5448− title = {Spin Wave Dispersion on the {nm} Scale}
5449−
5450− Though this is not necessary in bibtex/biblatex, it is necessary
5451− with citeproc, which stores titles internally in sentence case,
5452− and converts to title case in styles that require it. Here we
5453− protect "nm" so that it doesn't get converted to "Nm" at this stage.
5454−
5455−If you are using a CSL bibliography (either JSON or YAML), then observe
5456−the following rules:
5457−
5458− - All titles should be in sentence case.
5459−
5460− - Use the `language` field for non-English titles to prevent their
5461− conversion to title case in styles that call for this. (Conversion
5462− happens only if `language` begins with `en` or is left empty.)
5463−
5464− - Protect words that should not be converted to title case using
5465− this syntax:
5466−
5467− Spin wave dispersion on the <span class="nocase">nm</span> scale
5468−
5469−### Conference Papers, Published vs. Unpublished
5470−
5471−For a formally published conference paper, use the biblatex entry type
5472−`inproceedings` (which will be mapped to CSL `paper-conference`).
5473−
5474−For an unpublished manuscript, use the biblatex entry type
5475−`unpublished` without an `eventtitle` field (this entry type
5476−will be mapped to CSL `manuscript`).
5477−
5478−For a talk, an unpublished conference paper, or a poster
5479−presentation, use the biblatex entry type `unpublished` with an
5480−`eventtitle` field (this entry type will be mapped to CSL
5481−`speech`). Use the biblatex `type` field to indicate the type,
5482−e.g. "Paper", or "Poster". `venue` and `eventdate` may be useful
5483−too, though `eventdate` will not be rendered by most CSL styles.
5484−Note that `venue` is for the event's venue, unlike `location`
5485−which describes the publisher's location; do not use the latter
5486−for an unpublished conference paper.
5487−
5488−
5489−## Specifying a citation style
5490−
5491−Citations and references can be formatted using any style supported by the
5492−[Citation Style Language], listed in the [Zotero Style Repository].
5493−These files are specified using the `--csl` option or the `csl`
5494−(or `citation-style`) metadata field. By default, pandoc will
5495−use the [Chicago Manual of Style] author-date format. (You can
5496−override this default by copying a CSL style of your choice
5497−to `default.csl` in your user data directory.)
5498−The CSL project provides further information on [finding and
5499−editing styles].
5500−
5501−The `--citation-abbreviations` option (or the
5502−`citation-abbreviations` metadata field) may be used to specify
5503−a JSON file containing abbreviations of journals that should be
5504−used in formatted bibliographies when `form="short"` is
5505−specified. The format of the file can be illustrated with an
5506−example:
5507−
5508−
5509− { "default": {
5510− "container-title": {
5511− "Lloyd's Law Reports": "Lloyd's Rep",
5512− "Estates Gazette": "EG",
5513− "Scots Law Times": "SLT"
5514− }
5515− }
5516− }
5517−
5518−
5519−## Citations in note styles
5520−
5521−Pandoc's citation processing is designed to allow you to
5522−move between author-date, numerical, and note styles without
5523−modifying the markdown source. When you're using a note
5524−style, avoid inserting footnotes manually. Instead, insert
5525−citations just as you would in an author-date style---for
5526−example,
5527−
5528− Blah blah [@foo, p. 33].
5529−
5530−The footnote will be created automatically. Pandoc will take
5531−care of removing the space and moving the note before or
5532−after the period, depending on the setting of
5533−`notes-after-punctuation`, as described below in [Other relevant
5534−metadata fields].
5535−
5536−In some cases you may need to put a citation inside a regular
5537−footnote. Normal citations in footnotes (such as `[@foo, p.
5538−33]`) will be rendered in parentheses. In-text citations (such
5539−as `@foo [p. 33]`) will be rendered without parentheses. (A
5540−comma will be added if appropriate.) Thus:
5541−
5542− [^1]: Some studies [@foo; @bar, p. 33] show that
5543− frubulicious zoosnaps are quantical. For a survey
5544− of the literature, see @baz [chap. 1].
5545−
5546−## Raw content in a style
5547−
5548−To include raw content in a prefix, suffix, delimiter, or term,
5549−surround it with these tags indicating the format:
5550−
5551− {{jats}}<ref>{{/jats}}
5552−
5553−Without the tags, the string will be interpreted as a string
5554−and escaped in the output, rather than being passed through raw.
5555−
5556−This feature allows stylesheets to be customized to give
5557−different output for different output formats. However,
5558−stylesheets customized in this way will not be usable
5559−by other CSL implementations.
5560−
5561−
5562−
5563−## Placement of the bibliography
5564−
5565−If the style calls for a list of works cited, it will be placed
5566−in a div with id `refs`, if one exists:
5567−
5568− ::: {#refs}
5569− :::
5570−
5571−Otherwise, it will be placed at the end of the document.
5572−Generation of the bibliography can be suppressed by setting
5573−`suppress-bibliography: true` in the YAML metadata.
5574−
5575−If you wish the bibliography to have a section heading, you can
5576−set `reference-section-title` in the metadata, or put the heading
5577−at the beginning of the div with id `refs` (if you are using it)
5578−or at the end of your document:
5579−
5580− last paragraph...
5581−
5582− # References
5583−
5584−The bibliography will be inserted after this heading. Note that
5585−the `unnumbered` class will be added to this heading, so that the
5586−section will not be numbered.
5587−
5588−## Including uncited items in the bibliography
5589−
5590−If you want to include items in the bibliography without actually
5591−citing them in the body text, you can define a dummy `nocite` metadata
5592−field and put the citations there:
5593−
5594− ---
5595− nocite: |
5596− @item1, @item2
5597− ...
5598−
5599− @item3
5600−
5601−In this example, the document will contain a citation for `item3`
5602−only, but the bibliography will contain entries for `item1`, `item2`, and
5603−`item3`.
5604−
5605−It is possible to create a bibliography with all the citations,
5606−whether or not they appear in the document, by using a wildcard:
5607−
5608− ---
5609− nocite: |
5610− @*
5611− ...
5612−
5613−For LaTeX output, you can also use [`natbib`] or [`biblatex`] to
5614−render the bibliography. In order to do so, specify bibliography
5615−files as outlined above, and add `--natbib` or `--biblatex`
5616−argument to `pandoc` invocation. Bear in mind that bibliography
5617−files have to be in either BibTeX (for `--natbib`)
5618−or BibLaTeX (for `--biblatex`) format.
5619−
5620−## Other relevant metadata fields
5621−
5622−A few other metadata fields affect bibliography formatting:
5623−
5624−`link-citations`
5625−: If true, citations will be
5626− hyperlinked to the corresponding bibliography entries
5627− (for author-date and numerical styles only).
5628−
5629−`lang`
5630−: The `lang` field will affect how the style is localized,
5631− for example in the translation of labels, the use
5632− of quotation marks, and the way items are sorted.
5633− (For backwards compatibility, `locale` may be used instead
5634− of `lang`, but this use is deprecated.)
5635−
5636− A BCP 47 language tag is expected: for example, `en`,
5637− `de`, `en-US`, `fr-CA`, `ug-Cyrl`. The unicode extension
5638− syntax (after `-u-`) may be used to specify options for
5639− collation (sorting) more precisely. Here are some examples:
5640−
5641− - `zh-u-co-pinyin` -- Chinese with the Pinyin collation.
5642− - `es-u-co-trad` -- Spanish with the traditional collation
5643− (with `Ch` sorting after `C`).
5644− - `fr-u-kb` -- French with "backwards" accent sorting
5645− (with `coté` sorting after `côte`).
5646− - `en-US-u-kf-upper` -- English with uppercase letters sorting
5647− before lower (default is lower before upper).
5648−
5649−`notes-after-punctuation`
5650−: If true (the default), pandoc will put footnote citations
5651− after following punctuation. For example, if the source
5652− contains `blah blah [@jones99].`, the result will look like
5653− `blah blah.[^1]`, with the note moved after the period and
5654− the space collapsed. If false, the space will still be
5655− collapsed, but the footnote will not be moved after the
5656− punctuation.
5657−
5658−
5659−# Slide shows
5660−
5661−You can use pandoc to produce an HTML + JavaScript slide presentation
5662−that can be viewed via a web browser. There are five ways to do this,
5663−using [S5], [DZSlides], [Slidy], [Slideous], or [reveal.js].
5664−You can also produce a PDF slide show using LaTeX [`beamer`], or
5665−slides shows in Microsoft [PowerPoint] format.
5666−
5667−Here's the Markdown source for a simple slide show, `habits.txt`:
5668−
5669− % Habits
5670− % John Doe
5671− % March 22, 2005
5672−
5673− # In the morning
5674−
5675− ## Getting up
5676−
5677− - Turn off alarm
5678− - Get out of bed
5679−
5680− ## Breakfast
5681−
5682− - Eat eggs
5683− - Drink coffee
5684−
5685− # In the evening
5686−
5687− ## Dinner
5688−
5689− - Eat spaghetti
5690− - Drink wine
5691−
5692− ------------------
5693−
5694− 
5695−
5696− ## Going to sleep
5697−
5698− - Get in bed
5699− - Count sheep
5700−
5701−To produce an HTML/JavaScript slide show, simply type
5702−
5703− pandoc -t FORMAT -s habits.txt -o habits.html
5704−
5705−where `FORMAT` is either `s5`, `slidy`, `slideous`, `dzslides`, or `revealjs`.
5706−
5707−For Slidy, Slideous, reveal.js, and S5, the file produced by
5708−pandoc with the `-s/--standalone` option embeds a link to
5709−JavaScript and CSS files, which are assumed to be available at
5710−the relative path `s5/default` (for S5), `slideous` (for
5711−Slideous), `reveal.js` (for reveal.js), or at the Slidy website
5712−at `w3.org` (for Slidy). (These paths can be changed by setting
5713−the `slidy-url`, `slideous-url`, `revealjs-url`, or `s5-url`
5714−variables; see [Variables for HTML slides], above.) For
5715−DZSlides, the (relatively short) JavaScript and CSS are included
5716−in the file by default.
5717−
5718−With all HTML slide formats, the `--self-contained` option can
5719−be used to produce a single file that contains all of the data
5720−necessary to display the slide show, including linked scripts,
5721−stylesheets, images, and videos.
5722−
5723−To produce a PDF slide show using beamer, type
5724−
5725− pandoc -t beamer habits.txt -o habits.pdf
5726−
5727−Note that a reveal.js slide show can also be converted to a PDF
5728−by printing it to a file from the browser.
5729−
5730−To produce a Powerpoint slide show, type
5731−
5732− pandoc habits.txt -o habits.pptx
5733−
5734−## Structuring the slide show
5735−
5736−By default, the *slide level* is the highest heading level in
5737−the hierarchy that is followed immediately by content, and not another
5738−heading, somewhere in the document. In the example above, level-1 headings
5739−are always followed by level-2 headings, which are followed by content,
5740−so the slide level is 2. This default can be overridden using
5741−the `--slide-level` option.
5742−
5743−The document is carved up into slides according to the following
5744−rules:
5745−
5746− * A horizontal rule always starts a new slide.
5747−
5748− * A heading at the slide level always starts a new slide.
5749−
5750− * Headings *below* the slide level in the hierarchy create
5751− headings *within* a slide. (In beamer, a "block" will be
5752− created. If the heading has the class `example`, an
5753− `exampleblock` environment will be used; if it has the class
5754− `alert`, an `alertblock` will be used; otherwise a regular
5755− `block` will be used.)
5756−
5757− * Headings *above* the slide level in the hierarchy create
5758− "title slides," which just contain the section title
5759− and help to break the slide show into sections.
5760− Non-slide content under these headings will be included
5761− on the title slide (for HTML slide shows) or in a
5762− subsequent slide with the same title (for beamer).
5763−
5764− * A title page is constructed automatically from the document's title
5765− block, if present. (In the case of beamer, this can be disabled
5766− by commenting out some lines in the default template.)
5767−
5768−These rules are designed to support many different styles of slide show. If
5769−you don't care about structuring your slides into sections and subsections,
5770−you can just use level-1 headings for all each slide. (In that case, level-1
5771−will be the slide level.) But you can also structure the slide show into
5772−sections, as in the example above.
5773−
5774−Note: in reveal.js slide shows, if slide level is 2, a two-dimensional
5775−layout will be produced, with level-1 headings building horizontally
5776−and level-2 headings building vertically. It is not recommended that
5777−you use deeper nesting of section levels with reveal.js.
5778−
5779−## Incremental lists
5780−
5781−By default, these writers produce lists that display "all at once."
5782−If you want your lists to display incrementally (one item at a time),
5783−use the `-i` option. If you want a particular list to depart from the
5784−default, put it in a `div` block with class `incremental` or
5785−`nonincremental`. So, for example, using the `fenced div` syntax, the
5786−following would be incremental regardless of the document default:
5787−
5788− ::: incremental
5789−
5790− - Eat spaghetti
5791− - Drink wine
5792−
5793− :::
5794−
5795−or
5796−
5797− ::: nonincremental
5798−
5799− - Eat spaghetti
5800− - Drink wine
5801−
5802− :::
5803−
5804−While using `incremental` and `nonincremental` divs are the
5805−recommended method of setting incremental lists on a per-case basis,
5806−an older method is also supported: putting lists inside a blockquote
5807−will depart from the document default (that is, it will display
5808−incrementally without the `-i` option and all at once with the `-i`
5809−option):
5810−
5811− > - Eat spaghetti
5812− > - Drink wine
5813−
5814−Both methods allow incremental and nonincremental lists to be mixed
5815−in a single document.
5816−
5817−Note: Neither the `-i/--incremental` option nor any of the
5818−methods described here currently works for PowerPoint output.
5819−
5820−## Inserting pauses
5821−
5822−You can add "pauses" within a slide by including a paragraph containing
5823−three dots, separated by spaces:
5824−
5825− # Slide with a pause
5826−
5827− content before the pause
5828−
5829− . . .
5830−
5831− content after the pause
5832−
5833−Note: this feature is not yet implemented for PowerPoint output.
5834−
5835−## Styling the slides
5836−
5837−You can change the style of HTML slides by putting customized CSS files
5838−in `$DATADIR/s5/default` (for S5), `$DATADIR/slidy` (for Slidy),
5839−or `$DATADIR/slideous` (for Slideous),
5840−where `$DATADIR` is the user data directory (see `--data-dir`, above).
5841−The originals may be found in pandoc's system data directory (generally
5842−`$CABALDIR/pandoc-VERSION/s5/default`). Pandoc will look there for any
5843−files it does not find in the user data directory.
5844−
5845−For dzslides, the CSS is included in the HTML file itself, and may
5846−be modified there.
5847−
5848−All [reveal.js configuration options] can be set through variables.
5849−For example, themes can be used by setting the `theme` variable:
5850−
5851− -V theme=moon
5852−
5853−Or you can specify a custom stylesheet using the `--css` option.
5854−
5855−To style beamer slides, you can specify a `theme`, `colortheme`,
5856−`fonttheme`, `innertheme`, and `outertheme`, using the `-V` option:
5857−
5858− pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
5859−
5860−Note that heading attributes will turn into slide attributes
5861−(on a `<div>` or `<section>`) in HTML slide formats, allowing you
5862−to style individual slides. In beamer, the only heading attribute
5863−that affects slides is the `allowframebreaks` class, which sets the
5864−`allowframebreaks` option, causing multiple slides to be created
5865−if the content overfills the frame. This is recommended especially for
5866−bibliographies:
5867−
5868− # References {.allowframebreaks}
5869−
5870−## Speaker notes
5871−
5872−Speaker notes are supported in reveal.js and PowerPoint (pptx)
5873−output. You can add notes to your Markdown document thus:
5874−
5875− ::: notes
5876−
5877− This is my note.
5878−
5879− - It can contain Markdown
5880− - like this list
5881−
5882− :::
5883−
5884−To show the notes window in reveal.js, press `s` while viewing the
5885−presentation. Speaker notes in PowerPoint will be available, as usual,
5886−in handouts and presenter view.
5887−
5888−Notes are not yet supported for other slide formats, but the notes
5889−will not appear on the slides themselves.
5890−
5891−## Columns
5892−
5893−To put material in side by side columns, you can use a native
5894−div container with class `columns`, containing two or more div
5895−containers with class `column` and a `width` attribute:
5896−
5897− :::::::::::::: {.columns}
5898− ::: {.column width="40%"}
5899− contents...
5900− :::
5901− ::: {.column width="60%"}
5902− contents...
5903− :::
5904− ::::::::::::::
5905−
5906−### Additional columns attributes in beamer
5907−
5908−The div containers with classes `columns` and `column` can optionally have
5909−an `align` attribute.
5910−The class `columns` can optionally have a `totalwidth` attribute or an
5911−`onlytextwidth` class.
5912−
5913− :::::::::::::: {.columns align=center totalwidth=8em}
5914− ::: {.column width="40%"}
5915− contents...
5916− :::
5917− ::: {.column width="60%" align=bottom}
5918− contents...
5919− :::
5920− ::::::::::::::
5921−
5922−The `align` attributes on `columns` and `column` can be used with the
5923−values `top`, `top-baseline`, `center` and `bottom` to vertically align
5924−the columns. It defaults to `top` in `columns`.
5925−
5926−The `totalwidth` attribute limits the width of the columns to the given value.
5927−
5928− :::::::::::::: {.columns align=top .onlytextwidth}
5929− ::: {.column width="40%" align=center}
5930− contents...
5931− :::
5932− ::: {.column width="60%"}
5933− contents...
5934− :::
5935− ::::::::::::::
5936−
5937−The class `onlytextwidth` sets the `totalwidth` to `\textwidth`.
5938−
5939−See Section 12.7 of the [Beamer User's Guide] for more details.
5940−
5941−## Frame attributes in beamer
5942−
5943−Sometimes it is necessary to add the LaTeX `[fragile]` option to
5944−a frame in beamer (for example, when using the `minted` environment).
5945−This can be forced by adding the `fragile` class to the heading
5946−introducing the slide:
5947−
5948− # Fragile slide {.fragile}
5949−
5950−All of the other frame attributes described in Section 8.1 of
5951−the [Beamer User's Guide] may also be used: `allowdisplaybreaks`,
5952−`allowframebreaks`, `b`, `c`, `t`, `environment`, `label`, `plain`,
5953−`shrink`, `standout`, `noframenumbering`.
5954−
5955−## Background in reveal.js and beamer
5956−
5957−Background images can be added to self-contained reveal.js slideshows and
5958−to beamer slideshows.
5959−
5960−For the same image on every slide, use the configuration
5961−option `background-image` either in the YAML metadata block
5962−or as a command-line variable. (There are no other options in
5963−beamer and the rest of this section concerns reveal.js slideshows.)
5964−
5965−For reveal.js, you can instead use the reveal.js-native option
5966−`parallaxBackgroundImage`. You can also set `parallaxBackgroundHorizontal`
5967−and `parallaxBackgroundVertical` the same way and must also set
5968−`parallaxBackgroundSize` to have your values take effect.
5969−
5970−To set an image for a particular reveal.js slide, add
5971−`{data-background-image="/path/to/image"}`
5972−to the first slide-level heading on the slide (which may even be empty).
5973−
5974−In reveal.js's overview mode, the parallaxBackgroundImage will show up
5975−only on the first slide.
5976−
5977−Other reveal.js background settings also work on individual slides, including
5978−`data-background-size`, `data-background-repeat`, `data-background-color`,
5979−`data-transition`, and `data-transition-speed`.
5980−
5981−To add a background image to the automatically generated title slide, use the
5982−`title-slide-attributes` variable in the YAML metadata block. It must contain
5983−a map of attribute names and values.
5984−
5985−See the [reveal.js documentation](https://revealjs.com/backgrounds/) for more
5986−details.
5987−
5988−For example in reveal.js:
5989−
5990−```
5991−---
5992−title: My Slideshow
5993−parallaxBackgroundImage: /path/to/my/background_image.png
5994−title-slide-attributes:
5995− data-background-image: /path/to/title_image.png
5996− data-background-size: contain
5997−---
5998−
5999−## Slide One
6000−
6001−Slide 1 has background_image.png as its background.
6002−
6003−## {data-background-image="/path/to/special_image.jpg"}
6004−
6005−Slide 2 has a special image for its background, even though the heading has no content.
6006−```
6007−
6008−# EPUBs
6009−
6010−## EPUB Metadata
6011−
6012−EPUB metadata may be specified using the `--epub-metadata` option, but
6013−if the source document is Markdown, it is better to use a [YAML metadata
6014−block][Extension: `yaml_metadata_block`]. Here is an example:
6015−
6016− ---
6017− title:
6018− - type: main
6019− text: My Book
6020− - type: subtitle
6021− text: An investigation of metadata
6022− creator:
6023− - role: author
6024− text: John Smith
6025− - role: editor
6026− text: Sarah Jones
6027− identifier:
6028− - scheme: DOI
6029− text: doi:10.234234.234/33
6030− publisher: My Press
6031− rights: © 2007 John Smith, CC BY-NC
6032− ibooks:
6033− version: 1.3.4
6034− ...
6035−
6036−The following fields are recognized:
6037−
6038−`identifier`
6039− ~ Either a string value or an object with fields `text` and
6040− `scheme`. Valid values for `scheme` are `ISBN-10`,
6041− `GTIN-13`, `UPC`, `ISMN-10`, `DOI`, `LCCN`, `GTIN-14`,
6042− `ISBN-13`, `Legal deposit number`, `URN`, `OCLC`,
6043− `ISMN-13`, `ISBN-A`, `JP`, `OLCC`.
6044−
6045−`title`
6046− ~ Either a string value, or an object with fields `file-as` and
6047− `type`, or a list of such objects. Valid values for `type` are
6048− `main`, `subtitle`, `short`, `collection`, `edition`, `extended`.
6049−
6050−`creator`
6051− ~ Either a string value, or an object with fields `role`, `file-as`,
6052− and `text`, or a list of such objects. Valid values for `role` are
6053− [MARC relators], but
6054− pandoc will attempt to translate the human-readable versions
6055− (like "author" and "editor") to the appropriate marc relators.
6056−
6057−`contributor`
6058− ~ Same format as `creator`.
6059−
6060−`date`
6061− ~ A string value in `YYYY-MM-DD` format. (Only the year is necessary.)
6062− Pandoc will attempt to convert other common date formats.
6063−
6064−`lang` (or legacy: `language`)
6065− ~ A string value in [BCP 47] format. Pandoc will default to the local
6066− language if nothing is specified.
6067−
6068−`subject`
6069− ~ A string value or a list of such values.
6070−
6071−`description`
6072− ~ A string value.
6073−
6074−`type`
6075− ~ A string value.
6076−
6077−`format`
6078− ~ A string value.
6079−
6080−`relation`
6081− ~ A string value.
6082−
6083−`coverage`
6084− ~ A string value.
6085−
6086−`rights`
6087− ~ A string value.
6088−
6089−`belongs-to-collection`
6090− ~ A string value. identifies the name of a collection to which
6091− the EPUB Publication belongs.
6092−
6093−`group-position`
6094− ~ The `group-position` field indicates the numeric position in which
6095− the EPUB Publication belongs relative to other works belonging to
6096− the same `belongs-to-collection` field.
6097−
6098−`cover-image`
6099− ~ A string value (path to cover image).
6100−
6101−`css` (or legacy: `stylesheet`)
6102− ~ A string value (path to CSS stylesheet).
6103−
6104−`page-progression-direction`
6105− ~ Either `ltr` or `rtl`. Specifies the `page-progression-direction`
6106− attribute for the [`spine` element].
6107−
6108−`ibooks`
6109− ~ iBooks-specific metadata, with the following fields:
6110−
6111− - `version`: (string)
6112− - `specified-fonts`: `true`|`false` (default `false`)
6113− - `ipad-orientation-lock`: `portrait-only`|`landscape-only`
6114− - `iphone-orientation-lock`: `portrait-only`|`landscape-only`
6115− - `binding`: `true`|`false` (default `true`)
6116− - `scroll-axis`: `vertical`|`horizontal`|`default`
6117−
6118−[MARC relators]: https://loc.gov/marc/relators/relaterm.html
6119−[`spine` element]: http://idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem
6120−
6121−## The `epub:type` attribute
6122−
6123−For `epub3` output, you can mark up the heading that corresponds to an EPUB
6124−chapter using the [`epub:type` attribute][epub-type]. For example, to set
6125−the attribute to the value `prologue`, use this markdown:
6126−
6127− # My chapter {epub:type=prologue}
6128−
6129−Which will result in:
6130−
6131− <body epub:type="frontmatter">
6132− <section epub:type="prologue">
6133− <h1>My chapter</h1>
6134−
6135−Pandoc will output `<body epub:type="bodymatter">`, unless
6136−you use one of the following values, in which case either
6137−`frontmatter` or `backmatter` will be output.
6138−
6139−`epub:type` of first section `epub:type` of body
6140−---------------------------- ------------------
6141−prologue frontmatter
6142−abstract frontmatter
6143−acknowledgments frontmatter
6144−copyright-page frontmatter
6145−dedication frontmatter
6146−credits frontmatter
6147−keywords frontmatter
6148−imprint frontmatter
6149−contributors frontmatter
6150−other-credits frontmatter
6151−errata frontmatter
6152−revision-history frontmatter
6153−titlepage frontmatter
6154−halftitlepage frontmatter
6155−seriespage frontmatter
6156−foreword frontmatter
6157−preface frontmatter
6158−appendix backmatter
6159−colophon backmatter
6160−bibliography backmatter
6161−index backmatter
6162−
6163−[epub-type]: http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-epub-type-attribute
6164−
6165−## Linked media
6166−
6167−By default, pandoc will download media referenced from any `<img>`, `<audio>`,
6168−`<video>` or `<source>` element present in the generated EPUB,
6169−and include it in the EPUB container, yielding a completely
6170−self-contained EPUB. If you want to link to external media resources
6171−instead, use raw HTML in your source and add `data-external="1"` to the tag
6172−with the `src` attribute. For example:
6173−
6174− <audio controls="1">
6175− <source src="https://example.com/music/toccata.mp3"
6176− data-external="1" type="audio/mpeg">
6177− </source>
6178− </audio>
6179−
6180−# Jupyter notebooks
6181−
6182−When creating a [Jupyter notebook], pandoc will try to infer the
6183−notebook structure. Code blocks with the class `code` will be
6184−taken as code cells, and intervening content will be taken as
6185−Markdown cells. Attachments will automatically be created for
6186−images in Markdown cells. Metadata will be taken from the
6187−`jupyter` metadata field. For example:
6188−
6189−````
6190−---
6191−title: My notebook
6192−jupyter:
6193− nbformat: 4
6194− nbformat_minor: 5
6195− kernelspec:
6196− display_name: Python 2
6197− language: python
6198− name: python2
6199− language_info:
6200− codemirror_mode:
6201− name: ipython
6202− version: 2
6203− file_extension: ".py"
6204− mimetype: "text/x-python"
6205− name: "python"
6206− nbconvert_exporter: "python"
6207− pygments_lexer: "ipython2"
6208− version: "2.7.15"
6209−---
6210−
6211−# Lorem ipsum
6212−
6213−**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6214−bibendum felis dictum sodales.
6215−
6216−``` code
6217−print("hello")
6218−```
6219−
6220−## Pyout
6221−
6222−``` code
6223−from IPython.display import HTML
6224−HTML("""
6225−<script>
6226−console.log("hello");
6227−</script>
6228−<b>HTML</b>
6229−""")
6230−```
6231−
6232−## Image
6233−
6234−This image  will be
6235−included as a cell attachment.
6236−````
6237−
6238−If you want to add cell attributes, group cells differently, or
6239−add output to code cells, then you need to include divs to
6240−indicate the structure. You can use either [fenced
6241−divs][Extension: `fenced_divs`] or [native divs][Extension:
6242−`native_divs`] for this. Here is an example:
6243−
6244−````
6245−:::::: {.cell .markdown}
6246−# Lorem
6247−
6248−**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6249−bibendum felis dictum sodales.
6250−::::::
6251−
6252−:::::: {.cell .code execution_count=1}
6253−``` {.python}
6254−print("hello")
6255−```
6256−
6257−::: {.output .stream .stdout}
6258−```
6259−hello
6260−```
6261−:::
6262−::::::
6263−
6264−:::::: {.cell .code execution_count=2}
6265−``` {.python}
6266−from IPython.display import HTML
6267−HTML("""
6268−<script>
6269−console.log("hello");
6270−</script>
6271−<b>HTML</b>
6272−""")
6273−```
6274−
6275−::: {.output .execute_result execution_count=2}
6276−```{=html}
6277−<script>
6278−console.log("hello");
6279−</script>
6280−<b>HTML</b>
6281−hello
6282−```
6283−:::
6284−::::::
6285−````
6286−
6287−If you include raw HTML or TeX in an output cell, use the
6288−[raw attribute][Extension: `fenced_attribute`], as shown
6289−in the last cell of the example above. Although pandoc can
6290−process "bare" raw HTML and TeX, the result is often
6291−interspersed raw elements and normal textual elements, and
6292−in an output cell pandoc expects a single, connected raw
6293−block. To avoid using raw HTML or TeX except when
6294−marked explicitly using raw attributes, we recommend
6295−specifying the extensions `-raw_html-raw_tex+raw_attribute` when
6296−translating between Markdown and ipynb notebooks.
6297−
6298−Note that options and extensions that affect reading and
6299−writing of Markdown will also affect Markdown cells in ipynb
6300−notebooks. For example, `--wrap=preserve` will preserve
6301−soft line breaks in Markdown cells; `--atx-headers` will
6302−cause ATX-style headings to be used; and `--preserve-tabs` will
6303−prevent tabs from being turned to spaces.
6304−
6305−# Syntax highlighting
6306−
6307−Pandoc will automatically highlight syntax in [fenced code blocks] that
6308−are marked with a language name. The Haskell library [skylighting] is
6309−used for highlighting. Currently highlighting is supported only for
6310−HTML, EPUB, Docx, Ms, and LaTeX/PDF output. To see a list of language names
6311−that pandoc will recognize, type `pandoc --list-highlight-languages`.
6312−
6313−The color scheme can be selected using the `--highlight-style` option.
6314−The default color scheme is `pygments`, which imitates the default color
6315−scheme used by the Python library pygments (though pygments is not actually
6316−used to do the highlighting). To see a list of highlight styles,
6317−type `pandoc --list-highlight-styles`.
6318−
6319−If you are not satisfied with the predefined styles, you can
6320−use `--print-highlight-style` to generate a JSON `.theme` file which
6321−can be modified and used as the argument to `--highlight-style`. To
6322−get a JSON version of the `pygments` style, for example:
6323−
6324− pandoc --print-highlight-style pygments > my.theme
6325−
6326−Then edit `my.theme` and use it like this:
6327−
6328− pandoc --highlight-style my.theme
6329−
6330−If you are not satisfied with the built-in highlighting, or you
6331−want highlight a language that isn't supported, you can use the
6332−`--syntax-definition` option to load a [KDE-style XML syntax definition
6333−file](https://docs.kde.org/stable5/en/kate/katepart/highlight.html).
6334−Before writing your own, have a look at KDE's [repository of syntax
6335−definitions](https://github.com/KDE/syntax-highlighting/tree/master/data/syntax).
6336−
6337−To disable highlighting, use the `--no-highlight` option.
6338−
6339−[skylighting]: https://github.com/jgm/skylighting
6340−
6341−# Custom Styles
6342−
6343−Custom styles can be used in the docx and ICML formats.
6344−
6345−## Output
6346−
6347−By default, pandoc's docx and ICML output applies a predefined set of styles
6348−for blocks such as paragraphs and block quotes, and uses largely default
6349−formatting (italics, bold) for inlines. This will work for most
6350−purposes, especially alongside a `reference.docx` file. However, if you
6351−need to apply your own styles to blocks, or match a preexisting set of
6352−styles, pandoc allows you to define custom styles for blocks and text
6353−using `div`s and `span`s, respectively.
6354−
6355−If you define a `div` or `span` with the attribute `custom-style`,
6356−pandoc will apply your specified style to the contained elements (with
6357−the exception of elements whose function depends on a style, like
6358−headings, code blocks, block quotes, or links). So, for example, using
6359−the `bracketed_spans` syntax,
6360−
6361− [Get out]{custom-style="Emphatically"}, he said.
6362−
6363−would produce a docx file with "Get out" styled with character
6364−style `Emphatically`. Similarly, using the `fenced_divs` syntax,
6365−
6366− Dickinson starts the poem simply:
6367−
6368− ::: {custom-style="Poetry"}
6369− | A Bird came down the Walk---
6370− | He did not know I saw---
6371− :::
6372−
6373−would style the two contained lines with the `Poetry` paragraph style.
6374−
6375−For docx output, styles will be defined in the output file as inheriting
6376−from normal text, if the styles are not yet in your reference.docx.
6377−If they are already defined, pandoc will not alter the definition.
6378−
6379−This feature allows for greatest customization in conjunction with
6380−[pandoc filters]. If you want all paragraphs after block quotes to be
6381−indented, you can write a filter to apply the styles necessary. If you
6382−want all italics to be transformed to the `Emphasis` character style
6383−(perhaps to change their color), you can write a filter which will
6384−transform all italicized inlines to inlines within an `Emphasis`
6385−custom-style `span`.
6386−
6387−For docx output, you don't need to enable any extensions for
6388−custom styles to work.
6389−
6390−[pandoc filters]: https://pandoc.org/filters.html
6391−
6392−## Input
6393−
6394−The docx reader, by default, only reads those styles that it can
6395−convert into pandoc elements, either by direct conversion or
6396−interpreting the derivation of the input document's styles.
6397−
6398−By enabling the [`styles` extension](#ext-styles) in the docx reader
6399−(`-f docx+styles`), you can produce output that maintains the styles
6400−of the input document, using the `custom-style` class. Paragraph
6401−styles are interpreted as divs, while character styles are interpreted
6402−as spans.
6403−
6404−For example, using the `custom-style-reference.docx` file in the test
6405−directory, we have the following different outputs:
6406−
6407−Without the `+styles` extension:
6408−
6409− $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
6410− This is some text.
6411−
6412− This is text with an *emphasized* text style. And this is text with a
6413− **strengthened** text style.
6414−
6415− > Here is a styled paragraph that inherits from Block Text.
6416−
6417−And with the extension:
6418−
6419− $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
6420−
6421− ::: {custom-style="First Paragraph"}
6422− This is some text.
6423− :::
6424−
6425− ::: {custom-style="Body Text"}
6426− This is text with an [emphasized]{custom-style="Emphatic"} text style.
6427− And this is text with a [strengthened]{custom-style="Strengthened"}
6428− text style.
6429− :::
6430−
6431− ::: {custom-style="My Block Style"}
6432− > Here is a styled paragraph that inherits from Block Text.
6433− :::
6434−
6435−With these custom styles, you can use your input document as a
6436−reference-doc while creating docx output (see below), and maintain the
6437−same styles in your input and output files.
6438−
6439−# Custom writers
6440−
6441−Pandoc can be extended with custom writers written in [Lua]. (Pandoc
6442−includes a Lua interpreter, so Lua need not be installed separately.)
6443−
6444−To use a custom writer, simply specify the path to the Lua script
6445−in place of the output format. For example:
6446−
6447− pandoc -t data/sample.lua
6448−
6449−Creating a custom writer requires writing a Lua function for each
6450−possible element in a pandoc document. To get a documented example
6451−which you can modify according to your needs, do
6452−
6453− pandoc --print-default-data-file sample.lua
6454−
6455−Note that custom writers have no default template. If you want
6456−to use `--standalone` with a custom writer, you will need to
6457−specify a template manually using `--template` or add a new
6458−default template with the name
6459−`default.NAME_OF_CUSTOM_WRITER.lua` to the `templates`
6460−subdirectory of your user data directory (see [Templates]).
6461−
6462−[Lua]: https://www.lua.org
6463−
6464−# Reproducible builds
6465−
6466−Some of the document formats pandoc targets (such as EPUB,
6467−docx, and ODT) include build timestamps in the generated document.
6468−That means that the files generated on successive builds will
6469−differ, even if the source does not. To avoid this, set the
6470−`SOURCE_DATE_EPOCH` environment variable, and the timestamp will
6471−be taken from it instead of the current time.
6472−`SOURCE_DATE_EPOCH` should contain an integer unix timestamp
6473−(specifying the number of second since midnight UTC January 1, 1970).
6474−
6475−Some document formats also include a unique identifier. For
6476−EPUB, this can be set explicitly by setting the `identifier`
6477−metadata field (see [EPUB Metadata], above).
6478−
6479−# A note on security
6480−
6481−If you use pandoc to convert user-contributed content in a web
6482−application, here are some things to keep in mind:
6483−
6484−1. Although pandoc itself will not create or modify any files other
6485− than those you explicitly ask it create (with the exception
6486− of temporary files used in producing PDFs), a filter or custom
6487− writer could in principle do anything on your file system. Please
6488− audit filters and custom writers very carefully before using them.
6489−
6490−2. If your application uses pandoc as a Haskell library (rather than
6491− shelling out to the executable), it is possible to use it in a mode
6492− that fully isolates pandoc from your file system, by running the
6493− pandoc operations in the `PandocPure` monad. See the document
6494− [Using the pandoc API](https://pandoc.org/using-the-pandoc-api.html)
6495− for more details.
6496−
6497−3. Pandoc's parsers can exhibit pathological performance on some
6498− corner cases. It is wise to put any pandoc operations under
6499− a timeout, to avoid DOS attacks that exploit these issues.
6500− If you are using the pandoc executable, you can add the
6501− command line options `+RTS -M512M -RTS` (for example) to limit
6502− the heap size to 512MB.
6503−
6504−4. The HTML generated by pandoc is not guaranteed to be safe.
6505− If `raw_html` is enabled for the Markdown input, users can
6506− inject arbitrary HTML. Even if `raw_html` is disabled,
6507− users can include dangerous content in URLs and attributes.
6508− To be safe, you should run all the generated HTML through
6509− an HTML sanitizer.
6510−
6511−# Authors
6512−
6513−Copyright 2006--2021 John MacFarlane (jgm@berkeley.edu). Released
6514−under the [GPL], version 2 or greater. This software carries no
6515−warranty of any kind. (See COPYRIGHT for full copyright and
6516−warranty notices.) For a full list of contributors, see the file
6517−AUTHORS.md in the pandoc source code.
6518−
6519−[GPL]: https://www.gnu.org/copyleft/gpl.html "GNU General Public License"
6520−[YAML]: https://yaml.org/spec/1.2/spec.html "YAML v1.2 Spec"