@@ -1,6520 +0,0 @@
2−title: Pandoc User's Guide
3−author: John MacFarlane
9−`pandoc` [*options*] [*input-file*]...
13−Pandoc is a [Haskell] library for converting from one markup format to
14−another, and a command-line tool that uses this library.
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.
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].
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.
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.
45−If no *input-files* are specified, input is read from *stdin*.
46−Output goes to *stdout* by default. For output to a file,
49− pandoc -o output.html input.txt
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:
55− pandoc -s -o output.html input.txt
57−For more information on how standalone documents are produced, see
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
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:
71− pandoc -f markdown -t latex hello.txt
73−To convert `hello.html` from HTML to Markdown:
75− pandoc -f html -t markdown hello.html
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
83−If the input or output format is not specified explicitly, `pandoc`
84−will attempt to guess it from the extensions of the filenames.
87− pandoc -o hello.tex hello.txt
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.
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`]:
102− iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
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.
109−[`iconv`]: https://www.gnu.org/software/libiconv/
113−To produce a PDF, specify an output file with a `.pdf` extension:
115− pandoc test.txt -o test.pdf
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`.
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`.
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`.
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).
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
206−## Reading from the Web
208−Instead of an input file, an absolute URI may be given. In this case
209−pandoc will fetch the content using HTTP:
211− pandoc -f html -t markdown https://www.fsf.org
213−It is possible to supply a custom User-Agent string or other
214−header when requesting a document from a URL:
216− pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
221−## General options {.options}
223−`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
225−: Specify input format. *FORMAT* can be:
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])
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])
246− - `ipynb` ([Jupyter notebook])
247− - `jats` ([JATS] XML)
248− - `jira` ([Jira]/Confluence wiki markup)
249− - `json` (JSON version of native AST)
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])
258− - `native` (native Haskell)
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])
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`,
276−`-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
278−: Specify output format. *FORMAT* can be:
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)
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)
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])
320− - `native` (native Haskell),
321− - `odt` ([OpenOffice text document][ODT])
323− - `opendocument` ([OpenDocument])
324− - `org` ([Emacs Org mode])
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
343− Note that `odt`, `docx`, `epub`, and `pdf` output will not be directed
344− to *stdout* unless forced with `-o -`.
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.
351−`-o` *FILE*, `--output=`*FILE*
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.
357−`--data-dir=`*DIRECTORY*
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.
374−`-d` *FILE*, `--defaults=`*FILE*
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
390−: Generate a bash completion script. To enable bash completion
391− with pandoc, add this to your `.bashrc`:
393− eval "$(pandoc --bash-completion)"
397−: Give verbose debugging output.
401−: Suppress warning messages.
405−: Exit with error status if there are any warnings.
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`).
413−`--list-input-formats`
415−: List supported input formats, one per line.
417−`--list-output-formats`
419−: List supported output formats, one per line.
421−`--list-extensions`[`=`*FORMAT*]
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.
428−`--list-highlight-languages`
430−: List supported languages for syntax highlighting, one per
433−`--list-highlight-styles`
435−: List supported styles for syntax highlighting, one per line.
436− See `--highlight-style`.
444−: Show usage message.
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
504−## Reader options {.options}
506−`--shift-heading-level-by=`*NUMBER*
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.
523−`--base-header-level=`*NUMBER*
525−: *Deprecated. Use `--shift-heading-level-by`=X instead,
526− where X = NUMBER - 1.* Specify the base level for headings
529−`--strip-empty-paragraphs`
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.
536−`--indented-code-classes=`*CLASSES*
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.
542−`--default-image-extension=`*EXTENSION*
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.
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`.
557−`-F` *PROGRAM*, `--filter=`*PROGRAM*
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,
566− pandoc --filter ./caps.py -t latex
570− pandoc -t json | ./caps.py latex | pandoc -f json -t latex
572− The latter form may be useful for debugging filters.
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].
581− In order of preference, pandoc will look for filters in
583− 1. a specified full or relative path (executable or
586− 2. `$DATADIR/filters` (executable or non-executable)
587− where `$DATADIR` is the user data directory (see
588− `--data-dir`, above).
590− 3. `$PATH` (executable only)
592− Filters, Lua-filters, and citeproc processing are applied in
593− the order specified on the command line.
595−`-L` *SCRIPT*, `--lua-filter=`*SCRIPT*
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.
604− The `pandoc` Lua module provides helper functions for element
605− creation. It is always loaded into the script's Lua environment.
607− See the [Lua filters documentation] for further details.
609− In order of preference, pandoc will look for Lua filters in
611− 1. a specified full or relative path
613− 2. `$DATADIR/filters` where `$DATADIR` is the user data
614− directory (see `--data-dir`, above).
616− Filters, Lua filters, and citeproc processing are applied in
617− the order specified on the command line.
619−`-M` *KEY*[`=`*VAL*], `--metadata=`*KEY*[`:`*VAL*]
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.
632−`--metadata-file=`*FILE*
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.
645−`-p`, `--preserve-tabs`
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.
652−`--tab-stop=`*NUMBER*
654−: Specify the number of spaces per tab (default is 4).
656−`--track-changes=accept`|`reject`|`all`
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
673−`--extract-media=`*DIR*
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
685−`--abbreviations=`*FILE*
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
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.
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
704−## General writer options {.options}
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.
714−`--template=`*FILE*|*URL*
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`).
726−`-V` *KEY*[`=`*VAL*], `--variable=`*KEY*[`:`*VAL*]
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`.
732−`-D` *FORMAT*, `--print-default-template=`*FORMAT*
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.
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`.
746−`--print-default-data-file=`*FILE*
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.
753−`--eol=crlf`|`lf`|`native`
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
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.
769−`--wrap=auto`|`none`|`preserve`
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.
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).
789−`--toc`, `--table-of-contents`
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.
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`.
804−`--toc-depth=`*NUMBER*
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).
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.
820−: Disables syntax highlighting for code blocks and inlines, even when
821− a language attribute is given.
823−`--highlight-style=`*STYLE*|*FILE*
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`.
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
837− To generate the JSON version of an existing style,
838− use `--print-highlight-style`.
840−`--print-highlight-style=`*STYLE*|*FILE*
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.
849−`--syntax-definition=`*FILE*
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.
858−`-H` *FILE*, `--include-in-header=`*FILE*|*URL*
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`.
866−`-B` *FILE*, `--include-before-body=`*FILE*|*URL*
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`.
875−`-A` *FILE*, `--include-after-body=`*FILE*|*URL*
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`.
883−`--resource-path=`*SEARCHPATH*
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`.
900−`--request-header=`*NAME*`:`*VAL*
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://...`.
908−`--no-check-certificate`
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).
914−## Options affecting specific writers {.options}
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.
939−: Use `<q>` tags for quotes in HTML. (This option only has an
940− effect if the `smart` extension is enabled for the input
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.
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.
959−`--reference-location=block`|`section`|`document`
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.
966−`--markdown-headings=setext`|`atx`
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.
976−: *Deprecated synonym for `--markdown-headings=atx`.*
978−`--top-level-division=default`|`section`|`chapter`|`part`
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.
994−`-N`, `--number-sections`
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`
1001−`--number-offset=`*NUMBER*[`,`*NUMBER*`,`*...*]
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`.
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].
1019−`-i`, `--incremental`
1021−: Make list items in slide shows display incrementally (one by one).
1022− The default is for lists to be displayed all at once.
1024−`--slide-level=`*NUMBER*
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
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.
1043−`--email-obfuscation=none`|`javascript`|`references`
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
1051−`--id-prefix=`*STRING*
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.
1058−`-T` *STRING*, `--title-prefix=`*STRING*
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`.
1064−`-c` *URL*, `--css=`*URL*
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.
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.
1075−`--reference-doc=`*FILE*
1077−: Use the specified file as a style reference in producing a
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.
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:
1134− - Default Paragraph Font
1137− - Footnote Reference
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.
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.
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.
1167− The specific requirement is that the template should begin with
1168− the following first four layouts:
1171− 2. Title and Content
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.)
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).
1185−`--epub-cover-image=`*FILE*
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).
1192−`--epub-metadata=`*FILE*
1194−: Look in the specified XML file for metadata for the EPUB.
1195− The file should contain a series of [Dublin Core elements].
1198− <dc:rights>Creative Commons</dc:rights>
1199− <dc:language>es-AR</dc:language>
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.
1209− Note: if the source document is Markdown, a YAML metadata block
1210− in the document can be used instead. See below under
1213−`--epub-embed-font=`*FILE*
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`):
1224− font-family: DejaVuSans;
1225− font-style: normal;
1226− font-weight: normal;
1227− src:url("DejaVuSans-Regular.ttf");
1230− font-family: DejaVuSans;
1231− font-style: normal;
1233− src:url("DejaVuSans-Bold.ttf");
1236− font-family: DejaVuSans;
1237− font-style: italic;
1238− font-weight: normal;
1239− src:url("DejaVuSans-Oblique.ttf");
1242− font-family: DejaVuSans;
1243− font-style: italic;
1245− src:url("DejaVuSans-BoldOblique.ttf");
1247− body { font-family: "DejaVuSans"; }
1249−`--epub-chapter-level=`*NUMBER*
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
1259−`--epub-subdirectory=`*DIRNAME*
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.
1265−`--ipynb-output=all|none|best`
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`.
1274−`--pdf-engine=`*PROGRAM*
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`:
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`
1292−`--pdf-engine-opt=`*STRING*
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.
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
1304−## Citation rendering {.options}
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].
1325−`--bibliography=`*FILE*
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`).
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.
1345−`--citation-abbreviations=`*FILE*
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.
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`].
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`].
1369−## Math rendering in HTML {.options}
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.
1378−`--mathjax`[`=`*URL*]
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
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
1396−`--webtex`[`=`*URL*]
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.
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.
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.
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
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/
1430−## Options for wrapper scripts {.options}
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.
1445−: Ignore command-line arguments (for use in wrapper scripts).
1446− Regular pandoc options are not ignored. Thus, for example,
1448− pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
1452− pandoc -o foo.html -s
1456−If pandoc completes successfully, it will return exit code 0.
1457−Nonzero exit codes have the following meanings:
1460−----- ------------------------------------
1461− 3 PandocFailOnWarningError
1463− 5 PandocTemplateError
1464− 6 PandocOptionError
1465− 21 PandocUnknownReaderError
1466− 22 PandocUnknownWriterError
1467− 23 PandocUnsupportedExtensionError
1468− 24 PandocCiteprocError
1469− 31 PandocEpubSubdirectoryError
1472− 47 PandocPDFProgramNotFoundError
1474− 62 PandocShouldNeverHappenError
1476− 64 PandocParseError
1477− 65 PandocParsecError
1478− 66 PandocMakePDFError
1479− 67 PandocSyntaxMapError
1480− 83 PandocFilterError
1482− 92 PandocUTF8DecodingError
1483− 93 PandocIpynbDecodingError
1484− 94 PandocUnsupportedCharsetError
1485− 97 PandocCouldNotFindDataFileError
1486− 99 PandocResourceNotFound
1487−----- ------------------------------------
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:
1496−from: markdown+emoji
1497−# reader: may be used instead of from:
1499−# writer: may be used instead of to:
1501−# leave blank for output to stdout:
1503−# leave blank for input from stdin, use [] for no input:
1507−# or you may use input-file: with a single value
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.
1521−self-contained: false
1523−# note that structured variables may be specified:
1525− documentclass: book
1530−# metadata values specified here are parsed as literal
1531−# string text, not markdown:
1538−# or you may use metadata-file: with a single value
1540−# Note that these take files, not their contents:
1541−include-before-body: []
1542−include-after-body: []
1543−include-in-header: []
1544−resource-path: ["."]
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).
1555−citation-abbreviations: abbrevs.json
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}`.
1572−# ERROR, WARNING, or INFO
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
1581−# part, chapter, section, or default:
1582−top-level-division: chapter
1585−pdf-engine: pdflatex
1588−# you may also use pdf-engine-opt: with a single option
1589−# pdf-engine-opt: "-shell-escape"
1591−# auto, preserve, or none
1596−extract-media: mediadir
1598−table-of-contents: true
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
1606−identifier-prefix: foo
1608−strip-empty-paragraphs: true
1609−# lf, crlf, or native
1611−strip-comments: false
1612−indented-code-classes: []
1614−default-image-extension: ".jpg"
1616−# either a style name of a style definition file:
1617−highlight-style: pygments
1620−# or you may use syntax-definition: with a single value
1623−reference-doc: myref.docx
1625−# method is plain, webtex, gladtex, mathml, mathjax, katex
1626−# you may specify a url with webtex, mathjax, katex
1629− url: "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
1630−# none, references, or javascript
1631−email-obfuscation: javascript
1639−epub-subdirectory: EPUB
1640−epub-metadata: meta.xml
1643−epub-chapter-level: 1
1644−epub-cover-image: cover.jpg
1646−reference-links: true
1647−# block, section, or document
1648−reference-location: block
1649−markdown-headings: setext
1651−# accept, reject, or all
1652−track-changes: accept
1658−# none, all, or best
1661−# A list of two-element lists
1663−- ["User-Agent", "Mozilla/5.0"]
1665−fail-if-warnings: false
1671−Fields that are omitted will just have their regular
1672−default values. So a defaults file can be as simple as
1679−In fields that expect a file path (or list of file paths), the
1680−following syntax may be used to interpolate environment variables:
1683−csl: ${HOME}/mycsldir/special.csl
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`.
1691−`${.}` will resolve to the directory containing the default
1692−file itself. This allows you to refer to resources contained
1696−epub-cover-image: ${.}/cover.jpg
1697−epub-metadata: ${.}/meta.xml
1699−- . # the working directory from which pandoc is run
1700−- ${.}/images # the images subdirectory of the directory
1701− # containing this defaults file
1704−This environment variable interpolation syntax *only* works in
1705−fields that expect file paths.
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`.
1715−When multiple defaults are used, their contents will be combined.
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.
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
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:*
1738−- For `odt` output, customize the `default.opendocument`
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).
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.
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.
1762− [pandoc-templates]: https://github.com/jgm/pandoc-templates
1768−Anything between the sequence `$--` and the end of the
1769−line will be treated as a comment and omitted from the output.
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
1782−To include a literal `$` in the document, use `$$`.
1784−### Interpolated variables
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:
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.
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.
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:
1838−${if(foo)}bar${endif}
1851−The keyword `elseif` may be used to simplify complex nested
1866−A for loop begins with `for(variable)` (enclosed in
1867−matched delimiters) and ends with `endfor` (enclosed in matched
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
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.
1881−$for(foo)$$foo$$sep$, $endfor$
1884− - $foo.last$, $foo.first$
1888− - ${ foo.bar.last }, ${ foo.bar.first }
1892−$it.name$: $it.office$
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.
1901−${ for(foo) }${ foo }${ sep }, ${ endfor }
1904−Instead of using `variable` inside the loop, the special
1905−anaphoric keyword `it` may be used.
1909− - ${ it.last }, ${ it.first }
1915−Partials (subtemplates stored in different files) may be
1916−included by using the name of the partial, followed
1917−by `()`, for example:
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:
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.)
1938−Partials may optionally be applied to variables using
1944−${ articles:bibentry() }
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
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`.
1962−Final newlines are omitted from included partials.
1964−Partials may include other partials.
1966−A separator between values of an array may be specified
1967−in square brackets, immediately after the variable name
1973−${articles:bibentry()[; ]$
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.
1982−To ensure that content is "nested," that is, subsequent lines
1983−indented, use the `^` directive:
1986−$item.number$ $^$$item.description$ ($item.price$)
1989−In this example, if `item.description` has multiple lines,
1990−they will all be indented to line up with the first line:
1993−00123 A fine bottle of 18-year old
1994− Oban whiskey. ($148)
1997−To nest multiple lines to the same level, align them
1998−with the `^` directive in the template. For example:
2001−$item.number$ $^$$item.description$ ($item.price$)
2002− (Available til $item.sellby$.)
2008−00123 A fine bottle of 18-year old
2009− Oban whiskey. ($148)
2010− (Available til March 30, 2020.)
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.
2018−### Breakable spaces
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 `~`).
2026−$~$This long line may break if the document is rendered
2027−with a short line length.$~$
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:
2041−$for(metadata/pairs)$
2042−- $it.key$: $it.value$
2045−$employee:name()/uppercase$
2048−Pipes may be chained:
2051−$for(employees/pairs)$
2052−$it.key/alpha/uppercase$. $it.name$
2056−Some pipes take parameters:
2059−|----------------------|------------|
2061−$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
2063−|----------------------|------------|
2066−Currently the following pipes are predefined:
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,
2073−- `uppercase`: Converts text to uppercase.
2075−- `lowercase`: Converts text to lowercase.
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.
2081−- `reverse`: Reverses a textual value or array,
2082− and has no effect on other values.
2084−- `first`: Returns the first value of an array, if
2085− applied to a non-empty array; otherwise returns
2086− the original value.
2088−- `last`: Returns the last value of an array, if
2089− applied to a non-empty array; otherwise returns
2090− the original value.
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.
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.
2100−- `chomp`: Removes trailing newlines (and breakable space).
2102−- `nowrap`: Disables line wrapping on breakable spaces.
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`.
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`.
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.
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.
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.
2134−### Metadata variables
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`]:
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.
2157−: document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and docx
2161−: document summary, included in LaTeX, ConTeXt, AsciiDoc, and docx
2165−: list of keywords to be included in HTML, PDF, ODT, pptx, docx
2166− and AsciiDoc metadata; repeat as for `author`, above
2169−: document subject, included in ODT, PDF, docx and pptx metadata
2172−: document description, included in ODT, docx and pptx metadata. Some
2173− applications show this as `Comments` metadata.
2176−: document category, included in docx and pptx metadata
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:
2184− title: 'This is the title'
2185− subtitle: "This is the subtitle"
2193− It consists of two paragraphs
2196−will include `title`, `author` and `description` as standard document
2197−properties and `subtitle` as a custom property when converting to docx,
2200−### Language variables
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.
2209− Use native pandoc [Divs and Spans] with the `lang` attribute to
2210− switch the language:
2216− Text in the main document language (British English).
2219− > Cette citation est écrite en français canadien.
2222− More text in English. ['Zitat auf Deutsch.']{lang=de}
2225−: the base script direction, either `rtl` (right-to-left)
2226− or `ltr` (left-to-right).
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].
2235− When using LaTeX for bidirectional documents, only the
2236− `xelatex` engine is fully supported (use
2237− `--pdf-engine=xelatex`).
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/
2243−### Variables for HTML
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`.
2254−: sets the CSS `font-family` property on the `html` element.
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).
2262−: sets the CSS `color` property on the `html` element.
2265−: sets the CSS `color` property on all links.
2268−: sets the CSS `font-family` property on `code` elements.
2270−`monobackgroundcolor`
2271−: sets the CSS `background-color` property on `code` elements
2272− and adds extra padding.
2275−: sets the CSS `line-height` property on the `html` element,
2276− which is preferred to be unitless.
2279−: sets the CSS `background-color` property on the `html` element.
2281−`margin-left`, `margin-right`, `margin-top`, `margin-bottom`
2282−: sets the corresponding CSS `padding` properties on the `body` element.
2284−To override or extend some [CSS] for just one document, include for example:
2290− font-style: italic;
2293− background-color: #f0f0f0;
2296− padding: 0.5em 2em 0.5em 0.5em;
2299− border-bottom: none;
2304−[CSS]: https://developer.mozilla.org/en-US/docs/Learn/CSS
2306−### Variables for HTML math
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`.
2313−### Variables for HTML slides
2315−These affect HTML output when [producing slide shows with pandoc].
2318−: author affiliations: can be a list when there are multiple authors
2321−: base URL for reveal.js documents (defaults to
2322− `https://unpkg.com/reveal.js@^4/`)
2325−: base URL for S5 documents (defaults to `s5/default`)
2328−: base URL for Slidy documents (defaults to
2329− `https://www.w3.org/Talks/Tools/Slidy2`)
2332−: base URL for Slideous documents (defaults to `slideous`)
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.
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`.
2341−[reveal.js configuration options]: https://revealjs.com/config/
2343−### Variables for Beamer slides
2345−These variables change the appearance of PDF slides using [`beamer`].
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,
2353−: produce an article from Beamer slides
2356−: add extra beamer option with `\setbeameroption{}`
2359−: author affiliations: can be a list when there are multiple authors
2362−: logo image for slides
2365−: controls navigation symbols (default is `empty` for no navigation
2366− symbols; other valid values are `frame`, `vertical`, and `horizontal`)
2369−: enables "title pages" for new sections (default is true)
2371−`theme`, `colortheme`, `fonttheme`, `innertheme`, `outertheme`
2375−: options for LaTeX beamer themes (a list).
2378−: image for title slide
2380−### Variables for PowerPoint
2382−These variables control the visual aspects of a slide show that
2383−are not easily controlled via templates.
2386−: font to use for code.
2388−### Variables for LaTeX
2390−Pandoc uses these variables when [creating a PDF] with a LaTeX engine.
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:
2403− documentclass: scrartcl
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}
2417−: option for document class, e.g. `oneside`; repeat for multiple options:
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`]
2432−: option for [`geometry`] package, e.g. `margin=1in`;
2433− repeat for multiple options:
2443−: option for [`hyperref`] package, e.g. `linktoc=all`;
2444− repeat for multiple options:
2450− - pdfpagemode=FullScreen
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)
2459−: adjusts line spacing using the [`setspace`]
2460− package, e.g. `1.25`, `1.5`
2462−`margin-left`, `margin-right`, `margin-top`, `margin-bottom`
2463−: sets margins if `geometry` is not used (otherwise `geometry`
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)
2472−: paper size, e.g. `letter`, `a4`
2475−: numbering depth for sections (with `--number-sections` option
2476− or `numbersections` variable)
2481−: allows font encoding to be specified through `fontenc` package (with
2482− `pdflatex`); default is `T1` (see [LaTeX font encodings guide])
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`].
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:
2495− fontfamily: libertinus
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`.
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.
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:
2519− mainfont: TeX Gyre Pagella
2521− - Numbers=Lowercase
2522− - Numbers=Proportional
2526−: options to pass to the microtype package
2531−: add color to link text; automatically enabled if any of
2532− `linkcolor`, `filecolor`, `citecolor`, `urlcolor`, or `toccolor` are set
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
2541−: causes links to be printed as footnotes
2546−: include list of figures, list of tables
2549−: contents of acknowledgments footnote after document title
2552−: include table of contents (can also be set using
2553− `--toc/--table-of-contents`)
2556−: level of section to include in table of contents
2558−#### BibLaTeX Bibliographies
2560−These variables function when using BibLaTeX for [citation rendering].
2563−: list of options for biblatex
2566−: bibliography style, when used with `--natbib` and `--biblatex`.
2569−: bibliography title, when used with `--natbib` and `--biblatex`.
2572−: bibliography to use for resolving references
2575−: list of options for natbib
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
2587−### Variables for ConTeXt
2589−Pandoc uses these variables when [creating a PDF] with ConTeXt.
2592−: font size for body text (e.g. `10pt`, `12pt`)
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
2599−: controls indentation of paragraphs, e.g. `yes,small,next` (see
2600− [ConTeXt Indentation]); repeat for multiple options
2603−: adjusts line spacing, e.g. `4ex` (using [`setupinterlinespace`]);
2604− repeat for multiple options
2607−: options for page margins and text arrangement (see [ConTeXt Layout]);
2608− repeat for multiple options
2610−`linkcolor`, `contrastcolor`
2611−: color for links outside and inside a page, e.g. `red`, `blue` (see
2615−: typeface style for links, e.g. `normal`, `bold`, `slanted`, `boldslanted`,
2616− `type`, `cap`, `small`
2619−: include list of figures, list of tables
2621−`mainfont`, `sansfont`, `monofont`, `mathfont`
2622−: font families: take the name of any system font (see
2623− [ConTeXt Font Switching])
2625−`margin-left`, `margin-right`, `margin-top`, `margin-bottom`
2626−: sets margins, if `layout` is not used (otherwise `layout`
2630−: page number style and location (using [`setuppagenumbering`]);
2631− repeat for multiple options
2634−: paper size, e.g. `letter`, `A4`, `landscape` (see [ConTeXt Paper Setup]);
2635− repeat for multiple options
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.
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].
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.
2664−: include table of contents (can also be set using
2665− `--toc/--table-of-contents`)
2668−: spacing between paragraphs, e.g. `none`, `small` (using
2669− [`setupwhitespace`])
2672−: include all source documents as file attachments in the PDF file
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
2686−### Variables for `wkhtmltopdf`
2688−Pandoc uses these variables when [creating a PDF] with [`wkhtmltopdf`].
2689−The `--css` option also affects the output.
2691−`footer-html`, `header-html`
2692−: add information to the header and footer
2694−`margin-left`, `margin-right`, `margin-top`, `margin-bottom`
2695−: set the page margins
2698−: sets the PDF paper size
2700−### Variables for man pages
2703−: adjusts text to left (`l`), right (`r`), center (`c`),
2704− or both (`b`) margins
2707−: footer in man pages
2710−: header in man pages
2713−: if `true` (the default), hyphenation will be used
2716−: section number in man pages
2718−### Variables for ms
2721−: font family (e.g. `T` or `P`)
2724−: paragraph indent (e.g. `2m`)
2727−: line height (e.g. `12p`)
2730−: point size (e.g. `10p`)
2732−### Variables set automatically
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:
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`).
2752−: contents specified by `-H/--include-in-header` (may have multiple
2756−: contents specified by `-B/--include-before-body` (may have
2760−: contents specified by `-A/--include-after-body` (may have
2764−: JSON representation of all of the document's metadata. Field
2765− values are transformed to the selected output format.
2768−: non-null value if `-N/--number-sections` was specified
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:
2784− Similarly, `outputfile` can be `-` if output goes to the terminal.
2786− If you need absolute paths, use e.g. `$curdir$/$sourcefile$`.
2789−: working directory from which pandoc is run.
2792−: non-null value if `--toc/--table-of-contents` was specified
2795−: title of table of contents (works only with EPUB,
2796− HTML, opendocument, odt, docx, pptx, beamer, LaTeX)
2798−[pandoc-templates]: https://github.com/jgm/pandoc-templates
2802−The behavior of some of the readers and writers can be adjusted by
2803−enabling or disabling various extensions.
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.
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.
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`).
2823−#### Extension: `smart` ####
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."
2829−This extension can be enabled/disabled for the following formats:
2832−: `markdown`, `commonmark`, `latex`, `mediawiki`, `org`, `rst`, `twiki`
2835−: `markdown`, `latex`, `context`, `rst`
2837−enabled by default in
2838−: `markdown`, `latex`, `context` (both input and output)
2840−Note: If you are *writing* Markdown, then the `smart` extension
2841−has the reverse effect: what would have been curly quotes comes
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.
2853−## Headings and sections
2855−#### Extension: `auto_identifiers` ####
2857−A heading without an explicitly specified identifier will be
2858−automatically assigned a unique identifier based on the heading text.
2860−This extension can be enabled/disabled for the following formats:
2863−: `markdown`, `latex`, `rst`, `mediawiki`, `textile`
2866−: `markdown`, `muse`
2868−enabled by default in
2869−: `markdown`, `muse`
2871−The default algorithm used to derive the identifier from the
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`.
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`
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.
2901−(However, a different algorithm is used if
2902−`gfm_auto_identifiers` is enabled; see below.)
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:
2910− [heading identifiers](#heading-identifiers-in-html-latex-and-context).
2912−Note, however, that this method of providing links to sections works
2913−only in HTML, LaTeX, and ConTeXt formats.
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
2922−#### Extension: `ascii_identifiers` ####
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.
2928−#### Extension: `gfm_auto_identifiers` ####
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.
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.
2943−However, they can also be used with HTML input. This is handy for
2944−reading web pages formatted using MathJax, for example.
2948−The following extensions are described in more detail in
2949−their respective sections of [Pandoc's Markdown]:
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.
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`):
2960− : `latex`, `textile`, `html` (environments, `\ref`, and
2961− `\eqref` only), `ipynb`
2964− : `textile`, `commonmark`
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`.
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`.
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`.
2986−## Literate Haskell support
2988−#### Extension: `literate_haskell` ####
2990−Treat the document as literate Haskell source.
2992−This extension can be enabled/disabled for the following formats:
2995−: `markdown`, `rst`, `latex`
2998−: `markdown`, `rst`, `latex`, `html`
3000−If you append `+lhs` (or `+literate_haskell`) to one of the formats
3001−above, pandoc will treat the document as literate Haskell source.
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 '#'.
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.)
3016− - In restructured text input, "bird track" sections will be parsed
3019− - In restructured text output, code blocks with class `haskell` will
3020− be rendered using bird tracks.
3022− - In LaTeX input, text in `code` environments will be parsed as
3025− - In LaTeX output, code blocks with class `haskell` will be rendered
3026− inside `code` environments.
3028− - In HTML output, code blocks with class `haskell` will be rendered
3029− with class `literatehaskell` and bird tracks.
3033− pandoc -f markdown+lhs -t html
3035−reads literate Haskell source formatted with Markdown conventions and writes
3036−ordinary HTML (without bird tracks).
3038− pandoc -f markdown+lhs -t html+lhs
3040−writes HTML with the Haskell code in bird tracks, so it can be copied
3041−and pasted as literate Haskell source.
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.
3049−#### Extension: `empty_paragraphs` ####
3051−Allows empty paragraphs. By default empty paragraphs are
3054−This extension can be enabled/disabled for the following formats:
3060−: `docx`, `odt`, `opendocument`, `html`
3062−#### Extension: `native_numbering` ####
3064−Enables native numbering of figures and tables. Enumeration
3067−This extension can be enabled/disabled for the following formats:
3070−: `odt`, `opendocument`
3072−#### Extension: `xrefs_name` ####
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
3081−Text in cross-references is only made consistent with the referenced
3082−item once the document has been refreshed.
3084−This extension can be enabled/disabled for the following formats:
3087−: `odt`, `opendocument`
3089−#### Extension: `xrefs_number` ####
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.
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.
3101−Numbers in cross-references are only visible in the final document once
3102−it has been refreshed.
3104−This extension can be enabled/disabled for the following formats:
3107−: `odt`, `opendocument`
3109−#### Extension: `styles` #### {#ext-styles}
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.
3120−#### Extension: `amuse` ####
3122−In the `muse` input format, this enables Text::Amuse
3123−extensions to Emacs Muse markup.
3125−#### Extension: `raw_markdown` ####
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
3133−#### Extension: `citations` {#org-citations}
3135−Some aspects of [Pandoc's Markdown citation syntax](#citations)
3136−are also accepted in `org` input.
3138−#### Extension: `element_citations` ####
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.
3145−#### Extension: `ntb` ####
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.
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.
3166−Markdown is designed to be easy to write, and, even more importantly,
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
3172−> -- [John Gruber](https://daringfireball.net/projects/markdown/syntax#philosophy)
3174−This principle has guided pandoc's decisions in finding syntax for
3175−tables, footnotes, and other extensions.
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
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.
3191−#### Extension: `escaped_line_breaks` ####
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
3200−There are two kinds of headings: Setext and ATX.
3202−### Setext-style headings ###
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):
3207− A level-one heading
3208− ===================
3210− A level-two heading
3211− -------------------
3213−The heading text can contain inline formatting, such as emphasis (see
3214−[Inline formatting], below).
3217−### ATX-style headings ###
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:
3223− ## A level-two heading
3225− ### A level-three heading ###
3227−As with setext-style headings, the heading text can contain formatting:
3229− # A level-one heading with a [link](/url) and *emphasis*
3231−#### Extension: `blank_before_header` ####
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:
3239− I like several of their flavors of ice cream:
3240− #22, for example, and #5.
3242−#### Extension: `space_in_atx_header` ####
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.
3249−### Heading identifiers ###
3251−See also the [`auto_identifiers`
3252−extension](#extension-auto_identifiers) above.
3254−#### Extension: `header_attributes` ####
3256−Headings can be assigned attributes using this syntax at the end
3257−of the line containing the heading text:
3259− {#identifier .class .class key=value key=value}
3261−Thus, for example, the following headings will all be assigned the identifier
3264− # My heading {#foo}
3266− ## My heading ## {#foo}
3268− My other heading {#foo}
3271−(This syntax is compatible with [PHP Markdown Extra].)
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.
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
3288− # My heading {.unnumbered}
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.)
3295−#### Extension: `implicit_header_references` ####
3297−Pandoc behaves as if reference links have been defined for each heading.
3298−So, to link to a heading
3300− # Heading identifiers in HTML
3302−you can simply write
3304− [Heading identifiers in HTML]
3308− [Heading identifiers in HTML][]
3312− [the section on heading identifiers][heading identifiers in
3315−instead of giving the identifier explicitly:
3317− [Heading identifiers in HTML](#heading-identifiers-in-html)
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.
3323−Like regular reference links, these references are case-insensitive.
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`:
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.)
3343− > This is a block quote. This
3344− > paragraph has two lines.
3346− > 1. This is a list inside a block quote.
3349−A "lazy" form, which requires the `>` character only on the first
3350−line of each block, is also allowed:
3352− > This is a block quote. This
3353− paragraph has two lines.
3355− > 1. This is a list inside a block quote.
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:
3361− > This is a block quote.
3363− > > A block quote within a block quote.
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 `>`:
3372−#### Extension: `blank_before_blockquote` ####
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:
3382− > This is a block quote.
3386−## Verbatim (code) blocks
3388−### Indented code blocks ###
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,
3395− moveShip(5 * gravity, DOWN);
3398−The initial (four space or one tab) indentation is not considered part
3399−of the verbatim text, and is removed in the output.
3401−Note: blank lines in the verbatim text need not begin with four spaces.
3404−### Fenced code blocks ###
3406−#### Extension: `fenced_code_blocks` ####
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:
3416− moveShip(5 * gravity, DOWN);
3420−Like regular code blocks, fenced code blocks must be separated
3421−from surrounding text by blank lines.
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:
3428− code including tildes
3432−#### Extension: `backtick_code_blocks` ####
3434−Same as `fenced_code_blocks`, but uses backticks (`` ` ``) instead of tildes
3437−#### Extension: `fenced_code_attributes` ####
3439−Optionally, you may attach attributes to fenced or backtick code block using
3442− ~~~~ {#mycode .haskell .numberLines startFrom="100"}
3444− qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
3445− qsort (filter (>= x) xs)
3446− ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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:
3459− <pre id="mycode" class="haskell numberLines" startFrom="100">
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.
3471−A shortcut form can also be used for specifying the language of
3478−This is equivalent to:
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
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],
3496−#### Extension: `line_blocks` ####
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:
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
3510− | Berkeley, CA 94718
3512−The lines can be hard-wrapped if needed, but the continuation
3513−line must begin with a space.
3515− | The Right Honorable Most Venerable and Righteous Samuel L.
3518− | Berkeley, CA 94718
3520−Inline formatting (such as emphasis) is allowed in the content,
3521−but not block-level formatting (such as block quotes or lists).
3523−This syntax is borrowed from [reStructuredText].
3527−### Bullet lists ###
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
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:
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
3550−List items look best if subsequent lines are flush with the first
3551−line (after the bullet):
3557−But Markdown also allows a "lazy" format:
3563−### Block content in list items ###
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
3574− * Second paragraph. With a code block, which must be indented
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:
3586− continuation paragraph
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.
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.
3607− + A lazy, lazy, list
3610− + Another one; this looks
3613− Second paragraph of second
3616−### Ordered lists ###
3618−Ordered lists work just like bulleted lists, except that the items
3619−begin with enumerators rather than bullets.
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:
3635−#### Extension: `fancy_lists` ####
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]
3644−[^2]: The point of this rule is to ensure that normal paragraphs
3645− starting with people's initials, like
3647− B. Russell was an English philosopher.
3649− do not get treated as list items.
3651− This rule will not prevent
3655− from being interpreted as a list item. In this case, a backslash
3656− escape can be used:
3658− (C\) 2007 Joe Smith
3660−The `fancy_lists` extension also allows '`#`' to be used as an
3661−ordered list marker in place of a numeral:
3666−#### Extension: `startnum` ####
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
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:
3689−If default list markers are desired, use `#.`:
3695−#### Extension: `task_lists` ####
3697−Pandoc supports task lists, using the syntax of GitHub-Flavored Markdown.
3699− - [ ] an unchecked task list item
3702−### Definition lists ###
3704−#### Extension: `definition_lists` ####
3706−Pandoc supports definition lists, using the syntax of
3707−[PHP Markdown Extra] with some extensions.[^3]
3713− Term 2 with *inline markup*
3717− { some code, part of Definition 2 }
3719− Third paragraph of definition 2.
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
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:
3737− with lazy continuation.
3739− Second paragraph of the definition.
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
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.)
3759−[^3]: I have been influenced by the suggestions of [David
3760− Wheeler](https://justatheory.com/2009/02/modest-markdown-proposal/).
3762−### Numbered example lists ###
3764−#### Extension: `example_lists` ####
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:
3772− (@) My first example will be numbered (1).
3773− (@) My second example will be numbered (2).
3775− Explanation of examples.
3777− (@) My third example will be numbered (3).
3779−Numbered examples can be labeled and referred to elsewhere in the
3782− (@good) This is a good example.
3784− As (@good) illustrates, ...
3786−The label can be any string of alphanumeric characters, underscores,
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.
3797−### Ending a list ###
3799−What if you want to put an indented code block after a list?
3806−Trouble! Here pandoc (like other Markdown implementations) will treat
3807−`{ my code block }` as the second paragraph of item two, and not as
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
3817− <!-- end of list -->
3821−You can use the same trick if you want two consecutive lists instead
3836−A line containing a row of three or more `*`, `-`, or `_` characters
3837−(optionally separated by spaces) produces a horizontal rule:
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.
3850−#### Extension: `table_captions` ####
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.
3857−#### Extension: `simple_tables` ####
3859−Simple tables look like this:
3861− Right Left Center Default
3862− ------- ------ ---------- -------
3867− Table: Demonstration of simple table syntax.
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]
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).
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).
3885−The table must end with a blank line, or a line of dashes followed by
3888−The column header row may be omitted, provided a dashed line is used
3889−to end the table. For example:
3891− ------- ------ ---------- -------
3895− ------- ------ ---------- -------
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.
3901−#### Extension: `multiline_tables` ####
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:
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.
3914− Second row 5.0 Here's another one. Note
3915− the blank line between
3917− -------------------------------------------------------------
3919− Table: Here's the caption. It, too, may span
3922−These work like simple tables, but with the following differences:
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.
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.
3934−The header may be omitted in multiline tables as well as simple tables:
3936− ----------- ------- --------------- -------------------------
3937− First row 12.0 Example of a row that
3938− spans multiple lines.
3940− Second row 5.0 Here's another one. Note
3941− the blank line between
3943− ----------- ------- --------------- -------------------------
3945− : Here's a multiline table without a header.
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.
3951−#### Extension: `grid_tables` ####
3953−Grid tables look like this:
3955− : Sample grid table.
3957− +---------------+---------------+--------------------+
3958− | Fruit | Price | Advantages |
3959− +===============+===============+====================+
3960− | Bananas | $1.34 | - built-in wrapper |
3961− | | | - bright color |
3962− +---------------+---------------+--------------------+
3963− | Oranges | $2.10 | - cures scurvy |
3965− +---------------+---------------+--------------------+
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`).
3974−Alignments can be specified as with pipe tables, by putting
3975−colons at the boundaries of the separator line after the
3978− +---------------+---------------+--------------------+
3979− | Right | Left | Centered |
3980− +==============:+:==============+:==================:+
3981− | Bananas | $1.34 | built-in wrapper |
3982− +---------------+---------------+--------------------+
3984−For headerless tables, the colons go on the top line instead:
3986− +--------------:+:--------------+:------------------:+
3987− | Right | Left | Centered |
3988− +---------------+---------------+--------------------+
3990−##### Grid Table Limitations #####
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
4000−[sample grid tables]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables
4003−#### Extension: `pipe_tables` ####
4005−Pipe tables look like this:
4007− | Right | Left | Default | Center |
4008− |------:|:-----|---------|:------:|
4009− | 12 | 12 | 12 | 12 |
4010− | 123 | 123 | 123 | 123 |
4013− : Demonstration of pipe table syntax.
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
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:
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
4043−Note: pandoc also recognizes pipe tables of the following
4044−form, as can be produced by Emacs' orgtbl-mode:
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.
4055−[PHP Markdown Extra tables]: https://michelf.ca/projects/php-markdown/extra/#table
4059−#### Extension: `pandoc_title_block` ####
4061−If the file begins with a title block
4064− % author(s) (separated by semicolons)
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:
4084−The title may occupy multiple lines, but continuation lines must
4085−begin with leading space, thus:
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:
4102−% Author One; Author Two
4110−The date must fit on one line.
4112−All three metadata fields may contain standard inline formatting
4113−(italics, links, footnotes, etc.).
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.
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
4137−will yield a man page with the title `PANDOC` and section 1.
4139− % PANDOC(1) Pandoc User Manuals
4141−will also have "Pandoc User Manuals" in the footer.
4143− % PANDOC(1) Pandoc User Manuals | Version 4.0
4145−will also have "Version 4.0" in the header.
4147−#### Extension: `yaml_metadata_block` ####
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:
4157− pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html
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.
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).
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.
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.
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:
4190− title: 'This is the title: it contains a colon'
4194− keywords: [nothing, nothingness]
4196− This is the abstract.
4198− It consists of two paragraphs.
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
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:
4211− <p>This is the abstract.</p>
4212− <p>It consists of two paragraphs.</p>
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:
4221− title: The document title
4224− affiliation: University of Somewhere
4226− affiliation: University of Nowhere
4229−To use the structured authors in the example above, you would need a custom
4234− $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
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:
4249− \let\oldsection\section
4250− \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
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:
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
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.
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
4271−## Backslash escapes
4273−#### Extension: `all_symbols_escapable` ####
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
4287− <strong>hello</strong>
4289−This rule is easier to remember than standard Markdown's rule,
4290−which allows only the following characters to be backslash-escaped:
4294−(However, if the `markdown_strict` format is used, the standard Markdown rule
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
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.
4310−Backslash escapes do not work in verbatim contexts.
4312−## Inline formatting
4316−To *emphasize* some text, surround it with `*`s or `_`, like this:
4318− This text is _emphasized with underscores_, and this
4319− is *emphasized with asterisks*.
4321−Double `*` or `_` produces **strong emphasis**:
4323− This is **strong emphasis** and __with underscores__.
4325−A `*` or `_` character surrounded by spaces, or backslash-escaped,
4326−will not trigger emphasis:
4328− This is * not emphasized *, and \*neither is this\*.
4330−#### Extension: `intraword_underscores` ####
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 `*`:
4337− feas*ible*, not feas*able*.
4342−#### Extension: `strikeout` ####
4344−To strikeout a section of text with a horizontal line, begin and end it
4345−with `~~`. Thus, for example,
4347− This ~~is deleted text.~~
4350−### Superscripts and subscripts ###
4352−#### Extension: `superscript`, `subscript` ####
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,
4358− H~2~O is a liquid. 2^10^ is 1024.
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~`.
4370−To make a short span of text verbatim, put it inside backticks:
4372− What is the difference between `>>=` and `>>`?
4374−If the verbatim text includes a backtick, use double backticks:
4376− Here is a literal backtick `` ` ``.
4378−(The spaces after the opening backticks and before the closing
4379−backticks will be ignored.)
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).
4386−Note that backslash-escapes (and other Markdown constructs) do not
4387−work in verbatim contexts:
4389− This is a backslash followed by an asterisk: `\*`.
4391−#### Extension: `inline_code_attributes` ####
4393−Attributes can be attached to verbatim text, just as with
4394−[fenced code blocks]:
4400−To write small caps, use the `smallcaps` class:
4402− [Small caps]{.smallcaps}
4404−Or, without the `bracketed_spans` extension:
4406− <span class="smallcaps">Small caps</span>
4408−For compatibility with other Markdown flavors, CSS is also supported:
4410− <span style="font-variant:small-caps;">Small caps</span>
4412−This will work in all output formats that support small caps.
4417−#### Extension: `tex_math_dollars` ####
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.
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.)
4431−TeX math will be printed in all output formats. How it is rendered
4432−depends on the output format:
4435− ~ It will appear verbatim surrounded by `\(...\)` (for inline
4436− math) or `\[...\]` (for display math).
4438−Markdown, Emacs Org mode, ConTeXt, ZimWiki
4439− ~ It will appear verbatim surrounded by `$...$` (for inline
4440− math) or `$$...$$` (for display math).
4443− ~ It will appear verbatim surrounded by `{{formula}}..{{/formula}}`.
4446− ~ It will be rendered using an [interpreted text role `:math:`].
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.
4456− ~ It will be rendered inside a `@math` command.
4458−roff man, Jira markup
4459− ~ It will be rendered verbatim without `$`'s.
4462− ~ It will be rendered inside `<math>` tags.
4465− ~ It will be rendered inside `<span class="math">` tags.
4468− ~ It will be rendered, if possible, using Unicode characters,
4469− and will otherwise appear verbatim.
4472− ~ It will be rendered, if possible, using MathML.
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.
4480− ~ It will be rendered using OMML math markup.
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.
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]
4492−[interpreted text role `:math:`]: https://docutils.sourceforge.io/docs/ref/rst/roles.html#math
4496−#### Extension: `raw_html` ####
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.)
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.
4508−For a more explicit way of including raw HTML in a Markdown
4509−document, see the [`raw_attribute` extension][Extension: `raw_attribute`].
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.
4517−#### Extension: `markdown_in_html_blocks` ####
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.
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
4532− <td>[a link](https://google.com)</td>
4540− <td><em>one</em></td>
4541− <td><a href="https://google.com">a link</a></td>
4545−whereas `Markdown.pl` will preserve it as is.
4547−There is one exception to this rule: text between `<script>`,
4548−`<style>`, and `<textarea>` tags is not interpreted as Markdown.
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.
4555−#### Extension: `native_divs` ####
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.
4562−#### Extension: `native_spans` ####
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
4569−#### Extension: `raw_tex` ####
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:
4576− This result was proved in \cite{jones.1967}.
4578−Note that in LaTeX environments, like
4580− \begin{tabular}{|l|l|}\hline
4581− Age & Frequency \\ \hline
4584− 36--45 & 22 \\ \hline
4587−the material between the begin and end tags will be interpreted as raw
4588−LaTeX, not as Markdown.
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`].
4594−Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
4595−Emacs Org mode, and ConTeXt.
4597−### Generic raw attribute ###
4599−#### Extension: `raw_attribute` ####
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
4610−And the following produces a raw `html` inline element:
4612− This is `<a>html</a>`{=html}
4614−This can be useful to insert raw xml into `docx` documents, e.g.
4620− <w:br w:type="page"/>
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`).
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.
4638−The raw attribute cannot be combined with regular attributes.
4642−#### Extension: `latex_macros` ####
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:
4649− \newcommand{\tuple}[1]{\langle #1 \rangle}
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).
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.
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
4669−Markdown allows links to be specified in several ways.
4671−### Automatic links ###
4673−If you enclose a URL or email address in pointy brackets, it
4676− <https://google.com>
4677− <sam@green.eggs.ham>
4679−### Inline links ###
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.)
4685− This is an [inline link](/url), and here's [one with
4686− a title](https://fsf.org "click here for a good time!").
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.
4691−Email addresses in inline links are not autodetected, so they have to be
4692−prefixed with `mailto`:
4694− [Write me!](mailto:sam@green.eggs.ham)
4696−### Reference links ###
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).
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
4711−Here are some examples:
4713− [my label 1]: /foo/bar.html "My title, optional"
4715− [my label 3]: https://fsf.org (The free software foundation)
4716− [my label 4]: /bar#special 'A title in single quotes'
4718−The URL may optionally be surrounded by angle brackets:
4720− [my label 5]: <http://foo.bar.baz>
4722−The title may go on the next line:
4724− [my label 3]: https://fsf.org
4725− "The free software foundation"
4727−Note that link labels are not case sensitive. So, this will work:
4729− Here is [my link][FOO]
4733−In an *implicit* reference link, the second pair of brackets is
4736− See [my website][].
4738− [my website]: http://foo.bar.baz
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:
4746− > My block [quote].
4750−#### Extension: `shortcut_reference_links` ####
4752−In a *shortcut* reference link, the second pair of brackets may
4753−be omitted entirely:
4757− [my website]: http://foo.bar.baz
4759−### Internal links ###
4761−To link to another section of the same document, use the automatically
4762−generated identifier (see [Heading identifiers]). For example:
4764− See the [Introduction](#introduction).
4768− See the [Introduction].
4770− [Introduction]: #introduction
4772−Internal links are currently supported for HTML formats (including
4773−HTML slide shows and EPUB), LaTeX, and ConTeXt.
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:
4780− 
4784− [movie reel]: movie.gif
4786−#### Extension: `implicit_figures` ####
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.
4792− 
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
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:
4803− \
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.
4809−#### Extension: `link_attributes` ####
4811−Attributes can be set on links and images:
4813− An inline {#id .class width=30 height=20px}
4814− and a reference ![image][ref] with attributes.
4816− [ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}
4818−(This syntax is compatible with [PHP Markdown Extra] when only `#id`
4819−and `.class` are used.)
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.
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.
4834−{ width=50% }
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
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:
4865−#### Extension: `fenced_divs` ####
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.
4881− ::::: {#special .sidebar}
4882− Here is a paragraph.
4887−Fenced divs can be nested. Opening fences are distinguished
4888−because they *must* have attributes:
4894− This is a warning within a warning.
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.
4905−#### Extension: `bracketed_spans` ####
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:
4911− [This is *some text*]{.class key="val"}
4915−#### Extension: `footnotes` ####
4917−Pandoc's Markdown allows footnotes, using the following syntax:
4919− Here is a footnote reference,[^1] and another.[^longnote]
4921− [^1]: Here is the footnote.
4923− [^longnote]: Here's one with multiple blocks.
4925− Subsequent paragraphs are indented to show that they
4926− belong to the previous footnote.
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.
4934− This paragraph won't be part of the note, because it
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.
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)
4948−#### Extension: `inline_notes` ####
4950−Inline footnotes are also allowed (though, unlike regular notes,
4951−they cannot contain multiple paragraphs). The syntax is as follows:
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
4957−Inline and regular footnotes may be mixed freely.
4961−#### Extension: `citations` ####
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:
4967− Blah blah [@doe99; @smith2000; @smith2004].
4969−How this is rendered depends on the citation style. In an
4970−author-date style, it might render as
4972− Blah blah (Doe 1999, Smith 2000, 2004).
4974−In a footnote style, it might render as
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).
4982−See the [CSL user documentation] for more information about CSL
4983−styles and how they affect rendering.
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]`.
4995−Citation items may optionally include a prefix, a locator, and
4998− Blah blah [see @doe99, pp. 33-35 and *passim*; @smith04, chap. 1].
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.
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.
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:
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]
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:
5030− Smith says blah [-@smith04].
5032−You can also write an author-in-text citation, by omitting the
5035− @smith04 says blah.
5037− @smith04 [p. 33] says blah.
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.
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.
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
5060−## Non-default extensions
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.
5067−#### Extension: `rebase_relative_paths` ####
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.
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
5083− pandoc chap*/*.md -f markdown+rebase_relative_paths
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.
5090−Absolute paths and URLs are not changed. Neither are empty
5091−paths or paths consisting entirely of a fragment, e.g., `#foo`.
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.
5098−#### Extension: `attributes` ####
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`].
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
5111−- Consecutive attribute specifiers may be used,
5112− either for blocks or for inlines. Their attributes
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
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.
5129−#### Extension: `old_dashes` ####
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.
5136−#### Extension: `angle_brackets_escapable` ####
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`.
5142−#### Extension: `lists_without_preceding_blankline` ####
5144−Allow a list to occur right after a paragraph, with no intervening
5147−#### Extension: `four_space_rule` ####
5149−Selects the pandoc <= 2.0 behavior for parsing lists, so that
5150−four spaces indent are needed for list item continuation
5153−#### Extension: `spaced_reference_links` ####
5155−Allow whitespace between the two components of a reference link,
5160−#### Extension: `hard_line_breaks` ####
5162−Causes all newlines within a paragraph to be interpreted as hard line
5163−breaks instead of spaces.
5165−#### Extension: `ignore_line_breaks` ####
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.
5172−#### Extension: `east_asian_line_breaks` ####
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.
5180−#### Extension: `emoji` ####
5182−Parses textual emojis like `:smile:` as Unicode emoticons.
5184−#### Extension: `tex_math_single_backslash` ####
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 `[`.
5191−#### Extension: `tex_math_double_backslash` ####
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.
5197−#### Extension: `markdown_attribute` ####
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`.
5203−#### Extension: `mmd_title_block` ####
5205−Enables a [MultiMarkdown] style title block at the top of
5206−the document, for example:
5210− Date: September 1, 2008
5211− Comment: This is a sample mmd title block, with
5212− a field spanning multiple lines.
5214−See the MultiMarkdown documentation for details. If `pandoc_title_block` or
5215−`yaml_metadata_block` is enabled, it will take precedence over
5218−#### Extension: `abbreviations` ####
5220−Parses PHP Markdown Extra abbreviation keys, like
5222− *[HTML]: Hypertext Markup Language
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).
5228−#### Extension: `autolink_bare_uris` ####
5230−Makes all absolute URIs into links, even when not surrounded by
5231−pointy braces `<...>`.
5233−#### Extension: `mmd_link_attributes` ####
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.
5239− This is a reference ![image][ref] with multimarkdown attributes.
5241− [ref]: https://path.to/image "Image title" width=20px height=30px
5242− id=myId class="myClass1 myClass2"
5244−#### Extension: `mmd_header_identifiers` ####
5246−Parses multimarkdown style heading identifiers (in square brackets,
5247−after the heading but before any trailing `#`s in an ATX heading).
5249−#### Extension: `compact_definition_lists` ####
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:
5255− - No blank line is required between consecutive items of the
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
5260− - Lazy wrapping of paragraphs is not allowed: the entire definition must
5261− be indented four spaces.[^6]
5263−[^6]: To see why laziness is incompatible with relaxing the requirement
5264− of a blank line between items, consider the following example:
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
5276−#### Extension: `gutenberg` ####
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.
5282− [Project Gutenberg]: https://www.gutenberg.org
5284−#### Extension: `sourcepos` ####
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.
5291−## Markdown variants
5293−In addition to pandoc's extended Markdown, the following Markdown
5294−variants are supported:
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)
5304−To see which extensions are supported for a given format,
5305−and which are enabled by default, you can use the command
5307− pandoc --list-extensions=FORMAT
5309−where `FORMAT` is replaced with the name of the format.
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.
5319−When the `--citeproc` option is used, pandoc can automatically generate
5320−citations and a bibliography in a number of styles. Basic usage is
5322− pandoc --citeproc myinput.txt
5324−To use this feature, you will need to have
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.
5331−## Specifying bibliographic data
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:
5340− Format File extension
5341− ------------ --------------
5347−Note that `.bib` can be used with both BibTeX and BibLaTeX files;
5348−use the extension `.bibtex` to force interpretation as BibTeX.
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
5361−`<span style="font-variant:small-caps;">...</span>` or `<sc>...</sc>`
5370−`<span class="nocase">...</span>`
5371−: prevent a phrase from being capitalized as title case
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:
5381− - type: article-journal
5382− id: WatsonCrick1953
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
5400− DOI: 10.1038/171737a0
5401− URL: https://www.nature.com/articles/171737a0
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.
5409−Note that `pandoc` can be used to produce such a YAML metadata
5410−section from a BibTeX, BibLaTeX, or CSL JSON bibliography:
5412− pandoc chem.bib -s -f biblatex -t markdown
5413− pandoc chem.json -s -f csljson -t markdown
5415−Indeed, `pandoc` can convert between any of these
5418− pandoc chem.bib -s -f biblatex -t csljson
5419− pandoc chem.yaml -s -f markdown -t biblatex
5421−Running pandoc on a bibliography file with the `--citeproc`
5422−option will create a formatted bibliography in the format
5425− pandoc chem.bib -s --citeproc -o chem.html
5426− pandoc chem.bib -s --citeproc -o chem.pdf
5428−### Capitalization in titles
5430−If you are using a bibtex or biblatex bibliography, then observe
5431−the following rules:
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`.)
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:
5443− title = {My Dinner with {Andre}}
5445− - In addition, words that should remain lowercase (or camelCase)
5446− should be protected:
5448− title = {Spin Wave Dispersion on the {nm} Scale}
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.
5455−If you are using a CSL bibliography (either JSON or YAML), then observe
5456−the following rules:
5458− - All titles should be in sentence case.
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.)
5464− - Protect words that should not be converted to title case using
5467− Spin wave dispersion on the <span class="nocase">nm</span> scale
5469−### Conference Papers, Published vs. Unpublished
5471−For a formally published conference paper, use the biblatex entry type
5472−`inproceedings` (which will be mapped to CSL `paper-conference`).
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`).
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.
5489−## Specifying a citation style
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
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
5510− "container-title": {
5511− "Lloyd's Law Reports": "Lloyd's Rep",
5512− "Estates Gazette": "EG",
5513− "Scots Law Times": "SLT"
5519−## Citations in note styles
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
5528− Blah blah [@foo, p. 33].
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
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:
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].
5546−## Raw content in a style
5548−To include raw content in a prefix, suffix, delimiter, or term,
5549−surround it with these tags indicating the format:
5551− {{jats}}<ref>{{/jats}}
5553−Without the tags, the string will be interpreted as a string
5554−and escaped in the output, rather than being passed through raw.
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.
5563−## Placement of the bibliography
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:
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.
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:
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.
5588−## Including uncited items in the bibliography
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:
5601−In this example, the document will contain a citation for `item3`
5602−only, but the bibliography will contain entries for `item1`, `item2`, and
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:
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.
5620−## Other relevant metadata fields
5622−A few other metadata fields affect bibliography formatting:
5625−: If true, citations will be
5626− hyperlinked to the corresponding bibliography entries
5627− (for author-date and numerical styles only).
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.)
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:
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).
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
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.
5667−Here's the Markdown source for a simple slide show, `habits.txt`:
5694− 
5701−To produce an HTML/JavaScript slide show, simply type
5703− pandoc -t FORMAT -s habits.txt -o habits.html
5705−where `FORMAT` is either `s5`, `slidy`, `slideous`, `dzslides`, or `revealjs`.
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.
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.
5723−To produce a PDF slide show using beamer, type
5725− pandoc -t beamer habits.txt -o habits.pdf
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.
5730−To produce a Powerpoint slide show, type
5732− pandoc habits.txt -o habits.pptx
5734−## Structuring the slide show
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.
5743−The document is carved up into slides according to the following
5746− * A horizontal rule always starts a new slide.
5748− * A heading at the slide level always starts a new slide.
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.)
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).
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.)
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.
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.
5779−## Incremental lists
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:
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`
5814−Both methods allow incremental and nonincremental lists to be mixed
5815−in a single document.
5817−Note: Neither the `-i/--incremental` option nor any of the
5818−methods described here currently works for PowerPoint output.
5822−You can add "pauses" within a slide by including a paragraph containing
5823−three dots, separated by spaces:
5825− # Slide with a pause
5827− content before the pause
5831− content after the pause
5833−Note: this feature is not yet implemented for PowerPoint output.
5835−## Styling the slides
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.
5845−For dzslides, the CSS is included in the HTML file itself, and may
5848−All [reveal.js configuration options] can be set through variables.
5849−For example, themes can be used by setting the `theme` variable:
5853−Or you can specify a custom stylesheet using the `--css` option.
5855−To style beamer slides, you can specify a `theme`, `colortheme`,
5856−`fonttheme`, `innertheme`, and `outertheme`, using the `-V` option:
5858− pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf
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
5868− # References {.allowframebreaks}
5872−Speaker notes are supported in reveal.js and PowerPoint (pptx)
5873−output. You can add notes to your Markdown document thus:
5879− - It can contain Markdown
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.
5888−Notes are not yet supported for other slide formats, but the notes
5889−will not appear on the slides themselves.
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:
5897− :::::::::::::: {.columns}
5898− ::: {.column width="40%"}
5901− ::: {.column width="60%"}
5906−### Additional columns attributes in beamer
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.
5913− :::::::::::::: {.columns align=center totalwidth=8em}
5914− ::: {.column width="40%"}
5917− ::: {.column width="60%" align=bottom}
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`.
5926−The `totalwidth` attribute limits the width of the columns to the given value.
5928− :::::::::::::: {.columns align=top .onlytextwidth}
5929− ::: {.column width="40%" align=center}
5932− ::: {.column width="60%"}
5937−The class `onlytextwidth` sets the `totalwidth` to `\textwidth`.
5939−See Section 12.7 of the [Beamer User's Guide] for more details.
5941−## Frame attributes in beamer
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:
5948− # Fragile slide {.fragile}
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`.
5955−## Background in reveal.js and beamer
5957−Background images can be added to self-contained reveal.js slideshows and
5958−to beamer slideshows.
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.)
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.
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).
5974−In reveal.js's overview mode, the parallaxBackgroundImage will show up
5975−only on the first slide.
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`.
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.
5985−See the [reveal.js documentation](https://revealjs.com/backgrounds/) for more
5988−For example in reveal.js:
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
6001−Slide 1 has background_image.png as its background.
6003−## {data-background-image="/path/to/special_image.jpg"}
6005−Slide 2 has a special image for its background, even though the heading has no content.
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:
6021− text: An investigation of metadata
6029− text: doi:10.234234.234/33
6030− publisher: My Press
6031− rights: © 2007 John Smith, CC BY-NC
6036−The following fields are recognized:
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`.
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`.
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.
6058− ~ Same format as `creator`.
6061− ~ A string value in `YYYY-MM-DD` format. (Only the year is necessary.)
6062− Pandoc will attempt to convert other common date formats.
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.
6069− ~ A string value or a list of such values.
6089−`belongs-to-collection`
6090− ~ A string value. identifies the name of a collection to which
6091− the EPUB Publication belongs.
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.
6099− ~ A string value (path to cover image).
6101−`css` (or legacy: `stylesheet`)
6102− ~ A string value (path to CSS stylesheet).
6104−`page-progression-direction`
6105− ~ Either `ltr` or `rtl`. Specifies the `page-progression-direction`
6106− attribute for the [`spine` element].
6109− ~ iBooks-specific metadata, with the following fields:
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`
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
6121−## The `epub:type` attribute
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:
6127− # My chapter {epub:type=prologue}
6129−Which will result in:
6131− <body epub:type="frontmatter">
6132− <section epub:type="prologue">
6133− <h1>My chapter</h1>
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.
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
6147−keywords frontmatter
6149−contributors frontmatter
6150−other-credits frontmatter
6152−revision-history frontmatter
6153−titlepage frontmatter
6154−halftitlepage frontmatter
6155−seriespage frontmatter
6156−foreword frontmatter
6160−bibliography backmatter
6163−[epub-type]: http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-epub-type-attribute
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:
6174− <audio controls="1">
6175− <source src="https://example.com/music/toccata.mp3"
6176− data-external="1" type="audio/mpeg">
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:
6196− display_name: Python 2
6203− file_extension: ".py"
6204− mimetype: "text/x-python"
6206− nbconvert_exporter: "python"
6207− pygments_lexer: "ipython2"
6213−**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6214−bibendum felis dictum sodales.
6223−from IPython.display import HTML
6226−console.log("hello");
6234−This image  will be
6235−included as a cell attachment.
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:
6245−:::::: {.cell .markdown}
6248−**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Nunc luctus
6249−bibendum felis dictum sodales.
6252−:::::: {.cell .code execution_count=1}
6257−::: {.output .stream .stdout}
6264−:::::: {.cell .code execution_count=2}
6266−from IPython.display import HTML
6269−console.log("hello");
6275−::: {.output .execute_result execution_count=2}
6278−console.log("hello");
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.
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.
6305−# Syntax highlighting
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`.
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`.
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:
6324− pandoc --print-highlight-style pygments > my.theme
6326−Then edit `my.theme` and use it like this:
6328− pandoc --highlight-style my.theme
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).
6337−To disable highlighting, use the `--no-highlight` option.
6339−[skylighting]: https://github.com/jgm/skylighting
6343−Custom styles can be used in the docx and ICML formats.
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.
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,
6361− [Get out]{custom-style="Emphatically"}, he said.
6363−would produce a docx file with "Get out" styled with character
6364−style `Emphatically`. Similarly, using the `fenced_divs` syntax,
6366− Dickinson starts the poem simply:
6368− ::: {custom-style="Poetry"}
6369− | A Bird came down the Walk---
6370− | He did not know I saw---
6373−would style the two contained lines with the `Poetry` paragraph style.
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.
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`.
6387−For docx output, you don't need to enable any extensions for
6388−custom styles to work.
6390−[pandoc filters]: https://pandoc.org/filters.html
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.
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
6404−For example, using the `custom-style-reference.docx` file in the test
6405−directory, we have the following different outputs:
6407−Without the `+styles` extension:
6409− $ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
6412− This is text with an *emphasized* text style. And this is text with a
6413− **strengthened** text style.
6415− > Here is a styled paragraph that inherits from Block Text.
6417−And with the extension:
6419− $ pandoc test/docx/custom-style-reference.docx -f docx+styles -t markdown
6421− ::: {custom-style="First Paragraph"}
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"}
6431− ::: {custom-style="My Block Style"}
6432− > Here is a styled paragraph that inherits from Block Text.
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.
6441−Pandoc can be extended with custom writers written in [Lua]. (Pandoc
6442−includes a Lua interpreter, so Lua need not be installed separately.)
6444−To use a custom writer, simply specify the path to the Lua script
6445−in place of the output format. For example:
6447− pandoc -t data/sample.lua
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
6453− pandoc --print-default-data-file sample.lua
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]).
6462−[Lua]: https://www.lua.org
6464−# Reproducible builds
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).
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).
6479−# A note on security
6481−If you use pandoc to convert user-contributed content in a web
6482−application, here are some things to keep in mind:
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.
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)
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.
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
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.
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"