@@ -0,0 +1,6520 @@
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"