2.TH PANDOC 1 "October 26, 2016" "pandoc 1.18"
4pandoc - general markup converter
7\f[C]pandoc\f[] [\f[I]options\f[]] [\f[I]input\-file\f[]]...
10Pandoc is a Haskell library for converting from one markup format to
11another, and a command\-line tool that uses this library.
12It can read Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored
13Markdown, MultiMarkdown, and (subsets of) Textile, reStructuredText,
14HTML, LaTeX, MediaWiki markup, TWiki markup, Haddock markup, OPML, Emacs
15Org mode, DocBook, txt2tags, EPUB, ODT and Word docx; and it can write
16plain text, Markdown, CommonMark, PHP Markdown Extra, GitHub\-Flavored
17Markdown, MultiMarkdown, reStructuredText, XHTML, HTML5, LaTeX
18(including \f[C]beamer\f[] slide shows), ConTeXt, RTF, OPML, DocBook,
19OpenDocument, ODT, Word docx, GNU Texinfo, MediaWiki markup, DokuWiki
20markup, ZimWiki markup, Haddock markup, EPUB (v2 or v3), FictionBook2,
21Textile, groff man pages, Emacs Org mode, AsciiDoc, InDesign ICML, TEI
22Simple, and Slidy, Slideous, DZSlides, reveal.js or S5 HTML slide shows.
23It can also produce PDF output on systems where LaTeX, ConTeXt, or
24\f[C]wkhtmltopdf\f[] is installed.
26Pandoc\[aq]s enhanced version of Markdown includes syntax for footnotes,
27tables, flexible ordered lists, definition lists, fenced code blocks,
28superscripts and subscripts, strikeout, metadata blocks, automatic
29tables of contents, embedded LaTeX math, citations, and Markdown inside
31(These enhancements, described further under Pandoc\[aq]s Markdown, can
32be disabled using the \f[C]markdown_strict\f[] input or output format.)
34In contrast to most existing tools for converting Markdown to HTML,
35which use regex substitutions, pandoc has a modular design: it consists
36of a set of readers, which parse text in a given format and produce a
37native representation of the document, and a set of writers, which
38convert this native representation into a target format.
39Thus, adding an input or output format requires only adding a reader or
42Because pandoc\[aq]s intermediate representation of a document is less
43expressive than many of the formats it converts between, one should not
44expect perfect conversions between every format and every other.
45Pandoc attempts to preserve the structural elements of a document, but
46not formatting details such as margin size.
47And some document elements, such as complex tables, may not fit into
48pandoc\[aq]s simple document model.
49While conversions from pandoc\[aq]s Markdown to all formats aspire to be
50perfect, conversions from formats more expressive than pandoc\[aq]s
51Markdown can be expected to be lossy.
52.SS Using \f[C]pandoc\f[]
54If no \f[I]input\-file\f[] is specified, input is read from
56Otherwise, the \f[I]input\-files\f[] are concatenated (with a blank line
57between each) and used as input.
58Output goes to \f[I]stdout\f[] by default (though output to
59\f[I]stdout\f[] is disabled for the \f[C]odt\f[], \f[C]docx\f[],
60\f[C]epub\f[], and \f[C]epub3\f[] output formats).
61For output to a file, use the \f[C]\-o\f[] option:
65pandoc\ \-o\ output.html\ input.txt
69By default, pandoc produces a document fragment, not a standalone
70document with a proper header and footer.
71To produce a standalone document, use the \f[C]\-s\f[] or
72\f[C]\-\-standalone\f[] flag:
76pandoc\ \-s\ \-o\ output.html\ input.txt
80For more information on how standalone documents are produced, see
83Instead of a file, an absolute URI may be given.
84In this case pandoc will fetch the content using HTTP:
88pandoc\ \-f\ html\ \-t\ markdown\ http://www.fsf.org
92If multiple input files are given, \f[C]pandoc\f[] will concatenate them
93all (with blank lines between them) before parsing.
94This feature is disabled for binary input formats such as \f[C]EPUB\f[],
95\f[C]odt\f[], and \f[C]docx\f[].
97The format of the input and output can be specified explicitly using
99The input format can be specified using the \f[C]\-r/\-\-read\f[] or
100\f[C]\-f/\-\-from\f[] options, the output format using the
101\f[C]\-w/\-\-write\f[] or \f[C]\-t/\-\-to\f[] options.
102Thus, to convert \f[C]hello.txt\f[] from Markdown to LaTeX, you could
107pandoc\ \-f\ markdown\ \-t\ latex\ hello.txt
111To convert \f[C]hello.html\f[] from HTML to Markdown:
115pandoc\ \-f\ html\ \-t\ markdown\ hello.html
119Supported output formats are listed below under the \f[C]\-t/\-\-to\f[]
121Supported input formats are listed below under the \f[C]\-f/\-\-from\f[]
123Note that the \f[C]rst\f[], \f[C]textile\f[], \f[C]latex\f[], and
124\f[C]html\f[] readers are not complete; there are some constructs that
127If the input or output format is not specified explicitly,
128\f[C]pandoc\f[] will attempt to guess it from the extensions of the
129input and output filenames.
134pandoc\ \-o\ hello.tex\ hello.txt
138will convert \f[C]hello.txt\f[] from Markdown to LaTeX.
139If no output file is specified (so that output goes to \f[I]stdout\f[]),
140or if the output file\[aq]s extension is unknown, the output format will
142If no input file is specified (so that input comes from \f[I]stdin\f[]),
143or if the input files\[aq] extensions are unknown, the input format will
144be assumed to be Markdown unless explicitly specified.
146Pandoc uses the UTF\-8 character encoding for both input and output.
147If your local character encoding is not UTF\-8, you should pipe input
148and output through \f[C]iconv\f[]:
152iconv\ \-t\ utf\-8\ input.txt\ |\ pandoc\ |\ iconv\ \-f\ utf\-8
156Note that in some output formats (such as HTML, LaTeX, ConTeXt, RTF,
157OPML, DocBook, and Texinfo), information about the character encoding is
158included in the document header, which will only be included if you use
159the \f[C]\-s/\-\-standalone\f[] option.
162To produce a PDF, specify an output file with a \f[C]\&.pdf\f[]
164By default, pandoc will use LaTeX to convert it to PDF:
168pandoc\ test.txt\ \-o\ test.pdf
172Production of a PDF requires that a LaTeX engine be installed (see
173\f[C]\-\-latex\-engine\f[], below), and assumes that the following LaTeX
174packages are available: \f[C]amsfonts\f[], \f[C]amsmath\f[],
175\f[C]lm\f[], \f[C]ifxetex\f[], \f[C]ifluatex\f[], \f[C]eurosym\f[],
176\f[C]listings\f[] (if the \f[C]\-\-listings\f[] option is used),
177\f[C]fancyvrb\f[], \f[C]longtable\f[], \f[C]booktabs\f[],
178\f[C]graphicx\f[] and \f[C]grffile\f[] (if the document contains
179images), \f[C]hyperref\f[], \f[C]ulem\f[], \f[C]geometry\f[] (with the
180\f[C]geometry\f[] variable set), \f[C]setspace\f[] (with
181\f[C]linestretch\f[]), and \f[C]babel\f[] (with \f[C]lang\f[]).
182The use of \f[C]xelatex\f[] or \f[C]lualatex\f[] as the LaTeX engine
183requires \f[C]fontspec\f[]; \f[C]xelatex\f[] uses \f[C]mathspec\f[],
184\f[C]polyglossia\f[] (with \f[C]lang\f[]), \f[C]xecjk\f[], and
185\f[C]bidi\f[] (with the \f[C]dir\f[] variable set).
186The \f[C]upquote\f[] and \f[C]microtype\f[] packages are used if
187available, and \f[C]csquotes\f[] will be used for smart punctuation if
188added to the template or included in any header file.
189The \f[C]natbib\f[], \f[C]biblatex\f[], \f[C]bibtex\f[], and
190\f[C]biber\f[] packages can optionally be used for citation rendering.
191These are included with all recent versions of TeX Live.
193Alternatively, pandoc can use ConTeXt or \f[C]wkhtmltopdf\f[] to create
195To do this, specify an output file with a \f[C]\&.pdf\f[] extension, as
196before, but add \f[C]\-t\ context\f[] or \f[C]\-t\ html5\f[] to the
199PDF output can be controlled using variables for LaTeX (if LaTeX is
200used) and variables for ConTeXt (if ConTeXt is used).
201If \f[C]wkhtmltopdf\f[] is used, then the variables
202\f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[],
203\f[C]margin\-bottom\f[], and \f[C]papersize\f[] will affect the output,
204as will \f[C]\-\-css\f[].
208.B \f[C]\-f\f[] \f[I]FORMAT\f[], \f[C]\-r\f[] \f[I]FORMAT\f[], \f[C]\-\-from=\f[]\f[I]FORMAT\f[], \f[C]\-\-read=\f[]\f[I]FORMAT\f[]
210\f[I]FORMAT\f[] can be \f[C]native\f[] (native Haskell), \f[C]json\f[]
211(JSON version of native AST), \f[C]markdown\f[] (pandoc\[aq]s extended
212Markdown), \f[C]markdown_strict\f[] (original unextended Markdown),
213\f[C]markdown_phpextra\f[] (PHP Markdown Extra),
214\f[C]markdown_github\f[] (GitHub\-Flavored Markdown),
215\f[C]markdown_mmd\f[] (MultiMarkdown), \f[C]commonmark\f[] (CommonMark
216Markdown), \f[C]textile\f[] (Textile), \f[C]rst\f[] (reStructuredText),
217\f[C]html\f[] (HTML), \f[C]docbook\f[] (DocBook), \f[C]t2t\f[]
218(txt2tags), \f[C]docx\f[] (docx), \f[C]odt\f[] (ODT), \f[C]epub\f[]
219(EPUB), \f[C]opml\f[] (OPML), \f[C]org\f[] (Emacs Org mode),
220\f[C]mediawiki\f[] (MediaWiki markup), \f[C]twiki\f[] (TWiki markup),
221\f[C]haddock\f[] (Haddock markup), or \f[C]latex\f[] (LaTeX).
222If \f[C]+lhs\f[] is appended to \f[C]markdown\f[], \f[C]rst\f[],
223\f[C]latex\f[], or \f[C]html\f[], the input will be treated as literate
224Haskell source: see Literate Haskell support, below.
225Markdown syntax extensions can be individually enabled or disabled by
226appending \f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format
228So, for example, \f[C]markdown_strict+footnotes+definition_lists\f[] is
229strict Markdown with footnotes and definition lists enabled, and
230\f[C]markdown\-pipe_tables+hard_line_breaks\f[] is pandoc\[aq]s Markdown
231without pipe tables and with hard line breaks.
232See Pandoc\[aq]s Markdown, below, for a list of extensions and their
234See \f[C]\-\-list\-input\-formats\f[] and \f[C]\-\-list\-extensions\f[],
239.B \f[C]\-t\f[] \f[I]FORMAT\f[], \f[C]\-w\f[] \f[I]FORMAT\f[], \f[C]\-\-to=\f[]\f[I]FORMAT\f[], \f[C]\-\-write=\f[]\f[I]FORMAT\f[]
240Specify output format.
241\f[I]FORMAT\f[] can be \f[C]native\f[] (native Haskell), \f[C]json\f[]
242(JSON version of native AST), \f[C]plain\f[] (plain text),
243\f[C]markdown\f[] (pandoc\[aq]s extended Markdown),
244\f[C]markdown_strict\f[] (original unextended Markdown),
245\f[C]markdown_phpextra\f[] (PHP Markdown Extra),
246\f[C]markdown_github\f[] (GitHub\-Flavored Markdown),
247\f[C]markdown_mmd\f[] (MultiMarkdown), \f[C]commonmark\f[] (CommonMark
248Markdown), \f[C]rst\f[] (reStructuredText), \f[C]html\f[] (XHTML),
249\f[C]html5\f[] (HTML5), \f[C]latex\f[] (LaTeX), \f[C]beamer\f[] (LaTeX
250beamer slide show), \f[C]context\f[] (ConTeXt), \f[C]man\f[] (groff
251man), \f[C]mediawiki\f[] (MediaWiki markup), \f[C]dokuwiki\f[] (DokuWiki
252markup), \f[C]zimwiki\f[] (ZimWiki markup), \f[C]textile\f[] (Textile),
253\f[C]org\f[] (Emacs Org mode), \f[C]texinfo\f[] (GNU Texinfo),
254\f[C]opml\f[] (OPML), \f[C]docbook\f[] (DocBook 4), \f[C]docbook5\f[]
255(DocBook 5), \f[C]opendocument\f[] (OpenDocument), \f[C]odt\f[]
256(OpenOffice text document), \f[C]docx\f[] (Word docx), \f[C]haddock\f[]
257(Haddock markup), \f[C]rtf\f[] (rich text format), \f[C]epub\f[] (EPUB
258v2 book), \f[C]epub3\f[] (EPUB v3), \f[C]fb2\f[] (FictionBook2 e\-book),
259\f[C]asciidoc\f[] (AsciiDoc), \f[C]icml\f[] (InDesign ICML),
260\f[C]tei\f[] (TEI Simple), \f[C]slidy\f[] (Slidy HTML and javascript
261slide show), \f[C]slideous\f[] (Slideous HTML and javascript slide
262show), \f[C]dzslides\f[] (DZSlides HTML5 + javascript slide show),
263\f[C]revealjs\f[] (reveal.js HTML5 + javascript slide show), \f[C]s5\f[]
264(S5 HTML and javascript slide show), or the path of a custom lua writer
265(see Custom writers, below).
266Note that \f[C]odt\f[], \f[C]epub\f[], and \f[C]epub3\f[] output will
267not be directed to \f[I]stdout\f[]; an output filename must be specified
268using the \f[C]\-o/\-\-output\f[] option.
269If \f[C]+lhs\f[] is appended to \f[C]markdown\f[], \f[C]rst\f[],
270\f[C]latex\f[], \f[C]beamer\f[], \f[C]html\f[], or \f[C]html5\f[], the
271output will be rendered as literate Haskell source: see Literate Haskell
273Markdown syntax extensions can be individually enabled or disabled by
274appending \f[C]+EXTENSION\f[] or \f[C]\-EXTENSION\f[] to the format
275name, as described above under \f[C]\-f\f[].
276See \f[C]\-\-list\-output\-formats\f[] and
277\f[C]\-\-list\-extensions\f[], below.
281.B \f[C]\-o\f[] \f[I]FILE\f[], \f[C]\-\-output=\f[]\f[I]FILE\f[]
282Write output to \f[I]FILE\f[] instead of \f[I]stdout\f[].
283If \f[I]FILE\f[] is \f[C]\-\f[], output will go to \f[I]stdout\f[].
284(Exception: if the output format is \f[C]odt\f[], \f[C]docx\f[],
285\f[C]epub\f[], or \f[C]epub3\f[], output to stdout is disabled.)
289.B \f[C]\-\-data\-dir=\f[]\f[I]DIRECTORY\f[]
290Specify the user data directory to search for pandoc data files.
291If this option is not specified, the default user data directory will be
306C:\\Documents\ And\ Settings\\USERNAME\\Application\ Data\\pandoc
310and in Windows Vista or later:
314C:\\Users\\USERNAME\\AppData\\Roaming\\pandoc
318You can find the default user data directory on your system by looking
319at the output of \f[C]pandoc\ \-\-version\f[].
320A \f[C]reference.odt\f[], \f[C]reference.docx\f[], \f[C]epub.css\f[],
321\f[C]templates\f[], \f[C]slidy\f[], \f[C]slideous\f[], or \f[C]s5\f[]
322directory placed in this directory will override pandoc\[aq]s normal
326.B \f[C]\-\-bash\-completion\f[]
327Generate a bash completion script.
328To enable bash completion with pandoc, add this to your
334\ eval\ "$(pandoc\ \-\-bash\-completion)"
339.B \f[C]\-\-verbose\f[]
340Give verbose debugging output.
341Currently this only has an effect with PDF output.
345.B \f[C]\-\-list\-input\-formats\f[]
346List supported input formats, one per line.
350.B \f[C]\-\-list\-output\-formats\f[]
351List supported output formats, one per line.
355.B \f[C]\-\-list\-extensions\f[]
356List supported Markdown extensions, one per line, followed by a
357\f[C]+\f[] or \f[C]\-\f[] indicating whether it is enabled by default in
358pandoc\[aq]s Markdown.
362.B \f[C]\-\-list\-highlight\-languages\f[]
363List supported languages for syntax highlighting, one per line.
367.B \f[C]\-\-list\-highlight\-styles\f[]
368List supported styles for syntax highlighting, one per line.
369See \f[C]\-\-highlight\-style\f[].
373.B \f[C]\-v\f[], \f[C]\-\-version\f[]
378.B \f[C]\-h\f[], \f[C]\-\-help\f[]
384.B \f[C]\-R\f[], \f[C]\-\-parse\-raw\f[]
385Parse untranslatable HTML codes and LaTeX environments as raw HTML or
386LaTeX, instead of ignoring them.
387Affects only HTML and LaTeX input.
388Raw HTML can be printed in Markdown, reStructuredText, Emacs Org mode,
389HTML, Slidy, Slideous, DZSlides, reveal.js, and S5 output; raw LaTeX can
390be printed in Markdown, reStructuredText, Emacs Org mode, LaTeX, and
392The default is for the readers to omit untranslatable HTML codes and
394(The LaTeX reader does pass through untranslatable LaTeX
395\f[I]commands\f[], even if \f[C]\-R\f[] is not specified.)
399.B \f[C]\-S\f[], \f[C]\-\-smart\f[]
400Produce typographically correct output, converting straight quotes to
401curly quotes, \f[C]\-\-\-\f[] to em\-dashes, \f[C]\-\-\f[] to
402en\-dashes, and \f[C]\&...\f[] to ellipses.
403Nonbreaking spaces are inserted after certain abbreviations, such as
404"Mr." (Note: This option is selected automatically when the output
405format is \f[C]latex\f[] or \f[C]context\f[], unless
406\f[C]\-\-no\-tex\-ligatures\f[] is used.
407It has no effect for \f[C]latex\f[] input.)
411.B \f[C]\-\-old\-dashes\f[]
412Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes:
413\f[C]\-\f[] before a numeral is an en\-dash, and \f[C]\-\-\f[] is an
415This option is selected automatically for \f[C]textile\f[] input.
419.B \f[C]\-\-base\-header\-level=\f[]\f[I]NUMBER\f[]
420Specify the base level for headers (defaults to 1).
424.B \f[C]\-\-indented\-code\-classes=\f[]\f[I]CLASSES\f[]
425Specify classes to use for indented code blocks\-\-for example,
426\f[C]perl,numberLines\f[] or \f[C]haskell\f[].
427Multiple classes may be separated by spaces or commas.
431.B \f[C]\-\-default\-image\-extension=\f[]\f[I]EXTENSION\f[]
432Specify a default extension to use when image paths/URLs have no
434This allows you to use the same source for formats that require
435different kinds of images.
436Currently this option only affects the Markdown and LaTeX readers.
440.B \f[C]\-\-file\-scope\f[]
441Parse each file individually before combining for multifile documents.
442This will allow footnotes in different files with the same identifiers
444If this option is set, footnotes and links will not work across files.
445Reading binary files (docx, odt, epub) implies \f[C]\-\-file\-scope\f[].
449.B \f[C]\-\-filter=\f[]\f[I]EXECUTABLE\f[]
450Specify an executable to be used as a filter transforming the pandoc AST
451after the input is parsed and before the output is written.
452The executable should read JSON from stdin and write JSON to stdout.
453The JSON must be formatted like pandoc\[aq]s own JSON input and output.
454The name of the output format will be passed to the filter as the first
461pandoc\ \-\-filter\ ./caps.py\ \-t\ latex
469pandoc\ \-t\ json\ |\ ./caps.py\ latex\ |\ pandoc\ \-f\ json\ \-t\ latex
473The latter form may be useful for debugging filters.
475Filters may be written in any language.
476\f[C]Text.Pandoc.JSON\f[] exports \f[C]toJSONFilter\f[] to facilitate
477writing filters in Haskell.
478Those who would prefer to write filters in python can use the module
479\f[C]pandocfilters\f[], installable from PyPI.
480There are also pandoc filter libraries in PHP, perl, and
483If no directory is provided pandoc will look for executable or
484non\-executable filters in the director \f[C]$DATADIR/filters\f[], and
485then for executable filters in the user\[aq]s \f[C]PATH\f[].
486If you want to run a script in the working directory, preface the
487filename with \f[C]\&./\f[].
489In order of preference, pandoc will look for filters in
491a specified full or relative path (executable or non\-executable)
493\f[C]$DATADIR/filters\f[] (executable or non\-executable)
495\f[C]$PATH\f[] (executable only)
498.B \f[C]\-M\f[] \f[I]KEY\f[][\f[C]=\f[]\f[I]VAL\f[]], \f[C]\-\-metadata=\f[]\f[I]KEY\f[][\f[C]:\f[]\f[I]VAL\f[]]
499Set the metadata field \f[I]KEY\f[] to the value \f[I]VAL\f[].
500A value specified on the command line overrides a value specified in the
502Values will be parsed as YAML boolean or string values.
503If no value is specified, the value will be treated as Boolean true.
504Like \f[C]\-\-variable\f[], \f[C]\-\-metadata\f[] causes template
506But unlike \f[C]\-\-variable\f[], \f[C]\-\-metadata\f[] affects the
507metadata of the underlying document (which is accessible from filters
508and may be printed in some output formats).
512.B \f[C]\-\-normalize\f[]
513Normalize the document after reading: merge adjacent \f[C]Str\f[] or
514\f[C]Emph\f[] elements, for example, and remove repeated
519.B \f[C]\-p\f[], \f[C]\-\-preserve\-tabs\f[]
520Preserve tabs instead of converting them to spaces (the default).
521Note that this will only affect tabs in literal code spans and code
522blocks; tabs in regular text will be treated as spaces.
526.B \f[C]\-\-tab\-stop=\f[]\f[I]NUMBER\f[]
527Specify the number of spaces per tab (default is 4).
531.B \f[C]\-\-track\-changes=accept\f[]|\f[C]reject\f[]|\f[C]all\f[]
532Specifies what to do with insertions, deletions, and comments produced
533by the MS Word "Track Changes" feature.
534\f[C]accept\f[] (the default), inserts all insertions, and ignores all
536\f[C]reject\f[] inserts all deletions and ignores insertions.
537Both \f[C]accept\f[] and \f[C]reject\f[] ignore comments.
538\f[C]all\f[] puts in insertions, deletions, and comments, wrapped in
539spans with \f[C]insertion\f[], \f[C]deletion\f[],
540\f[C]comment\-start\f[], and \f[C]comment\-end\f[] classes,
542The author and time of change is included.
543\f[C]all\f[] is useful for scripting: only accepting changes from a
544certain reviewer, say, or before a certain date.
545This option only affects the docx reader.
549.B \f[C]\-\-extract\-media=\f[]\f[I]DIR\f[]
550Extract images and other media contained in a docx or epub container to
551the path \f[I]DIR\f[], creating it if necessary, and adjust the images
552references in the document so they point to the extracted files.
553This option only affects the docx and epub readers.
556.SS General writer options
558.B \f[C]\-s\f[], \f[C]\-\-standalone\f[]
559Produce output with an appropriate header and footer (e.g.
560a standalone HTML, LaTeX, TEI, or RTF file, not a fragment).
561This option is set automatically for \f[C]pdf\f[], \f[C]epub\f[],
562\f[C]epub3\f[], \f[C]fb2\f[], \f[C]docx\f[], and \f[C]odt\f[] output.
566.B \f[C]\-\-template=\f[]\f[I]FILE\f[]
567Use \f[I]FILE\f[] as a custom template for the generated document.
568Implies \f[C]\-\-standalone\f[].
569See Templates, below, for a description of template syntax.
570If no extension is specified, an extension corresponding to the writer
571will be added, so that \f[C]\-\-template=special\f[] looks for
572\f[C]special.html\f[] for HTML output.
573If the template is not found, pandoc will search for it in the
574\f[C]templates\f[] subdirectory of the user data directory (see
575\f[C]\-\-data\-dir\f[]).
576If this option is not used, a default template appropriate for the
577output format will be used (see
578\f[C]\-D/\-\-print\-default\-template\f[]).
582.B \f[C]\-V\f[] \f[I]KEY\f[][\f[C]=\f[]\f[I]VAL\f[]], \f[C]\-\-variable=\f[]\f[I]KEY\f[][\f[C]:\f[]\f[I]VAL\f[]]
583Set the template variable \f[I]KEY\f[] to the value \f[I]VAL\f[] when
584rendering the document in standalone mode.
585This is generally only useful when the \f[C]\-\-template\f[] option is
586used to specify a custom template, since pandoc automatically sets the
587variables used in the default templates.
588If no \f[I]VAL\f[] is specified, the key will be given the value
593.B \f[C]\-D\f[] \f[I]FORMAT\f[], \f[C]\-\-print\-default\-template=\f[]\f[I]FORMAT\f[]
594Print the system default template for an output \f[I]FORMAT\f[].
595(See \f[C]\-t\f[] for a list of possible \f[I]FORMAT\f[]s.) Templates in
596the user data directory are ignored.
600.B \f[C]\-\-print\-default\-data\-file=\f[]\f[I]FILE\f[]
601Print a system default data file.
602Files in the user data directory are ignored.
606.B \f[C]\-\-dpi\f[]=\f[I]NUMBER\f[]
607Specify the dpi (dots per inch) value for conversion from pixels to
608inch/centimeters and vice versa.
610Technically, the correct term would be ppi (pixels per inch).
614.B \f[C]\-\-wrap=auto\f[]|\f[C]none\f[]|\f[C]preserve\f[]
615Determine how text is wrapped in the output (the source code, not the
617With \f[C]auto\f[] (the default), pandoc will attempt to wrap lines to
618the column width specified by \f[C]\-\-columns\f[] (default 80).
619With \f[C]none\f[], pandoc will not wrap lines at all.
620With \f[C]preserve\f[], pandoc will attempt to preserve the wrapping
621from the source document (that is, where there are nonsemantic newlines
622in the source, there will be nonsemantic newlines in the output as
627.B \f[C]\-\-no\-wrap\f[]
628Deprecated synonym for \f[C]\-\-wrap=none\f[].
632.B \f[C]\-\-columns=\f[]\f[I]NUMBER\f[]
633Specify length of lines in characters.
634This affects text wrapping in the generated source code (see
636It also affects calculation of column widths for plain text tables (see
641.B \f[C]\-\-toc\f[], \f[C]\-\-table\-of\-contents\f[]
642Include an automatically generated table of contents (or, in the case of
643\f[C]latex\f[], \f[C]context\f[], \f[C]docx\f[], and \f[C]rst\f[], an
644instruction to create one) in the output document.
645This option has no effect on \f[C]man\f[], \f[C]docbook\f[],
646\f[C]docbook5\f[], \f[C]slidy\f[], \f[C]slideous\f[], \f[C]s5\f[], or
651.B \f[C]\-\-toc\-depth=\f[]\f[I]NUMBER\f[]
652Specify the number of section levels to include in the table of
654The default is 3 (which means that level 1, 2, and 3 headers will be
655listed in the contents).
659.B \f[C]\-\-no\-highlight\f[]
660Disables syntax highlighting for code blocks and inlines, even when a
661language attribute is given.
665.B \f[C]\-\-highlight\-style=\f[]\f[I]STYLE\f[]
666Specifies the coloring style to be used in highlighted source code.
667Options are \f[C]pygments\f[] (the default), \f[C]kate\f[],
668\f[C]monochrome\f[], \f[C]espresso\f[], \f[C]zenburn\f[],
669\f[C]haddock\f[], and \f[C]tango\f[].
670For more information on syntax highlighting in pandoc, see Syntax
672See also \f[C]\-\-list\-highlight\-styles\f[].
676.B \f[C]\-H\f[] \f[I]FILE\f[], \f[C]\-\-include\-in\-header=\f[]\f[I]FILE\f[]
677Include contents of \f[I]FILE\f[], verbatim, at the end of the header.
678This can be used, for example, to include special CSS or javascript in
680This option can be used repeatedly to include multiple files in the
682They will be included in the order specified.
683Implies \f[C]\-\-standalone\f[].
687.B \f[C]\-B\f[] \f[I]FILE\f[], \f[C]\-\-include\-before\-body=\f[]\f[I]FILE\f[]
688Include contents of \f[I]FILE\f[], verbatim, at the beginning of the
690after the \f[C]<body>\f[] tag in HTML, or the \f[C]\\begin{document}\f[]
692This can be used to include navigation bars or banners in HTML
694This option can be used repeatedly to include multiple files.
695They will be included in the order specified.
696Implies \f[C]\-\-standalone\f[].
700.B \f[C]\-A\f[] \f[I]FILE\f[], \f[C]\-\-include\-after\-body=\f[]\f[I]FILE\f[]
701Include contents of \f[I]FILE\f[], verbatim, at the end of the document
702body (before the \f[C]</body>\f[] tag in HTML, or the
703\f[C]\\end{document}\f[] command in LaTeX).
704This option can be used repeatedly to include multiple files.
705They will be included in the order specified.
706Implies \f[C]\-\-standalone\f[].
709.SS Options affecting specific writers
711.B \f[C]\-\-self\-contained\f[]
712Produce a standalone HTML file with no external dependencies, using
713\f[C]data:\f[] URIs to incorporate the contents of linked scripts,
714stylesheets, images, and videos.
715The resulting file should be "self\-contained," in the sense that it
716needs no external files and no net access to be displayed properly by a
718This option works only with HTML output formats, including
719\f[C]html\f[], \f[C]html5\f[], \f[C]html+lhs\f[], \f[C]html5+lhs\f[],
720\f[C]s5\f[], \f[C]slidy\f[], \f[C]slideous\f[], \f[C]dzslides\f[], and
722Scripts, images, and stylesheets at absolute URLs will be downloaded;
723those at relative URLs will be sought relative to the working directory
724(if the first source file is local) or relative to the base URL (if the
725first source file is remote).
726Limitation: resources that are loaded dynamically through JavaScript
727cannot be incorporated; as a result, \f[C]\-\-self\-contained\f[] does
728not work with \f[C]\-\-mathjax\f[], and some advanced features (e.g.
729zoom or speaker notes) may not work in an offline "self\-contained"
730\f[C]reveal.js\f[] slide show.
734.B \f[C]\-\-html\-q\-tags\f[]
735Use \f[C]<q>\f[] tags for quotes in HTML.
740Use only ascii characters in output.
741Currently supported only for HTML output (which uses numerical entities
742instead of UTF\-8 when this option is selected).
746.B \f[C]\-\-reference\-links\f[]
747Use reference\-style links, rather than inline links, in writing
748Markdown or reStructuredText.
749By default inline links are used.
750The placement of link references is affected by the
751\f[C]\-\-reference\-location\f[] option.
755.B \f[C]\-\-reference\-location\ =\ block\f[]|\f[C]section\f[]|\f[C]document\f[]
756Specify whether footnotes (and references, if \f[C]reference\-links\f[]
757is set) are placed at the end of the current (top\-level) block, the
758current section, or the document.
759The default is \f[C]document\f[].
760Currently only affects the markdown writer.
764.B \f[C]\-\-atx\-headers\f[]
765Use ATX\-style headers in Markdown and asciidoc output.
766The default is to use setext\-style headers for levels 1\-2, and then
771.B \f[C]\-\-chapters\f[]
772Deprecated synonym for \f[C]\-\-top\-level\-division=chapter\f[].
776.B \f[C]\-\-top\-level\-division=[section|chapter|part]\f[]
777Treat top\-level headers as the given division type in LaTeX, ConTeXt,
778DocBook, and TEI output.
779The hierarchy order is part, chapter, then section; all headers are
780shifted such that the top\-level header becomes the specified type.
781The default is \f[C]section\f[].
782When the LaTeX document class is set to \f[C]report\f[], \f[C]book\f[],
783or \f[C]memoir\f[] (unless the \f[C]article\f[] option is specified),
784\f[C]chapter\f[] is implied as the setting for this option.
785If \f[C]beamer\f[] is the output format, specifying either
786\f[C]chapter\f[] or \f[C]part\f[] will cause top\-level headers to
787become \f[C]\\part{..}\f[], while second\-level headers remain as their
792.B \f[C]\-N\f[], \f[C]\-\-number\-sections\f[]
793Number section headings in LaTeX, ConTeXt, HTML, or EPUB output.
794By default, sections are not numbered.
795Sections with class \f[C]unnumbered\f[] will never be numbered, even if
796\f[C]\-\-number\-sections\f[] is specified.
800.B \f[C]\-\-number\-offset=\f[]\f[I]NUMBER\f[][\f[C],\f[]\f[I]NUMBER\f[]\f[C],\f[]\f[I]\&...\f[]]
801Offset for section headings in HTML output (ignored in other output
803The first number is added to the section number for top\-level headers,
804the second for second\-level headers, and so on.
805So, for example, if you want the first top\-level header in your
806document to be numbered "6", specify \f[C]\-\-number\-offset=5\f[].
807If your document starts with a level\-2 header which you want to be
808numbered "1.5", specify \f[C]\-\-number\-offset=1,4\f[].
809Offsets are 0 by default.
810Implies \f[C]\-\-number\-sections\f[].
814.B \f[C]\-\-no\-tex\-ligatures\f[]
815Do not use the TeX ligatures for quotation marks, apostrophes, and
816dashes (\f[C]`...\[aq]\f[], \f[C]``..\[aq]\[aq]\f[], \f[C]\-\-\f[],
817\f[C]\-\-\-\f[]) when writing or reading LaTeX or ConTeXt.
818In reading LaTeX, parse the characters \f[C]`\f[], \f[C]\[aq]\f[], and
819\f[C]\-\f[] literally, rather than parsing ligatures for quotation marks
821In writing LaTeX or ConTeXt, print unicode quotation mark and dash
822characters literally, rather than converting them to the standard ASCII
824Note: normally \f[C]\-\-smart\f[] is selected automatically for LaTeX
825and ConTeXt output, but it must be specified explicitly if
826\f[C]\-\-no\-tex\-ligatures\f[] is selected.
827If you use literal curly quotes, dashes, and ellipses in your source,
828then you may want to use \f[C]\-\-no\-tex\-ligatures\f[] without
833.B \f[C]\-\-listings\f[]
834Use the \f[C]listings\f[] package for LaTeX code blocks
838.B \f[C]\-i\f[], \f[C]\-\-incremental\f[]
839Make list items in slide shows display incrementally (one by one).
840The default is for lists to be displayed all at once.
844.B \f[C]\-\-slide\-level=\f[]\f[I]NUMBER\f[]
845Specifies that headers with the specified level create slides (for
846\f[C]beamer\f[], \f[C]s5\f[], \f[C]slidy\f[], \f[C]slideous\f[],
848Headers above this level in the hierarchy are used to divide the slide
849show into sections; headers below this level create subheads within a
851The default is to set the slide level based on the contents of the
852document; see Structuring the slide show.
856.B \f[C]\-\-section\-divs\f[]
857Wrap sections in \f[C]<div>\f[] tags (or \f[C]<section>\f[] tags in
858HTML5), and attach identifiers to the enclosing \f[C]<div>\f[] (or
859\f[C]<section>\f[]) rather than the header itself.
860See Header identifiers, below.
864.B \f[C]\-\-email\-obfuscation=none\f[]|\f[C]javascript\f[]|\f[C]references\f[]
865Specify a method for obfuscating \f[C]mailto:\f[] links in HTML
867\f[C]none\f[] leaves \f[C]mailto:\f[] links as they are.
868\f[C]javascript\f[] obfuscates them using javascript.
869\f[C]references\f[] obfuscates them by printing their letters as decimal
870or hexadecimal character references.
871The default is \f[C]none\f[].
875.B \f[C]\-\-id\-prefix=\f[]\f[I]STRING\f[]
876Specify a prefix to be added to all automatically generated identifiers
877in HTML and DocBook output, and to footnote numbers in Markdown output.
878This is useful for preventing duplicate identifiers when generating
879fragments to be included in other pages.
883.B \f[C]\-T\f[] \f[I]STRING\f[], \f[C]\-\-title\-prefix=\f[]\f[I]STRING\f[]
884Specify \f[I]STRING\f[] as a prefix at the beginning of the title that
885appears in the HTML header (but not in the title as it appears at the
886beginning of the HTML body).
887Implies \f[C]\-\-standalone\f[].
891.B \f[C]\-c\f[] \f[I]URL\f[], \f[C]\-\-css=\f[]\f[I]URL\f[]
892Link to a CSS style sheet.
893This option can be used repeatedly to include multiple files.
894They will be included in the order specified.
898.B \f[C]\-\-reference\-odt=\f[]\f[I]FILE\f[]
899Use the specified file as a style reference in producing an ODT.
900For best results, the reference ODT should be a modified version of an
901ODT produced using pandoc.
902The contents of the reference ODT are ignored, but its stylesheets are
904If no reference ODT is specified on the command line, pandoc will look
905for a file \f[C]reference.odt\f[] in the user data directory (see
906\f[C]\-\-data\-dir\f[]).
907If this is not found either, sensible defaults will be used.
911.B \f[C]\-\-reference\-docx=\f[]\f[I]FILE\f[]
912Use the specified file as a style reference in producing a docx file.
913For best results, the reference docx should be a modified version of a
914docx file produced using pandoc.
915The contents of the reference docx are ignored, but its stylesheets and
916document properties (including margins, page size, header, and footer)
917are used in the new docx.
918If no reference docx is specified on the command line, pandoc will look
919for a file \f[C]reference.docx\f[] in the user data directory (see
920\f[C]\-\-data\-dir\f[]).
921If this is not found either, sensible defaults will be used.
922The following styles are used by pandoc: [paragraph] Normal, Body Text,
923First Paragraph, Compact, Title, Subtitle, Author, Date, Abstract,
924Bibliography, Heading 1, Heading 2, Heading 3, Heading 4, Heading 5,
925Heading 6, Block Text, Footnote Text, Definition Term, Definition,
926Caption, Table Caption, Image Caption, Figure, Figure With Caption, TOC
927Heading; [character] Default Paragraph Font, Body Text Char, Verbatim
928Char, Footnote Reference, Hyperlink; [table] Normal Table.
932.B \f[C]\-\-epub\-stylesheet=\f[]\f[I]FILE\f[]
933Use the specified CSS file to style the EPUB.
934If no stylesheet is specified, pandoc will look for a file
935\f[C]epub.css\f[] in the user data directory (see
936\f[C]\-\-data\-dir\f[]).
937If it is not found there, sensible defaults will be used.
941.B \f[C]\-\-epub\-cover\-image=\f[]\f[I]FILE\f[]
942Use the specified image as the EPUB cover.
943It is recommended that the image be less than 1000px in width and
945Note that in a Markdown source document you can also specify
946\f[C]cover\-image\f[] in a YAML metadata block (see EPUB Metadata,
951.B \f[C]\-\-epub\-metadata=\f[]\f[I]FILE\f[]
952Look in the specified XML file for metadata for the EPUB.
953The file should contain a series of Dublin Core elements.
959\ <dc:rights>Creative\ Commons</dc:rights>
960\ <dc:language>es\-AR</dc:language>
964By default, pandoc will include the following metadata elements:
965\f[C]<dc:title>\f[] (from the document title), \f[C]<dc:creator>\f[]
966(from the document authors), \f[C]<dc:date>\f[] (from the document date,
967which should be in ISO 8601 format), \f[C]<dc:language>\f[] (from the
968\f[C]lang\f[] variable, or, if is not set, the locale), and
969\f[C]<dc:identifier\ id="BookId">\f[] (a randomly generated UUID).
970Any of these may be overridden by elements in the metadata file.
972Note: if the source document is Markdown, a YAML metadata block in the
973document can be used instead.
974See below under EPUB Metadata.
977.B \f[C]\-\-epub\-embed\-font=\f[]\f[I]FILE\f[]
978Embed the specified font in the EPUB.
979This option can be repeated to embed multiple fonts.
980Wildcards can also be used: for example, \f[C]DejaVuSans\-*.ttf\f[].
981However, if you use wildcards on the command line, be sure to escape
982them or put the whole filename in single quotes, to prevent them from
983being interpreted by the shell.
984To use the embedded fonts, you will need to add declarations like the
985following to your CSS (see \f[C]\-\-epub\-stylesheet\f[]):
991font\-family:\ DejaVuSans;
993font\-weight:\ normal;
994src:url("DejaVuSans\-Regular.ttf");
997font\-family:\ DejaVuSans;
1000src:url("DejaVuSans\-Bold.ttf");
1003font\-family:\ DejaVuSans;
1004font\-style:\ italic;
1005font\-weight:\ normal;
1006src:url("DejaVuSans\-Oblique.ttf");
1009font\-family:\ DejaVuSans;
1010font\-style:\ italic;
1012src:url("DejaVuSans\-BoldOblique.ttf");
1014body\ {\ font\-family:\ "DejaVuSans";\ }
1019.B \f[C]\-\-epub\-chapter\-level=\f[]\f[I]NUMBER\f[]
1020Specify the header level at which to split the EPUB into separate
1022The default is to split into chapters at level 1 headers.
1023This option only affects the internal composition of the EPUB, not the
1024way chapters and sections are displayed to users.
1025Some readers may be slow if the chapter files are too large, so for
1026large documents with few level 1 headers, one might want to use a
1027chapter level of 2 or 3.
1031.B \f[C]\-\-latex\-engine=pdflatex\f[]|\f[C]lualatex\f[]|\f[C]xelatex\f[]
1032Use the specified LaTeX engine when producing PDF output.
1033The default is \f[C]pdflatex\f[].
1034If the engine is not in your PATH, the full path of the engine may be
1039.B \f[C]\-\-latex\-engine\-opt=\f[]\f[I]STRING\f[]
1040Use the given string as a command\-line argument to the
1041\f[C]latex\-engine\f[].
1042If used multiple times, the arguments are provided with spaces between
1044Note that no check for duplicate options is done.
1047.SS Citation rendering
1049.B \f[C]\-\-bibliography=\f[]\f[I]FILE\f[]
1050Set the \f[C]bibliography\f[] field in the document\[aq]s metadata to
1051\f[I]FILE\f[], overriding any value set in the metadata, and process
1052citations using \f[C]pandoc\-citeproc\f[].
1053(This is equivalent to
1054\f[C]\-\-metadata\ bibliography=FILE\ \-\-filter\ pandoc\-citeproc\f[].)
1055If \f[C]\-\-natbib\f[] or \f[C]\-\-biblatex\f[] is also supplied,
1056\f[C]pandoc\-citeproc\f[] is not used, making this equivalent to
1057\f[C]\-\-metadata\ bibliography=FILE\f[].
1058If you supply this argument multiple times, each \f[I]FILE\f[] will be
1059added to bibliography.
1063.B \f[C]\-\-csl=\f[]\f[I]FILE\f[]
1064Set the \f[C]csl\f[] field in the document\[aq]s metadata to
1065\f[I]FILE\f[], overriding any value set in the metadata.
1066(This is equivalent to \f[C]\-\-metadata\ csl=FILE\f[].) This option is
1067only relevant with \f[C]pandoc\-citeproc\f[].
1071.B \f[C]\-\-citation\-abbreviations=\f[]\f[I]FILE\f[]
1072Set the \f[C]citation\-abbreviations\f[] field in the document\[aq]s
1073metadata to \f[I]FILE\f[], overriding any value set in the metadata.
1074(This is equivalent to
1075\f[C]\-\-metadata\ citation\-abbreviations=FILE\f[].) This option is
1076only relevant with \f[C]pandoc\-citeproc\f[].
1080.B \f[C]\-\-natbib\f[]
1081Use \f[C]natbib\f[] for citations in LaTeX output.
1082This option is not for use with the \f[C]pandoc\-citeproc\f[] filter or
1084It is intended for use in producing a LaTeX file that can be processed
1085with \f[C]bibtex\f[].
1089.B \f[C]\-\-biblatex\f[]
1090Use \f[C]biblatex\f[] for citations in LaTeX output.
1091This option is not for use with the \f[C]pandoc\-citeproc\f[] filter or
1093It is intended for use in producing a LaTeX file that can be processed
1094with \f[C]bibtex\f[] or \f[C]biber\f[].
1097.SS Math rendering in HTML
1099.B \f[C]\-m\f[] [\f[I]URL\f[]], \f[C]\-\-latexmathml\f[][\f[C]=\f[]\f[I]URL\f[]]
1100Use the LaTeXMathML script to display embedded TeX math in HTML output.
1101To insert a link to a local copy of the \f[C]LaTeXMathML.js\f[] script,
1102provide a \f[I]URL\f[].
1103If no \f[I]URL\f[] is provided, the contents of the script will be
1104inserted directly into the HTML header, preserving portability at the
1106If you plan to use math on several pages, it is much better to link to a
1107copy of the script, so it can be cached.
1111.B \f[C]\-\-mathml\f[][\f[C]=\f[]\f[I]URL\f[]]
1112Convert TeX math to MathML (in \f[C]docbook\f[], \f[C]docbook5\f[],
1113\f[C]html\f[] and \f[C]html5\f[]).
1114In standalone \f[C]html\f[] output, a small javascript (or a link to
1115such a script if a \f[I]URL\f[] is supplied) will be inserted that
1116allows the MathML to be viewed on some browsers.
1120.B \f[C]\-\-jsmath\f[][\f[C]=\f[]\f[I]URL\f[]]
1121Use jsMath to display embedded TeX math in HTML output.
1122The \f[I]URL\f[] should point to the jsMath load script (e.g.
1123\f[C]jsMath/easy/load.js\f[]); if provided, it will be linked to in the
1124header of standalone HTML documents.
1125If a \f[I]URL\f[] is not provided, no link to the jsMath load script
1126will be inserted; it is then up to the author to provide such a link in
1131.B \f[C]\-\-mathjax\f[][\f[C]=\f[]\f[I]URL\f[]]
1132Use MathJax to display embedded TeX math in HTML output.
1133The \f[I]URL\f[] should point to the \f[C]MathJax.js\f[] load script.
1134If a \f[I]URL\f[] is not provided, a link to the MathJax CDN will be
1139.B \f[C]\-\-gladtex\f[]
1140Enclose TeX math in \f[C]<eq>\f[] tags in HTML output.
1141These can then be processed by gladTeX to produce links to images of the
1146.B \f[C]\-\-mimetex\f[][\f[C]=\f[]\f[I]URL\f[]]
1147Render TeX math using the mimeTeX CGI script.
1148If \f[I]URL\f[] is not specified, it is assumed that the script is at
1149\f[C]/cgi\-bin/mimetex.cgi\f[].
1153.B \f[C]\-\-webtex\f[][\f[C]=\f[]\f[I]URL\f[]]
1154Render TeX formulas using an external script that converts TeX formulas
1156The formula will be concatenated with the URL provided.
1157If \f[I]URL\f[] is not specified, the CodeCogs will be used.
1158Note: the \f[C]\-\-webtex\f[] option will affect Markdown output as well
1159as HTML, which is useful if you\[aq]re targeting a version of Markdown
1160without native math support.
1164.B \f[C]\-\-katex\f[][\f[C]=\f[]\f[I]URL\f[]]
1165Use KaTeX to display embedded TeX math in HTML output.
1166The \f[I]URL\f[] should point to the \f[C]katex.js\f[] load script.
1167If a \f[I]URL\f[] is not provided, a link to the KaTeX CDN will be
1169Note: KaTeX seems to work best with \f[C]html5\f[] output.
1173.B \f[C]\-\-katex\-stylesheet=\f[]\f[I]URL\f[]
1174The \f[I]URL\f[] should point to the \f[C]katex.css\f[] stylesheet.
1175If this option is not specified, a link to the KaTeX CDN will be
1177Note that this option does not imply \f[C]\-\-katex\f[].
1180.SS Options for wrapper scripts
1182.B \f[C]\-\-dump\-args\f[]
1183Print information about command\-line arguments to \f[I]stdout\f[], then
1185This option is intended primarily for use in wrapper scripts.
1186The first line of output contains the name of the output file specified
1187with the \f[C]\-o\f[] option, or \f[C]\-\f[] (for \f[I]stdout\f[]) if no
1188output file was specified.
1189The remaining lines contain the command\-line arguments, one per line,
1190in the order they appear.
1191These do not include regular pandoc options and their arguments, but do
1192include any options appearing after a \f[C]\-\-\f[] separator at the end
1197.B \f[C]\-\-ignore\-args\f[]
1198Ignore command\-line arguments (for use in wrapper scripts).
1199Regular pandoc options are not ignored.
1205pandoc\ \-\-ignore\-args\ \-o\ foo.html\ \-s\ foo.txt\ \-\-\ \-e\ latin1
1213pandoc\ \-o\ foo.html\ \-s
1219When the \f[C]\-s/\-\-standalone\f[] option is used, pandoc uses a
1220template to add header and footer material that is needed for a
1221self\-standing document.
1222To see the default template that is used, just type
1226pandoc\ \-D\ *FORMAT*
1230where \f[I]FORMAT\f[] is the name of the output format.
1231A custom template can be specified using the \f[C]\-\-template\f[]
1233You can also override the system default templates for a given output
1234format \f[I]FORMAT\f[] by putting a file
1235\f[C]templates/default.*FORMAT*\f[] in the user data directory (see
1236\f[C]\-\-data\-dir\f[], above).
1239For \f[C]odt\f[] output, customize the \f[C]default.opendocument\f[]
1242For \f[C]pdf\f[] output, customize the \f[C]default.latex\f[] template
1243(or the \f[C]default.beamer\f[] template, if you use
1244\f[C]\-t\ beamer\f[], or the \f[C]default.context\f[] template, if you
1245use \f[C]\-t\ context\f[]).
1247\f[C]docx\f[] has no template (however, you can use
1248\f[C]\-\-reference\-docx\f[] to customize the output).
1250Templates contain \f[I]variables\f[], which allow for the inclusion of
1251arbitrary information at any point in the file.
1252Variables may be set within the document using YAML metadata blocks.
1253They may also be set at the command line using the
1254\f[C]\-V/\-\-variable\f[] option: variables set in this way override
1255metadata fields with the same name.
1256.SS Variables set by pandoc
1258Some variables are set automatically by pandoc.
1259These vary somewhat depending on the output format, but include metadata
1260fields as well as the following:
1262.B \f[C]title\f[], \f[C]author\f[], \f[C]date\f[]
1263allow identification of basic aspects of the document.
1264Included in PDF metadata through LaTeX and ConTeXt.
1265These can be set through a pandoc title block, which allows for multiple
1266authors, or through a YAML metadata block:
1281document subtitle, included in HTML, EPUB, LaTeX, ConTeXt, and Word
1282docx; renders in LaTeX only when using a document class that supports
1283\f[C]\\subtitle\f[], such as \f[C]beamer\f[] or the KOMA\-Script series
1284(\f[C]scrartcl\f[], \f[C]scrreprt\f[], \f[C]scrbook\f[]).
1288.B \f[C]institute\f[]
1289author affiliations (in LaTeX and Beamer only).
1290Can be a list, when there are multiple authors.
1295document summary, included in LaTeX, ConTeXt, AsciiDoc, and Word docx
1300list of keywords to be included in HTML, PDF, and AsciiDoc metadata; may
1301be repeated as for \f[C]author\f[], above
1305.B \f[C]header\-includes\f[]
1306contents specified by \f[C]\-H/\-\-include\-in\-header\f[] (may have
1312non\-null value if \f[C]\-\-toc/\-\-table\-of\-contents\f[] was
1317.B \f[C]toc\-title\f[]
1318title of table of contents (works only with EPUB and docx)
1322.B \f[C]include\-before\f[]
1323contents specified by \f[C]\-B/\-\-include\-before\-body\f[] (may have
1328.B \f[C]include\-after\f[]
1329contents specified by \f[C]\-A/\-\-include\-after\-body\f[] (may have
1339.B \f[C]meta\-json\f[]
1340JSON representation of all of the document\[aq]s metadata
1343.SS Language variables
1346identifies the main language of the document, using a code according to
1348\f[C]en\f[] or \f[C]en\-GB\f[]).
1349For some output formats, pandoc will convert it to an appropriate format
1350stored in the additional variables \f[C]babel\-lang\f[],
1351\f[C]polyglossia\-lang\f[] (LaTeX) and \f[C]context\-lang\f[] (ConTeXt).
1354Native pandoc \f[C]span\f[]s and \f[C]div\f[]s with the lang attribute
1355(value in BCP 47) can be used to switch the language in that range.
1358.B \f[C]otherlangs\f[]
1359a list of other languages used in the document in the YAML metadata,
1361For example: \f[C]otherlangs:\ [en\-GB,\ fr]\f[].
1362This is automatically generated from the \f[C]lang\f[] attributes in all
1363\f[C]span\f[]s and \f[C]div\f[]s but can be overridden.
1364Currently only used by LaTeX through the generated
1365\f[C]babel\-otherlangs\f[] and \f[C]polyglossia\-otherlangs\f[]
1367The LaTeX writer outputs polyglossia commands in the text but the
1368\f[C]babel\-newcommands\f[] variable contains mappings for them to the
1374the base direction of the document, either \f[C]rtl\f[]
1375(right\-to\-left) or \f[C]ltr\f[] (left\-to\-right).
1378For bidirectional documents, native pandoc \f[C]span\f[]s and
1379\f[C]div\f[]s with the \f[C]dir\f[] attribute (value \f[C]rtl\f[] or
1380\f[C]ltr\f[]) can be used to override the base direction in some output
1382This may not always be necessary if the final renderer (e.g.
1383the browser, when generating HTML) supports the Unicode Bidirectional
1386When using LaTeX for bidirectional documents, only the \f[C]xelatex\f[]
1387engine is fully supported (use \f[C]\-\-latex\-engine=xelatex\f[]).
1389.SS Variables for slides
1391Variables are available for producing slide shows with pandoc, including
1392all reveal.js configuration options.
1394.B \f[C]slidy\-url\f[]
1395base URL for Slidy documents (defaults to
1396\f[C]http://www.w3.org/Talks/Tools/Slidy2\f[])
1400.B \f[C]slideous\-url\f[]
1401base URL for Slideous documents (defaults to \f[C]slideous\f[])
1406base URL for S5 documents (defaults to \f[C]s5/default\f[])
1410.B \f[C]revealjs\-url\f[]
1411base URL for reveal.js documents (defaults to \f[C]reveal.js\f[])
1415.B \f[C]theme\f[], \f[C]colortheme\f[], \f[C]fonttheme\f[], \f[C]innertheme\f[], \f[C]outertheme\f[]
1416themes for LaTeX \f[C]beamer\f[] documents
1420.B \f[C]themeoptions\f[]
1421options for LaTeX beamer themes (a list).
1425.B \f[C]navigation\f[]
1426controls navigation symbols in \f[C]beamer\f[] documents (default is
1427\f[C]empty\f[] for no navigation symbols; other valid values are
1428\f[C]frame\f[], \f[C]vertical\f[], and \f[C]horizontal\f[]).
1432.B \f[C]section\-titles\f[]
1433enables on "title pages" for new sections in \f[C]beamer\f[] documents
1438.B \f[C]beamerarticle\f[]
1439when true, the \f[C]beamerarticle\f[] package is loaded (for producing
1440an article from beamer slides).
1444.B \f[C]colorlinks\f[]
1445add color to link text; automatically enabled if any of
1446\f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], or
1447\f[C]toccolor\f[] are set (for beamer only).
1451.B \f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], \f[C]toccolor\f[]
1452color for internal links, citation links, external links, and links in
1453table of contents: uses any of the predefined LaTeX colors (for beamer
1457.SS Variables for LaTeX
1459LaTeX variables are used when creating a PDF.
1461.B \f[C]papersize\f[]
1463\f[C]letter\f[], \f[C]A4\f[]
1468font size for body text (e.g.
1469\f[C]10pt\f[], \f[C]12pt\f[])
1473.B \f[C]documentclass\f[]
1475\f[C]article\f[], \f[C]report\f[], \f[C]book\f[], \f[C]memoir\f[]
1479.B \f[C]classoption\f[]
1480option for document class, e.g.
1481\f[C]oneside\f[]; may be repeated for multiple options
1486option for \f[C]geometry\f[] package, e.g.
1487\f[C]margin=1in\f[]; may be repeated for multiple options
1491.B \f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], \f[C]margin\-bottom\f[]
1492sets margins, if \f[C]geometry\f[] is not used (otherwise
1493\f[C]geometry\f[] overrides these)
1497.B \f[C]linestretch\f[]
1498adjusts line spacing using the \f[C]setspace\f[] package, e.g.
1499\f[C]1.25\f[], \f[C]1.5\f[]
1503.B \f[C]fontfamily\f[]
1504font package for use with \f[C]pdflatex\f[]: TeX Live includes many
1505options, documented in the LaTeX Font Catalogue.
1506The default is Latin Modern.
1510.B \f[C]fontfamilyoptions\f[]
1511options for package used as \f[C]fontfamily\f[]: e.g.
1512\f[C]osf,sc\f[] with \f[C]fontfamily\f[] set to \f[C]mathpazo\f[]
1513provides Palatino with old\-style figures and true small caps; may be
1514repeated for multiple options
1518.B \f[C]mainfont\f[], \f[C]sansfont\f[], \f[C]monofont\f[], \f[C]mathfont\f[], \f[C]CJKmainfont\f[]
1519font families for use with \f[C]xelatex\f[] or \f[C]lualatex\f[]: take
1520the name of any system font, using the \f[C]fontspec\f[] package.
1521Note that if \f[C]CJKmainfont\f[] is used, the \f[C]xecjk\f[] package
1526.B \f[C]mainfontoptions\f[], \f[C]sansfontoptions\f[], \f[C]monofontoptions\f[], \f[C]mathfontoptions\f[], \f[C]CJKoptions\f[]
1527options to use with \f[C]mainfont\f[], \f[C]sansfont\f[],
1528\f[C]monofont\f[], \f[C]mathfont\f[], \f[C]CJKmainfont\f[] in
1529\f[C]xelatex\f[] and \f[C]lualatex\f[].
1530Allow for any choices available through \f[C]fontspec\f[], such as the
1531OpenType features \f[C]Numbers=OldStyle,Numbers=Proportional\f[].
1532May be repeated for multiple options.
1537allows font encoding to be specified through \f[C]fontenc\f[] package
1538(with \f[C]pdflatex\f[]); default is \f[C]T1\f[] (see guide to LaTeX
1543.B \f[C]colorlinks\f[]
1544add color to link text; automatically enabled if any of
1545\f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], or
1546\f[C]toccolor\f[] are set
1550.B \f[C]linkcolor\f[], \f[C]citecolor\f[], \f[C]urlcolor\f[], \f[C]toccolor\f[]
1551color for internal links, citation links, external links, and links in
1552table of contents: uses any of the predefined LaTeX colors
1556.B \f[C]links\-as\-notes\f[]
1557causes links to be printed as footnotes
1562uses document class settings for indentation (the default LaTeX template
1563otherwise removes indentation and adds space between paragraphs)
1567.B \f[C]subparagraph\f[]
1568disables default behavior of LaTeX template that redefines
1569(sub)paragraphs as sections, changing the appearance of nested headings
1575specifies contents of acknowledgments footnote after document title.
1580include table of contents (can also be set using
1581\f[C]\-\-toc/\-\-table\-of\-contents\f[])
1585.B \f[C]toc\-depth\f[]
1586level of section to include in table of contents
1590.B \f[C]secnumdepth\f[]
1591numbering depth for sections, if sections are numbered
1595.B \f[C]lof\f[], \f[C]lot\f[]
1596include list of figures, list of tables
1600.B \f[C]bibliography\f[]
1601bibliography to use for resolving references
1605.B \f[C]biblio\-style\f[]
1606bibliography style, when used with \f[C]\-\-natbib\f[] and
1607\f[C]\-\-biblatex\f[].
1611.B \f[C]biblio\-title\f[]
1612bibliography title, when used with \f[C]\-\-natbib\f[] and
1613\f[C]\-\-biblatex\f[].
1617.B \f[C]biblatexoptions\f[]
1618list of options for biblatex.
1621.SS Variables for ConTeXt
1623.B \f[C]papersize\f[]
1625\f[C]letter\f[], \f[C]A4\f[], \f[C]landscape\f[] (see ConTeXt Paper
1626Setup); may be repeated for multiple options
1631options for page margins and text arrangement (see ConTeXt Layout); may
1632be repeated for multiple options
1636.B \f[C]margin\-left\f[], \f[C]margin\-right\f[], \f[C]margin\-top\f[], \f[C]margin\-bottom\f[]
1637sets margins, if \f[C]layout\f[] is not used (otherwise \f[C]layout\f[]
1643font size for body text (e.g.
1644\f[C]10pt\f[], \f[C]12pt\f[])
1648.B \f[C]mainfont\f[], \f[C]sansfont\f[], \f[C]monofont\f[], \f[C]mathfont\f[]
1649font families: take the name of any system font (see ConTeXt Font
1654.B \f[C]linkcolor\f[], \f[C]contrastcolor\f[]
1655color for links outside and inside a page, e.g.
1656\f[C]red\f[], \f[C]blue\f[] (see ConTeXt Color)
1660.B \f[C]linkstyle\f[]
1661typeface style for links, e.g.
1662\f[C]normal\f[], \f[C]bold\f[], \f[C]slanted\f[], \f[C]boldslanted\f[],
1663\f[C]type\f[], \f[C]cap\f[], \f[C]small\f[]
1667.B \f[C]indenting\f[]
1668controls indentation of paragraphs, e.g.
1669\f[C]yes,small,next\f[] (see ConTeXt Indentation); may be repeated for
1674.B \f[C]whitespace\f[]
1675spacing between paragraphs, e.g.
1676\f[C]none\f[], \f[C]small\f[] (using \f[C]setupwhitespace\f[])
1680.B \f[C]interlinespace\f[]
1681adjusts line spacing, e.g.
1682\f[C]4ex\f[] (using \f[C]setupinterlinespace\f[]); may be repeated for
1687.B \f[C]headertext\f[], \f[C]footertext\f[]
1688text to be placed in running header or footer (see ConTeXt Headers and
1689Footers); may be repeated up to four times for different placement
1693.B \f[C]pagenumbering\f[]
1694page number style and location (using \f[C]setuppagenumbering\f[]); may
1695be repeated for multiple options
1700include table of contents (can also be set using
1701\f[C]\-\-toc/\-\-table\-of\-contents\f[])
1705.B \f[C]lof\f[], \f[C]lot\f[]
1706include list of figures, list of tables
1709.SS Variables for man pages
1712section number in man pages
1726.B \f[C]adjusting\f[]
1727adjusts text to left (\f[C]l\f[]), right (\f[C]r\f[]), center
1728(\f[C]c\f[]), or both (\f[C]b\f[]) margins
1732.B \f[C]hyphenate\f[]
1733if \f[C]true\f[] (the default), hyphenation will be used
1736.SS Using variables in templates
1738Variable names are sequences of alphanumerics, \f[C]\-\f[], and
1739\f[C]_\f[], starting with a letter.
1740A variable name surrounded by \f[C]$\f[] signs will be replaced by its
1742For example, the string \f[C]$title$\f[] in
1746<title>$title$</title>
1750will be replaced by the document title.
1752To write a literal \f[C]$\f[] in a template, use \f[C]$$\f[].
1754Templates may contain conditionals.
1755The syntax is as follows:
1767This will include \f[C]X\f[] in the template if \f[C]variable\f[] has a
1768non\-null value; otherwise it will include \f[C]Y\f[].
1769\f[C]X\f[] and \f[C]Y\f[] are placeholders for any valid template text,
1770and may include interpolated variables or other conditionals.
1771The \f[C]$else$\f[] section may be omitted.
1773When variables can have multiple values (for example, \f[C]author\f[] in
1774a multi\-author document), you can use the \f[C]$for$\f[] keyword:
1779<meta\ name="author"\ content="$author$"\ />
1784You can optionally specify a separator to be used between consecutive
1789$for(author)$$author$$sep$,\ $endfor$
1793A dot can be used to select a field of a variable that takes an object
1799$author.name$\ ($author.affiliation$)
1803If you use custom templates, you may need to revise them as pandoc
1805We recommend tracking the changes in the default templates, and
1806modifying your custom templates accordingly.
1807An easy way to do this is to fork the pandoc\-templates repository and
1808merge in changes after each pandoc release.
1809.SH PANDOC\[aq]S MARKDOWN
1811Pandoc understands an extended and slightly revised version of John
1812Gruber\[aq]s Markdown syntax.
1813This document explains the syntax, noting differences from standard
1815Except where noted, these differences can be suppressed by using the
1816\f[C]markdown_strict\f[] format instead of \f[C]markdown\f[].
1817An extensions can be enabled by adding \f[C]+EXTENSION\f[] to the format
1818name and disabled by adding \f[C]\-EXTENSION\f[].
1819For example, \f[C]markdown_strict+footnotes\f[] is strict Markdown with
1820footnotes enabled, while \f[C]markdown\-footnotes\-pipe_tables\f[] is
1821pandoc\[aq]s Markdown without footnotes or pipe tables.
1824Markdown is designed to be easy to write, and, even more importantly,
1828A Markdown\-formatted document should be publishable as\-is, as plain
1829text, without looking like it\[aq]s been marked up with tags or
1830formatting instructions.
1834This principle has guided pandoc\[aq]s decisions in finding syntax for
1835tables, footnotes, and other extensions.
1837There is, however, one respect in which pandoc\[aq]s aims are different
1838from the original aims of Markdown.
1839Whereas Markdown was originally designed with HTML generation in mind,
1840pandoc is designed for multiple output formats.
1841Thus, while pandoc allows the embedding of raw HTML, it discourages it,
1842and provides other, non\-HTMLish ways of representing important document
1843elements like definition lists, tables, mathematics, and footnotes.
1846A paragraph is one or more lines of text followed by one or more blank
1848Newlines are treated as spaces, so you can reflow your paragraphs as you
1850If you need a hard line break, put two or more spaces at the end of a
1852.SS Extension: \f[C]escaped_line_breaks\f[]
1854A backslash followed by a newline is also a hard line break.
1855Note: in multiline and grid table cells, this is the only way to create
1856a hard line break, since trailing spaces in the cells are ignored.
1859There are two kinds of headers: Setext and ATX.
1860.SS Setext\-style headers
1862A setext\-style header is a line of text "underlined" with a row of
1863\f[C]=\f[] signs (for a level one header) or \f[C]\-\f[] signs (for a
1868A\ level\-one\ header
1871A\ level\-two\ header
1872\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1876The header text can contain inline formatting, such as emphasis (see
1877Inline formatting, below).
1878.SS ATX\-style headers
1880An ATX\-style header consists of one to six \f[C]#\f[] signs and a line
1881of text, optionally followed by any number of \f[C]#\f[] signs.
1882The number of \f[C]#\f[] signs at the beginning of the line is the
1887##\ A\ level\-two\ header
1889###\ A\ level\-three\ header\ ###
1893As with setext\-style headers, the header text can contain formatting:
1897#\ A\ level\-one\ header\ with\ a\ [link](/url)\ and\ *emphasis*
1900.SS Extension: \f[C]blank_before_header\f[]
1902Standard Markdown syntax does not require a blank line before a header.
1903Pandoc does require this (except, of course, at the beginning of the
1905The reason for the requirement is that it is all too easy for a
1906\f[C]#\f[] to end up at the beginning of a line by accident (perhaps
1907through line wrapping).
1908Consider, for example:
1912I\ like\ several\ of\ their\ flavors\ of\ ice\ cream:
1913#22,\ for\ example,\ and\ #5.
1916.SS Header identifiers
1917.SS Extension: \f[C]header_attributes\f[]
1919Headers can be assigned attributes using this syntax at the end of the
1920line containing the header text:
1924{#identifier\ .class\ .class\ key=value\ key=value}
1928Thus, for example, the following headers will all be assigned the
1929identifier \f[C]foo\f[]:
1933#\ My\ header\ {#foo}
1935##\ My\ header\ ##\ \ \ \ {#foo}
1937My\ other\ header\ \ \ {#foo}
1938\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
1942(This syntax is compatible with PHP Markdown Extra.)
1944Note that although this syntax allows assignment of classes and
1945key/value attributes, writers generally don\[aq]t use all of this
1947Identifiers, classes, and key/value attributes are used in HTML and
1948HTML\-based formats such as EPUB and slidy.
1949Identifiers are used for labels and link anchors in the LaTeX, ConTeXt,
1950Textile, and AsciiDoc writers.
1952Headers with the class \f[C]unnumbered\f[] will not be numbered, even if
1953\f[C]\-\-number\-sections\f[] is specified.
1954A single hyphen (\f[C]\-\f[]) in an attribute context is equivalent to
1955\f[C]\&.unnumbered\f[], and preferable in non\-English documents.
1968#\ My\ header\ {.unnumbered}
1971.SS Extension: \f[C]auto_identifiers\f[]
1973A header without an explicitly specified identifier will be
1974automatically assigned a unique identifier based on the header text.
1975To derive the identifier from the header text,
1977Remove all formatting, links, etc.
1979Remove all footnotes.
1981Remove all punctuation, except underscores, hyphens, and periods.
1983Replace all spaces and newlines with hyphens.
1985Convert all alphabetic characters to lowercase.
1987Remove everything up to the first letter (identifiers may not begin with
1988a number or punctuation mark).
1990If nothing is left after this, use the identifier \f[C]section\f[].
2004\f[C]Header\ identifiers\ in\ HTML\f[]
2006\f[C]header\-identifiers\-in\-html\f[]
2009\f[C]*Dogs*?\-\-in\ *my*\ house?\f[]
2011\f[C]dogs\-\-in\-my\-house\f[]
2014\f[C][HTML],\ [S5],\ or\ [RTF]?\f[]
2016\f[C]html\-s5\-or\-rtf\f[]
2019\f[C]3.\ Applications\f[]
2021\f[C]applications\f[]
2030These rules should, in most cases, allow one to determine the identifier
2031from the header text.
2032The exception is when several headers have the same text; in this case,
2033the first will get an identifier as described above; the second will get
2034the same identifier with \f[C]\-1\f[] appended; the third with
2035\f[C]\-2\f[]; and so on.
2037These identifiers are used to provide link targets in the table of
2038contents generated by the \f[C]\-\-toc|\-\-table\-of\-contents\f[]
2040They also make it easy to provide links from one section of a document
2042A link to this section, for example, might look like this:
2046See\ the\ section\ on
2047[header\ identifiers](#header\-identifiers\-in\-html\-latex\-and\-context).
2051Note, however, that this method of providing links to sections works
2052only in HTML, LaTeX, and ConTeXt formats.
2054If the \f[C]\-\-section\-divs\f[] option is specified, then each section
2055will be wrapped in a \f[C]div\f[] (or a \f[C]section\f[], if
2056\f[C]\-\-html5\f[] was specified), and the identifier will be attached
2057to the enclosing \f[C]<div>\f[] (or \f[C]<section>\f[]) tag rather than
2059This allows entire sections to be manipulated using javascript or
2060treated differently in CSS.
2061.SS Extension: \f[C]implicit_header_references\f[]
2063Pandoc behaves as if reference links have been defined for each header.
2064So, to link to a header
2068#\ Header\ identifiers\ in\ HTML
2076[Header\ identifiers\ in\ HTML]
2084[Header\ identifiers\ in\ HTML][]
2092[the\ section\ on\ header\ identifiers][header\ identifiers\ in
2097instead of giving the identifier explicitly:
2101[Header\ identifiers\ in\ HTML](#header\-identifiers\-in\-html)
2105If there are multiple headers with identical text, the corresponding
2106reference will link to the first one only, and you will need to use
2107explicit links to link to the others, as described above.
2109Like regular reference links, these references are case\-insensitive.
2111Explicit link reference definitions always take priority over implicit
2113So, in the following example, the link will point to \f[C]bar\f[], not
2127Markdown uses email conventions for quoting blocks of text.
2128A block quotation is one or more paragraphs or other block elements
2129(such as lists or headers), with each line preceded by a \f[C]>\f[]
2130character and an optional space.
2131(The \f[C]>\f[] need not start at the left margin, but it should not be
2132indented more than three spaces.)
2136>\ This\ is\ a\ block\ quote.\ This
2137>\ paragraph\ has\ two\ lines.
2139>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote.
2144A "lazy" form, which requires the \f[C]>\f[] character only on the first
2145line of each block, is also allowed:
2149>\ This\ is\ a\ block\ quote.\ This
2150paragraph\ has\ two\ lines.
2152>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote.
2157Among the block elements that can be contained in a block quote are
2159That is, block quotes can be nested:
2163>\ This\ is\ a\ block\ quote.
2165>\ >\ A\ block\ quote\ within\ a\ block\ quote.
2169If the \f[C]>\f[] character is followed by an optional space, that space
2170will be considered part of the block quote marker and not part of the
2171indentation of the contents.
2172Thus, to put an indented code block in a block quote, you need five
2173spaces after the \f[C]>\f[]:
2180.SS Extension: \f[C]blank_before_blockquote\f[]
2182Standard Markdown syntax does not require a blank line before a block
2184Pandoc does require this (except, of course, at the beginning of the
2186The reason for the requirement is that it is all too easy for a
2187\f[C]>\f[] to end up at the beginning of a line by accident (perhaps
2188through line wrapping).
2189So, unless the \f[C]markdown_strict\f[] format is used, the following
2190does not produce a nested block quote in pandoc:
2194>\ This\ is\ a\ block\ quote.
2198.SS Verbatim (code) blocks
2199.SS Indented code blocks
2201A block of text indented four spaces (or one tab) is treated as verbatim
2202text: that is, special characters do not trigger special formatting, and
2203all spaces and line breaks are preserved.
2208\ \ \ \ if\ (a\ >\ 3)\ {
2209\ \ \ \ \ \ moveShip(5\ *\ gravity,\ DOWN);
2214The initial (four space or one tab) indentation is not considered part
2215of the verbatim text, and is removed in the output.
2217Note: blank lines in the verbatim text need not begin with four spaces.
2218.SS Fenced code blocks
2219.SS Extension: \f[C]fenced_code_blocks\f[]
2221In addition to standard indented code blocks, pandoc supports
2222\f[I]fenced\f[] code blocks.
2223These begin with a row of three or more tildes (\f[C]~\f[]) and end with
2224a row of tildes that must be at least as long as the starting row.
2225Everything between these lines is treated as code.
2226No indentation is necessary:
2232\ \ moveShip(5\ *\ gravity,\ DOWN);
2238Like regular code blocks, fenced code blocks must be separated from
2239surrounding text by blank lines.
2241If the code itself contains a row of tildes or backticks, just use a
2242longer row of tildes or backticks at the start and end:
2248code\ including\ tildes
2253.SS Extension: \f[C]backtick_code_blocks\f[]
2255Same as \f[C]fenced_code_blocks\f[], but uses backticks (\f[C]`\f[])
2256instead of tildes (\f[C]~\f[]).
2257.SS Extension: \f[C]fenced_code_attributes\f[]
2259Optionally, you may attach attributes to fenced or backtick code block
2264~~~~\ {#mycode\ .haskell\ .numberLines\ startFrom="100"}
2265qsort\ []\ \ \ \ \ =\ []
2266qsort\ (x:xs)\ =\ qsort\ (filter\ (<\ x)\ xs)\ ++\ [x]\ ++
2267\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ qsort\ (filter\ (>=\ x)\ xs)
2268~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2272Here \f[C]mycode\f[] is an identifier, \f[C]haskell\f[] and
2273\f[C]numberLines\f[] are classes, and \f[C]startFrom\f[] is an attribute
2274with value \f[C]100\f[].
2275Some output formats can use this information to do syntax highlighting.
2276Currently, the only output formats that uses this information are HTML
2278If highlighting is supported for your output format and language, then
2279the code block above will appear highlighted, with numbered lines.
2280(To see which languages are supported, do \f[C]pandoc\ \-\-version\f[].)
2281Otherwise, the code block above will appear as follows:
2285<pre\ id="mycode"\ class="haskell\ numberLines"\ startFrom="100">
2293A shortcut form can also be used for specifying the language of the code
2304This is equivalent to:
2314If the \f[C]fenced_code_attributes\f[] extension is disabled, but input
2315contains class attribute(s) for the codeblock, the first class attribute
2316will be printed after the opening fence as a bare word.
2318To prevent all highlighting, use the \f[C]\-\-no\-highlight\f[] flag.
2319To set the highlighting style, use \f[C]\-\-highlight\-style\f[].
2320For more information on highlighting, see Syntax highlighting, below.
2322.SS Extension: \f[C]line_blocks\f[]
2324A line block is a sequence of lines beginning with a vertical bar
2325(\f[C]|\f[]) followed by a space.
2326The division into lines will be preserved in the output, as will any
2327leading spaces; otherwise, the lines will be formatted as Markdown.
2328This is useful for verse and addresses:
2332|\ The\ limerick\ packs\ laughs\ anatomical
2333|\ In\ space\ that\ is\ quite\ economical.
2334|\ \ \ \ But\ the\ good\ ones\ I\[aq]ve\ seen
2335|\ \ \ \ So\ seldom\ are\ clean
2336|\ And\ the\ clean\ ones\ so\ seldom\ are\ comical
2339|\ Berkeley,\ CA\ 94718
2343The lines can be hard\-wrapped if needed, but the continuation line must
2348|\ The\ Right\ Honorable\ Most\ Venerable\ and\ Righteous\ Samuel\ L.
2351|\ Berkeley,\ CA\ 94718
2355This syntax is borrowed from reStructuredText.
2359A bullet list is a list of bulleted list items.
2360A bulleted list item begins with a bullet (\f[C]*\f[], \f[C]+\f[], or
2362Here is a simple example:
2372This will produce a "compact" list.
2373If you want a "loose" list, in which each item is formatted as a
2374paragraph, put spaces between the items:
2386The bullets need not be flush with the left margin; they may be indented
2387one, two, or three spaces.
2388The bullet must be followed by whitespace.
2390List items look best if subsequent lines are flush with the first line
2395*\ here\ is\ my\ first
2401But Markdown also allows a "lazy" format:
2405*\ here\ is\ my\ first
2410.SS The four\-space rule
2412A list item may contain multiple paragraphs and other block\-level
2414However, subsequent paragraphs must be preceded by a blank line and
2415indented four spaces or a tab.
2416The list will look better if the first paragraph is aligned with the
2421\ \ *\ First\ paragraph.
2425\ \ *\ Second\ paragraph.\ With\ a\ code\ block,\ which\ must\ be\ indented
2426\ \ \ \ eight\ spaces:
2428\ \ \ \ \ \ \ \ {\ code\ }
2432List items may include other lists.
2433In this case the preceding blank line is optional.
2434The nested list must be indented four spaces or one tab:
2440\ \ \ \ \ \ \ \ \-\ macintosh
2441\ \ \ \ \ \ \ \ \-\ red\ delicious
2450As noted above, Markdown allows you to write list items "lazily,"
2451instead of indenting continuation lines.
2452However, if there are multiple paragraphs or other blocks in a list
2453item, the first line of each must be indented.
2457+\ A\ lazy,\ lazy,\ list
2460+\ Another\ one;\ this\ looks
2463\ \ \ \ Second\ paragraph\ of\ second
2468\f[B]Note:\f[] Although the four\-space rule for continuation paragraphs
2469comes from the official Markdown syntax guide, the reference
2470implementation, \f[C]Markdown.pl\f[], does not follow it.
2471So pandoc will give different results than \f[C]Markdown.pl\f[] when
2472authors have indented continuation paragraphs fewer than four spaces.
2474The Markdown syntax guide is not explicit whether the four\-space rule
2475applies to \f[I]all\f[] block\-level content in a list item; it only
2476mentions paragraphs and code blocks.
2477But it implies that the rule applies to all block\-level content
2478(including nested lists), and pandoc interprets it that way.
2481Ordered lists work just like bulleted lists, except that the items begin
2482with enumerators rather than bullets.
2484In standard Markdown, enumerators are decimal numbers followed by a
2486The numbers themselves are ignored, so there is no difference between
2506.SS Extension: \f[C]fancy_lists\f[]
2508Unlike standard Markdown, pandoc allows ordered list items to be marked
2509with uppercase and lowercase letters and roman numerals, in addition to
2511List markers may be enclosed in parentheses or followed by a single
2512right\-parentheses or period.
2513They must be separated from the text that follows by at least one space,
2514and, if the list marker is a capital letter with a period, by at least
2517The \f[C]fancy_lists\f[] extension also allows \[aq]\f[C]#\f[]\[aq] to
2518be used as an ordered list marker in place of a numeral:
2526.SS Extension: \f[C]startnum\f[]
2528Pandoc also pays attention to the type of list marker used, and to the
2529starting number, and both of these are preserved where possible in the
2531Thus, the following yields a list with numbers followed by a single
2532parenthesis, starting with 9, and a sublist with lowercase roman
2540\ \ \ \ \ \ \ i.\ subone
2541\ \ \ \ \ \ ii.\ subtwo
2542\ \ \ \ \ iii.\ subthree
2546Pandoc will start a new list each time a different type of list marker
2548So, the following will create three lists:
2559If default list markers are desired, use \f[C]#.\f[]:
2569.SS Extension: \f[C]definition_lists\f[]
2571Pandoc supports definition lists, using the syntax of PHP Markdown Extra
2572with some extensions.
2580Term\ 2\ with\ *inline\ markup*
2584\ \ \ \ \ \ \ \ {\ some\ code,\ part\ of\ Definition\ 2\ }
2586\ \ \ \ Third\ paragraph\ of\ definition\ 2.
2590Each term must fit on one line, which may optionally be followed by a
2591blank line, and must be followed by one or more definitions.
2592A definition begins with a colon or tilde, which may be indented one or
2595A term may have multiple definitions, and each definition may consist of
2596one or more block elements (paragraph, code block, list, etc.), each
2597indented four spaces or one tab stop.
2598The body of the definition (including the first line, aside from the
2599colon or tilde) should be indented four spaces.
2600However, as with other Markdown lists, you can "lazily" omit indentation
2601except at the beginning of a paragraph or other block element:
2608with\ lazy\ continuation.
2610\ \ \ \ Second\ paragraph\ of\ the\ definition.
2614If you leave space before the definition (as in the example above), the
2615text of the definition will be treated as a paragraph.
2616In some output formats, this will mean greater spacing between
2617term/definition pairs.
2618For a more compact definition list, omit the space before the
2627\ \ ~\ Definition\ 2a
2628\ \ ~\ Definition\ 2b
2632Note that space between items in a definition list is required.
2633(A variant that loosens this requirement, but disallows "lazy" hard
2634wrapping, can be activated with \f[C]compact_definition_lists\f[]: see
2635Non\-pandoc extensions, below.)
2636.SS Numbered example lists
2637.SS Extension: \f[C]example_lists\f[]
2639The special list marker \f[C]\@\f[] can be used for sequentially
2641The first list item with a \f[C]\@\f[] marker will be numbered
2642\[aq]1\[aq], the next \[aq]2\[aq], and so on, throughout the document.
2643The numbered examples need not occur in a single list; each new list
2644using \f[C]\@\f[] will take up where the last stopped.
2649(\@)\ \ My\ first\ example\ will\ be\ numbered\ (1).
2650(\@)\ \ My\ second\ example\ will\ be\ numbered\ (2).
2652Explanation\ of\ examples.
2654(\@)\ \ My\ third\ example\ will\ be\ numbered\ (3).
2658Numbered examples can be labeled and referred to elsewhere in the
2663(\@good)\ \ This\ is\ a\ good\ example.
2665As\ (\@good)\ illustrates,\ ...
2669The label can be any string of alphanumeric characters, underscores, or
2671.SS Compact and loose lists
2673Pandoc behaves differently from \f[C]Markdown.pl\f[] on some "edge
2674cases" involving lists.
2675Consider this source:
2689Pandoc transforms this into a "compact list" (with no \f[C]<p>\f[] tags
2690around "First", "Second", or "Third"), while Markdown puts \f[C]<p>\f[]
2691tags around "Second" and "Third" (but not "First"), because of the blank
2692space around "Third".
2693Pandoc follows a simple rule: if the text is followed by a blank line,
2694it is treated as a paragraph.
2695Since "Second" is followed by a list, and not a blank line, it isn\[aq]t
2696treated as a paragraph.
2697The fact that the list is followed by a blank line is irrelevant.
2698(Note: Pandoc works this way even when the \f[C]markdown_strict\f[]
2700This behavior is consistent with the official Markdown syntax
2701description, even though it is different from that of
2702\f[C]Markdown.pl\f[].)
2705What if you want to put an indented code block after a list?
2712\ \ \ \ {\ my\ code\ block\ }
2716Trouble! Here pandoc (like other Markdown implementations) will treat
2717\f[C]{\ my\ code\ block\ }\f[] as the second paragraph of item two, and
2720To "cut off" the list after item two, you can insert some non\-indented
2721content, like an HTML comment, which won\[aq]t produce visible output in
2729<!\-\-\ end\ of\ list\ \-\->
2731\ \ \ \ {\ my\ code\ block\ }
2735You can use the same trick if you want two consecutive lists instead of
2753A line containing a row of three or more \f[C]*\f[], \f[C]\-\f[], or
2754\f[C]_\f[] characters (optionally separated by spaces) produces a
2761\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
2766Four kinds of tables may be used.
2767The first three kinds presuppose the use of a fixed\-width font, such as
2769The fourth kind can be used with proportionally spaced fonts, as it does
2770not require lining up columns.
2771.SS Extension: \f[C]table_captions\f[]
2773A caption may optionally be provided with all 4 kinds of tables (as
2774illustrated in the examples below).
2775A caption is a paragraph beginning with the string \f[C]Table:\f[] (or
2776just \f[C]:\f[]), which will be stripped off.
2777It may appear either before or after the table.
2778.SS Extension: \f[C]simple_tables\f[]
2780Simple tables look like this:
2784\ \ Right\ \ \ \ \ Left\ \ \ \ \ Center\ \ \ \ \ Default
2785\-\-\-\-\-\-\-\ \ \ \ \ \-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\ \ \ \-\-\-\-\-\-\-
2786\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ 12
2787\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ 123
2788\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ 1
2790Table:\ \ Demonstration\ of\ simple\ table\ syntax.
2794The headers and table rows must each fit on one line.
2795Column alignments are determined by the position of the header text
2796relative to the dashed line below it:
2798If the dashed line is flush with the header text on the right side but
2799extends beyond it on the left, the column is right\-aligned.
2801If the dashed line is flush with the header text on the left side but
2802extends beyond it on the right, the column is left\-aligned.
2804If the dashed line extends beyond the header text on both sides, the
2807If the dashed line is flush with the header text on both sides, the
2808default alignment is used (in most cases, this will be left).
2810The table must end with a blank line, or a line of dashes followed by a
2813The column headers may be omitted, provided a dashed line is used to end
2819\-\-\-\-\-\-\-\ \ \ \ \ \-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\ \ \ \-\-\-\-\-\-\-
2820\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ \ 12
2821\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ \ 123
2822\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ 1
2823\-\-\-\-\-\-\-\ \ \ \ \ \-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\ \ \ \-\-\-\-\-\-\-
2827When headers are omitted, column alignments are determined on the basis
2828of the first line of the table body.
2829So, in the tables above, the columns would be right, left, center, and
2830right aligned, respectively.
2831.SS Extension: \f[C]multiline_tables\f[]
2833Multiline tables allow headers and table rows to span multiple lines of
2834text (but cells that span multiple columns or rows of the table are not
2840\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
2841\ Centered\ \ \ Default\ \ \ \ \ \ \ \ \ \ \ Right\ Left
2842\ \ Header\ \ \ \ Aligned\ \ \ \ \ \ \ \ \ Aligned\ Aligned
2843\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
2844\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that
2845\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines.
2847\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note
2848\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between
2849\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.
2850\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
2852Table:\ Here\[aq]s\ the\ caption.\ It,\ too,\ may\ span
2857These work like simple tables, but with the following differences:
2859They must begin with a row of dashes, before the header text (unless the
2860headers are omitted).
2862They must end with a row of dashes, then a blank line.
2864The rows must be separated by blank lines.
2866In multiline tables, the table parser pays attention to the widths of
2867the columns, and the writers try to reproduce these relative widths in
2869So, if you find that one of the columns is too narrow in the output, try
2870widening it in the Markdown source.
2872Headers may be omitted in multiline tables as well as simple tables:
2876\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
2877\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that
2878\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines.
2880\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note
2881\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between
2882\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.
2883\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
2885:\ Here\[aq]s\ a\ multiline\ table\ without\ headers.
2889It is possible for a multiline table to have just one row, but the row
2890should be followed by a blank line (and then the row of dashes that ends
2891the table), or the table may be interpreted as a simple table.
2892.SS Extension: \f[C]grid_tables\f[]
2894Grid tables look like this:
2898:\ Sample\ grid\ table.
2900+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
2901|\ Fruit\ \ \ \ \ \ \ \ \ |\ Price\ \ \ \ \ \ \ \ \ |\ Advantages\ \ \ \ \ \ \ \ \ |
2902+===============+===============+====================+
2903|\ Bananas\ \ \ \ \ \ \ |\ $1.34\ \ \ \ \ \ \ \ \ |\ \-\ built\-in\ wrapper\ |
2904|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \-\ bright\ color\ \ \ \ \ |
2905+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
2906|\ Oranges\ \ \ \ \ \ \ |\ $2.10\ \ \ \ \ \ \ \ \ |\ \-\ cures\ scurvy\ \ \ \ \ |
2907|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \-\ tasty\ \ \ \ \ \ \ \ \ \ \ \ |
2908+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
2912The row of \f[C]=\f[]s separates the header from the table body, and can
2913be omitted for a headerless table.
2914The cells of grid tables may contain arbitrary block elements (multiple
2915paragraphs, code blocks, lists, etc.).
2916Alignments are not supported, nor are cells that span multiple columns
2918Grid tables can be created easily using Emacs table mode.
2919.SS Extension: \f[C]pipe_tables\f[]
2921Pipe tables look like this:
2925|\ Right\ |\ Left\ |\ Default\ |\ Center\ |
2926|\-\-\-\-\-\-:|:\-\-\-\-\-|\-\-\-\-\-\-\-\-\-|:\-\-\-\-\-\-:|
2927|\ \ \ 12\ \ |\ \ 12\ \ |\ \ \ \ 12\ \ \ |\ \ \ \ 12\ \ |
2928|\ \ 123\ \ |\ \ 123\ |\ \ \ 123\ \ \ |\ \ \ 123\ \ |
2929|\ \ \ \ 1\ \ |\ \ \ \ 1\ |\ \ \ \ \ 1\ \ \ |\ \ \ \ \ 1\ \ |
2931\ \ :\ Demonstration\ of\ pipe\ table\ syntax.
2935The syntax is identical to PHP Markdown Extra tables.
2936The beginning and ending pipe characters are optional, but pipes are
2937required between all columns.
2938The colons indicate column alignment as shown.
2939The header cannot be omitted.
2940To simulate a headerless table, include a header with blank cells.
2942Since the pipes indicate column boundaries, columns need not be
2943vertically aligned, as they are in the above example.
2944So, this is a perfectly legal (though ugly) pipe table:
2949\-\-\-\-\-|\-\-\-\-\-:
2956The cells of pipe tables cannot contain block elements like paragraphs
2957and lists, and cannot span multiple lines.
2958If a pipe table contains a row whose printable content is wider than the
2959column width (see \f[C]\-\-columns\f[]), then the cell contents will
2960wrap, with the relative cell widths determined by the widths of the
2963Note: pandoc also recognizes pipe tables of the following form, as can
2964be produced by Emacs\[aq] orgtbl\-mode:
2968|\ One\ |\ Two\ \ \ |
2969|\-\-\-\-\-+\-\-\-\-\-\-\-|
2971|\ is\ \ |\ nice\ \ |
2975The difference is that \f[C]+\f[] is used instead of \f[C]|\f[].
2976Other orgtbl features are not supported.
2977In particular, to get non\-default column alignment, you\[aq]ll need to
2980.SS Extension: \f[C]pandoc_title_block\f[]
2982If the file begins with a title block
2987%\ author(s)\ (separated\ by\ semicolons)
2992it will be parsed as bibliographic information, not regular text.
2993(It will be used, for example, in the title of standalone LaTeX or HTML
2994output.) The block may contain just a title, a title and an author, or
2996If you want to include an author but no title, or a title and a date but
2997no author, you need a blank line:
3010The title may occupy multiple lines, but continuation lines must begin
3011with leading space, thus:
3016\ \ on\ multiple\ lines
3020If a document has multiple authors, the authors may be put on separate
3021lines with leading space, or separated by semicolons, or both.
3022So, all of the following are equivalent:
3029%\ Author\ One;\ Author\ Two
3036The date must fit on one line.
3038All three metadata fields may contain standard inline formatting
3039(italics, links, footnotes, etc.).
3041Title blocks will always be parsed, but they will affect the output only
3042when the \f[C]\-\-standalone\f[] (\f[C]\-s\f[]) option is chosen.
3043In HTML output, titles will appear twice: once in the document head \-\-
3044this is the title that will appear at the top of the window in a browser
3045\-\- and once at the beginning of the document body.
3046The title in the document head can have an optional prefix attached
3047(\f[C]\-\-title\-prefix\f[] or \f[C]\-T\f[] option).
3048The title in the body appears as an H1 element with class "title", so it
3049can be suppressed or reformatted with CSS.
3050If a title prefix is specified with \f[C]\-T\f[] and no title block
3051appears in the document, the title prefix will be used by itself as the
3054The man page writer extracts a title, man page section number, and other
3055header and footer information from the title line.
3056The title is assumed to be the first word on the title line, which may
3057optionally end with a (single\-digit) section number in parentheses.
3058(There should be no space between the title and the parentheses.)
3059Anything after this is assumed to be additional footer and header text.
3060A single pipe character (\f[C]|\f[]) should be used to separate the
3061footer text from the header text.
3070will yield a man page with the title \f[C]PANDOC\f[] and section 1.
3074%\ PANDOC(1)\ Pandoc\ User\ Manuals
3078will also have "Pandoc User Manuals" in the footer.
3082%\ PANDOC(1)\ Pandoc\ User\ Manuals\ |\ Version\ 4.0
3086will also have "Version 4.0" in the header.
3087.SS Extension: \f[C]yaml_metadata_block\f[]
3089A YAML metadata block is a valid YAML object, delimited by a line of
3090three hyphens (\f[C]\-\-\-\f[]) at the top and a line of three hyphens
3091(\f[C]\-\-\-\f[]) or three dots (\f[C]\&...\f[]) at the bottom.
3092A YAML metadata block may occur anywhere in the document, but if it is
3093not at the beginning, it must be preceded by a blank line.
3094(Note that, because of the way pandoc concatenates input files when
3095several are provided, you may also keep the metadata in a separate YAML
3096file and pass it to pandoc as an argument, along with your Markdown
3101pandoc\ chap1.md\ chap2.md\ chap3.md\ metadata.yaml\ \-s\ \-o\ book.html
3105Just be sure that the YAML file begins with \f[C]\-\-\-\f[] and ends
3106with \f[C]\-\-\-\f[] or \f[C]\&...\f[].)
3108Metadata will be taken from the fields of the YAML object and added to
3109any existing document metadata.
3110Metadata can contain lists and objects (nested arbitrarily), but all
3111string scalars will be interpreted as Markdown.
3112Fields with names ending in an underscore will be ignored by pandoc.
3113(They may be given a role by external processors.)
3115A document may contain multiple metadata blocks.
3116The metadata fields will be combined through a \f[I]left\-biased
3117union\f[]: if two metadata blocks attempt to set the same field, the
3118value from the first block will be taken.
3120When pandoc is used with \f[C]\-t\ markdown\f[] to create a Markdown
3121document, a YAML metadata block will be produced only if the
3122\f[C]\-s/\-\-standalone\f[] option is used.
3123All of the metadata will appear in a single block at the beginning of
3126Note that YAML escaping rules must be followed.
3127Thus, for example, if a title contains a colon, it must be quoted.
3128The pipe character (\f[C]|\f[]) can be used to begin an indented block
3129that will be interpreted literally, without need for escaping.
3130This form is necessary when the field contains blank lines:
3135title:\ \ \[aq]This\ is\ the\ title:\ it\ contains\ a\ colon\[aq]
3139tags:\ [nothing,\ nothingness]
3141\ \ This\ is\ the\ abstract.
3143\ \ It\ consists\ of\ two\ paragraphs.
3148Template variables will be set automatically from the metadata.
3149Thus, for example, in writing HTML, the variable \f[C]abstract\f[] will
3150be set to the HTML equivalent of the Markdown in the \f[C]abstract\f[]
3155<p>This\ is\ the\ abstract.</p>
3156<p>It\ consists\ of\ two\ paragraphs.</p>
3160Variables can contain arbitrary YAML structures, but the template must
3161match this structure.
3162The \f[C]author\f[] variable in the default templates expects a simple
3163list or string, but can be changed to support more complicated
3165The following combination, for example, would add an affiliation to the
3166author if one is given:
3171title:\ The\ document\ title
3173\-\ name:\ Author\ One
3174\ \ affiliation:\ University\ of\ Somewhere
3175\-\ name:\ Author\ Two
3176\ \ affiliation:\ University\ of\ Nowhere
3181To use the structured authors in the example above, you would need a
3188$author.name$$if(author.affiliation)$\ ($author.affiliation$)$endif$
3195.SS Backslash escapes
3196.SS Extension: \f[C]all_symbols_escapable\f[]
3198Except inside a code block or inline code, any punctuation or space
3199character preceded by a backslash will be treated literally, even if it
3200would normally indicate formatting.
3201Thus, for example, if one writes
3221<strong>hello</strong>
3225This rule is easier to remember than standard Markdown\[aq]s rule, which
3226allows only the following characters to be backslash\-escaped:
3234(However, if the \f[C]markdown_strict\f[] format is used, the standard
3235Markdown rule will be used.)
3237A backslash\-escaped space is parsed as a nonbreaking space.
3238It will appear in TeX output as \f[C]~\f[] and in HTML and XML as
3239\f[C]\\ \f[] or \f[C]\\ \f[].
3241A backslash\-escaped newline (i.e.
3242a backslash occurring at the end of a line) is parsed as a hard line
3244It will appear in TeX output as \f[C]\\\\\f[] and in HTML as
3246This is a nice alternative to Markdown\[aq]s "invisible" way of
3247indicating hard line breaks using two trailing spaces on a line.
3249Backslash escapes do not work in verbatim contexts.
3250.SS Smart punctuation
3253If the \f[C]\-\-smart\f[] option is specified, pandoc will produce
3254typographically correct output, converting straight quotes to curly
3255quotes, \f[C]\-\-\-\f[] to em\-dashes, \f[C]\-\-\f[] to en\-dashes, and
3256\f[C]\&...\f[] to ellipses.
3257Nonbreaking spaces are inserted after certain abbreviations, such as
3260Note: if your LaTeX template or any included header file call for the
3261\f[C]csquotes\f[] package, pandoc will detect this automatically and use
3262\f[C]\\enquote{...}\f[] for quoted text.
3263.SS Inline formatting
3266To \f[I]emphasize\f[] some text, surround it with \f[C]*\f[]s or
3267\f[C]_\f[], like this:
3271This\ text\ is\ _emphasized\ with\ underscores_,\ and\ this
3272is\ *emphasized\ with\ asterisks*.
3276Double \f[C]*\f[] or \f[C]_\f[] produces \f[B]strong emphasis\f[]:
3280This\ is\ **strong\ emphasis**\ and\ __with\ underscores__.
3284A \f[C]*\f[] or \f[C]_\f[] character surrounded by spaces, or
3285backslash\-escaped, will not trigger emphasis:
3289This\ is\ *\ not\ emphasized\ *,\ and\ \\*neither\ is\ this\\*.
3292.SS Extension: \f[C]intraword_underscores\f[]
3294Because \f[C]_\f[] is sometimes used inside words and identifiers,
3295pandoc does not interpret a \f[C]_\f[] surrounded by alphanumeric
3296characters as an emphasis marker.
3297If you want to emphasize just part of a word, use \f[C]*\f[]:
3301feas*ible*,\ not\ feas*able*.
3305.SS Extension: \f[C]strikeout\f[]
3307To strikeout a section of text with a horizontal line, begin and end it
3313This\ ~~is\ deleted\ text.~~
3316.SS Superscripts and subscripts
3317.SS Extension: \f[C]superscript\f[], \f[C]subscript\f[]
3319Superscripts may be written by surrounding the superscripted text by
3320\f[C]^\f[] characters; subscripts may be written by surrounding the
3321subscripted text by \f[C]~\f[] characters.
3326H~2~O\ is\ a\ liquid.\ \ 2^10^\ is\ 1024.
3330If the superscripted or subscripted text contains spaces, these spaces
3331must be escaped with backslashes.
3332(This is to prevent accidental superscripting and subscripting through
3333the ordinary use of \f[C]~\f[] and \f[C]^\f[].) Thus, if you want the
3334letter P with \[aq]a cat\[aq] in subscripts, use \f[C]P~a\\\ cat~\f[],
3335not \f[C]P~a\ cat~\f[].
3338To make a short span of text verbatim, put it inside backticks:
3342What\ is\ the\ difference\ between\ `>>=`\ and\ `>>`?
3346If the verbatim text includes a backtick, use double backticks:
3350Here\ is\ a\ literal\ backtick\ ``\ `\ ``.
3354(The spaces after the opening backticks and before the closing backticks
3357The general rule is that a verbatim span starts with a string of
3358consecutive backticks (optionally followed by a space) and ends with a
3359string of the same number of backticks (optionally preceded by a space).
3361Note that backslash\-escapes (and other Markdown constructs) do not work
3362in verbatim contexts:
3366This\ is\ a\ backslash\ followed\ by\ an\ asterisk:\ `\\*`.
3369.SS Extension: \f[C]inline_code_attributes\f[]
3371Attributes can be attached to verbatim text, just as with fenced code
3381To write small caps, you can use an HTML span tag:
3385<span\ style="font\-variant:small\-caps;">Small\ caps</span>
3389(The semicolon is optional and there may be space after the colon.) This
3390will work in all output formats that support small caps.
3392Alternatively, you can also use the new \f[C]bracketed_spans\f[] syntax:
3396[Small\ caps]{style="font\-variant:small\-caps;"}
3400.SS Extension: \f[C]tex_math_dollars\f[]
3402Anything between two \f[C]$\f[] characters will be treated as TeX math.
3403The opening \f[C]$\f[] must have a non\-space character immediately to
3404its right, while the closing \f[C]$\f[] must have a non\-space character
3405immediately to its left, and must not be followed immediately by a
3407Thus, \f[C]$20,000\ and\ $30,000\f[] won\[aq]t parse as math.
3408If for some reason you need to enclose text in literal \f[C]$\f[]
3409characters, backslash\-escape them and they won\[aq]t be treated as math
3412TeX math will be printed in all output formats.
3413How it is rendered depends on the output format:
3415.B Markdown, LaTeX, Emacs Org mode, ConTeXt, ZimWiki
3416It will appear verbatim between \f[C]$\f[] characters.
3421It will be rendered using an interpreted text role \f[C]:math:\f[].
3426It will be rendered as \f[C]latexmath:[...]\f[].
3431It will be rendered inside a \f[C]\@math\f[] command.
3436It will be rendered verbatim without \f[C]$\f[]\[aq]s.
3440.B MediaWiki, DokuWiki
3441It will be rendered inside \f[C]<math>\f[] tags.
3446It will be rendered inside \f[C]<span\ class="math">\f[] tags.
3450.B RTF, OpenDocument, ODT
3451It will be rendered, if possible, using unicode characters, and will
3452otherwise appear verbatim.
3457If the \f[C]\-\-mathml\f[] flag is used, it will be rendered using
3458MathML in an \f[C]inlineequation\f[] or \f[C]informalequation\f[] tag.
3459Otherwise it will be rendered, if possible, using unicode characters.
3464It will be rendered using OMML math markup.
3469If the \f[C]\-\-webtex\f[] option is used, formulas are rendered as
3470images using CodeCogs or other compatible web service, downloaded and
3471embedded in the e\-book.
3472Otherwise, they will appear verbatim.
3476.B HTML, Slidy, DZSlides, S5, EPUB
3477The way math is rendered in HTML will depend on the command\-line
3481The default is to render TeX math as far as possible using unicode
3482characters, as with RTF, DocBook, and OpenDocument output.
3483Formulas are put inside a \f[C]span\f[] with \f[C]class="math"\f[], so
3484that they may be styled differently from the surrounding text if needed.
3486If the \f[C]\-\-latexmathml\f[] option is used, TeX math will be
3487displayed between \f[C]$\f[] or \f[C]$$\f[] characters and put in
3488\f[C]<span>\f[] tags with class \f[C]LaTeX\f[].
3489The LaTeXMathML script will be used to render it as formulas.
3490(This trick does not work in all browsers, but it works in Firefox.
3491In browsers that do not support LaTeXMathML, TeX math will appear
3492verbatim between \f[C]$\f[] characters.)
3494If the \f[C]\-\-jsmath\f[] option is used, TeX math will be put inside
3495\f[C]<span>\f[] tags (for inline math) or \f[C]<div>\f[] tags (for
3496display math) with class \f[C]math\f[].
3497The jsMath script will be used to render it.
3499If the \f[C]\-\-mimetex\f[] option is used, the mimeTeX CGI script will
3500be called to generate images for each TeX formula.
3501This should work in all browsers.
3502The \f[C]\-\-mimetex\f[] option takes an optional URL as argument.
3503If no URL is specified, it will be assumed that the mimeTeX CGI script
3504is at \f[C]/cgi\-bin/mimetex.cgi\f[].
3506If the \f[C]\-\-gladtex\f[] option is used, TeX formulas will be
3507enclosed in \f[C]<eq>\f[] tags in the HTML output.
3508The resulting \f[C]htex\f[] file may then be processed by gladTeX, which
3509will produce image files for each formula and an HTML file with links to
3511So, the procedure is:
3516pandoc\ \-s\ \-\-gladtex\ myfile.txt\ \-o\ myfile.htex
3517gladtex\ \-d\ myfile\-images\ myfile.htex
3518#\ produces\ myfile.html\ and\ images\ in\ myfile\-images
3523If the \f[C]\-\-webtex\f[] option is used, TeX formulas will be
3524converted to \f[C]<img>\f[] tags that link to an external script that
3525converts formulas to images.
3526The formula will be URL\-encoded and concatenated with the URL provided.
3527If no URL is specified, the CodeCogs will be used
3528(\f[C]https://latex.codecogs.com/png.latex?\f[]).
3530If the \f[C]\-\-mathjax\f[] option is used, TeX math will be displayed
3531between \f[C]\\(...\\)\f[] (for inline math) or \f[C]\\[...\\]\f[] (for
3532display math) and put in \f[C]<span>\f[] tags with class \f[C]math\f[].
3533The MathJax script will be used to render it as formulas.
3536.SS Extension: \f[C]raw_html\f[]
3538Markdown allows you to insert raw HTML (or DocBook) anywhere in a
3539document (except verbatim contexts, where \f[C]<\f[], \f[C]>\f[], and
3540\f[C]&\f[] are interpreted literally).
3541(Technically this is not an extension, since standard Markdown allows
3542it, but it has been made an extension so that it can be disabled if
3545The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,
3546DZSlides, EPUB, Markdown, Emacs Org mode, and Textile output, and
3547suppressed in other formats.
3548.SS Extension: \f[C]markdown_in_html_blocks\f[]
3550Standard Markdown allows you to include HTML "blocks": blocks of HTML
3551between balanced tags that are separated from the surrounding text with
3552blank lines, and start and end at the left margin.
3553Within these blocks, everything is interpreted as HTML, not Markdown; so
3554(for example), \f[C]*\f[] does not signify emphasis.
3556Pandoc behaves this way when the \f[C]markdown_strict\f[] format is
3557used; but by default, pandoc interprets material between HTML block tags
3559Thus, for example, pandoc will turn
3566<td>[a\ link](http://google.com)</td>
3578<td><em>one</em></td>
3579<td><a\ href="http://google.com">a\ link</a></td>
3585whereas \f[C]Markdown.pl\f[] will preserve it as is.
3587There is one exception to this rule: text between \f[C]<script>\f[] and
3588\f[C]<style>\f[] tags is not interpreted as Markdown.
3590This departure from standard Markdown should make it easier to mix
3591Markdown with HTML block elements.
3592For example, one can surround a block of Markdown text with
3593\f[C]<div>\f[] tags without preventing it from being interpreted as
3595.SS Extension: \f[C]native_divs\f[]
3597Use native pandoc \f[C]Div\f[] blocks for content inside \f[C]<div>\f[]
3599For the most part this should give the same output as
3600\f[C]markdown_in_html_blocks\f[], but it makes it easier to write pandoc
3601filters to manipulate groups of blocks.
3602.SS Extension: \f[C]native_spans\f[]
3604Use native pandoc \f[C]Span\f[] blocks for content inside
3605\f[C]<span>\f[] tags.
3606For the most part this should give the same output as \f[C]raw_html\f[],
3607but it makes it easier to write pandoc filters to manipulate groups of
3610.SS Extension: \f[C]raw_tex\f[]
3612In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
3613included in a document.
3614Inline TeX commands will be preserved and passed unchanged to the LaTeX
3616Thus, for example, you can use LaTeX to include BibTeX citations:
3620This\ result\ was\ proved\ in\ \\cite{jones.1967}.
3624Note that in LaTeX environments, like
3628\\begin{tabular}{|l|l|}\\hline
3629Age\ &\ Frequency\ \\\\\ \\hline
363018\-\-25\ \ &\ 15\ \\\\
363126\-\-35\ \ &\ 33\ \\\\
363236\-\-45\ \ &\ 22\ \\\\\ \\hline
3637the material between the begin and end tags will be interpreted as raw
3638LaTeX, not as Markdown.
3640Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
3641Emacs Org mode, and ConTeXt.
3643.SS Extension: \f[C]latex_macros\f[]
3645For output formats other than LaTeX, pandoc will parse LaTeX
3646\f[C]\\newcommand\f[] and \f[C]\\renewcommand\f[] definitions and apply
3647the resulting macros to all LaTeX math.
3648So, for example, the following will work in all output formats, not just
3653\\newcommand{\\tuple}[1]{\\langle\ #1\ \\rangle}
3659In LaTeX output, the \f[C]\\newcommand\f[] definition will simply be
3660passed unchanged to the output.
3663Markdown allows links to be specified in several ways.
3666If you enclose a URL or email address in pointy brackets, it will become
3672<sam\@green.eggs.ham>
3677An inline link consists of the link text in square brackets, followed by
3678the URL in parentheses.
3679(Optionally, the URL can be followed by a link title, in quotes.)
3683This\ is\ an\ [inline\ link](/url),\ and\ here\[aq]s\ [one\ with
3684a\ title](http://fsf.org\ "click\ here\ for\ a\ good\ time!").
3688There can be no space between the bracketed part and the parenthesized
3690The link text can contain formatting (such as emphasis), but the title
3693Email addresses in inline links are not autodetected, so they have to be
3694prefixed with \f[C]mailto\f[]:
3698[Write\ me!](mailto:sam\@green.eggs.ham)
3703An \f[I]explicit\f[] reference link has two parts, the link itself and
3704the link definition, which may occur elsewhere in the document (either
3705before or after the link).
3707The link consists of link text in square brackets, followed by a label
3709(There can be space between the two.) The link definition consists of
3710the bracketed label, followed by a colon and a space, followed by the
3711URL, and optionally (after a space) a link title either in quotes or in
3713The label must not be parseable as a citation (assuming the
3714\f[C]citations\f[] extension is enabled): citations take precedence over
3717Here are some examples:
3721[my\ label\ 1]:\ /foo/bar.html\ \ "My\ title,\ optional"
3722[my\ label\ 2]:\ /foo
3723[my\ label\ 3]:\ http://fsf.org\ (The\ free\ software\ foundation)
3724[my\ label\ 4]:\ /bar#special\ \ \[aq]A\ title\ in\ single\ quotes\[aq]
3728The URL may optionally be surrounded by angle brackets:
3732[my\ label\ 5]:\ <http://foo.bar.baz>
3736The title may go on the next line:
3740[my\ label\ 3]:\ http://fsf.org
3741\ \ "The\ free\ software\ foundation"
3745Note that link labels are not case sensitive.
3750Here\ is\ [my\ link][FOO]
3756In an \f[I]implicit\f[] reference link, the second pair of brackets is
3761See\ [my\ website][].
3763[my\ website]:\ http://foo.bar.baz
3767Note: In \f[C]Markdown.pl\f[] and most other Markdown implementations,
3768reference link definitions cannot occur in nested constructions such as
3769list items or block quotes.
3770Pandoc lifts this arbitrary seeming restriction.
3771So the following is fine in pandoc, though not in most other
3776>\ My\ block\ [quote].
3781.SS Extension: \f[C]shortcut_reference_links\f[]
3783In a \f[I]shortcut\f[] reference link, the second pair of brackets may
3790[my\ website]:\ http://foo.bar.baz
3795To link to another section of the same document, use the automatically
3796generated identifier (see Header identifiers).
3801See\ the\ [Introduction](#introduction).
3809See\ the\ [Introduction].
3811[Introduction]:\ #introduction
3815Internal links are currently supported for HTML formats (including HTML
3816slide shows and EPUB), LaTeX, and ConTeXt.
3819A link immediately preceded by a \f[C]!\f[] will be treated as an image.
3820The link text will be used as the image\[aq]s alt text:
3824
3828[movie\ reel]:\ movie.gif
3831.SS Extension: \f[C]implicit_figures\f[]
3833An image occurring by itself in a paragraph will be rendered as a figure
3834with a caption. (In LaTeX, a figure environment will be used; in HTML,
3835the image will be placed in a \f[C]div\f[] with class \f[C]figure\f[],
3836together with a caption in a \f[C]p\f[] with class \f[C]caption\f[].)
3837The image\[aq]s alt text will be used as the caption.
3841
3845If you just want a regular inline image, just make sure it is not the
3846only thing in the paragraph.
3847One way to do this is to insert a nonbreaking space after the image:
3851![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\\
3854.SS Extension: \f[C]link_attributes\f[]
3856Attributes can be set on links and images:
3860An\ inline\ {#id\ .class\ width=30\ height=20px}
3861and\ a\ reference\ ![image][ref]\ with\ attributes.
3863[ref]:\ foo.jpg\ "optional\ title"\ {#id\ .class\ key=val\ key2="val\ 2"}
3867(This syntax is compatible with PHP Markdown Extra when only
3868\f[C]#id\f[] and \f[C]\&.class\f[] are used.)
3870For HTML and EPUB, all attributes except \f[C]width\f[] and
3871\f[C]height\f[] (but including \f[C]srcset\f[] and \f[C]sizes\f[]) are
3872passed through as is.
3873The other writers ignore attributes that are not supported by their
3876The \f[C]width\f[] and \f[C]height\f[] attributes on images are treated
3878When used without a unit, the unit is assumed to be pixels.
3879However, any of the following unit identifiers can be used: \f[C]px\f[],
3880\f[C]cm\f[], \f[C]mm\f[], \f[C]in\f[], \f[C]inch\f[] and \f[C]%\f[].
3881There must not be any spaces between the number and the unit.
3886{\ width=50%\ }
3890Dimensions are converted to inches for output in page\-based formats
3892Dimensions are converted to pixels for output in HTML\-like formats.
3893Use the \f[C]\-\-dpi\f[] option to specify the number of pixels per
3895The default is 96dpi.
3897The \f[C]%\f[] unit is generally relative to some available space.
3898For example the above example will render to
3899\f[C]<img\ href="file.jpg"\ style="width:\ 50%;"\ />\f[] (HTML),
3900\f[C]\\includegraphics[width=0.5\\textwidth]{file.jpg}\f[] (LaTeX), or
3901\f[C]\\externalfigure[file.jpg][width=0.5\\textwidth]\f[] (ConTeXt).
3903Some output formats have a notion of a class (ConTeXt) or a unique
3904identifier (LaTeX \f[C]\\caption\f[]), or both (HTML).
3906When no \f[C]width\f[] or \f[C]height\f[] attributes are specified, the
3907fallback is to look at the image resolution and the dpi metadata
3908embedded in the image file.
3910.SS Extension: \f[C]bracketed_spans\f[]
3912A bracketed sequence of inlines, as one would use to begin a link, will
3913be treated as a span with attributes if it is followed immediately by
3918[This\ is\ *some\ text*]{.class\ key="val"}
3922.SS Extension: \f[C]footnotes\f[]
3924Pandoc\[aq]s Markdown allows footnotes, using the following syntax:
3928Here\ is\ a\ footnote\ reference,[^1]\ and\ another.[^longnote]
3930[^1]:\ Here\ is\ the\ footnote.
3932[^longnote]:\ Here\[aq]s\ one\ with\ multiple\ blocks.
3934\ \ \ \ Subsequent\ paragraphs\ are\ indented\ to\ show\ that\ they
3935belong\ to\ the\ previous\ footnote.
3937\ \ \ \ \ \ \ \ {\ some.code\ }
3939\ \ \ \ The\ whole\ paragraph\ can\ be\ indented,\ or\ just\ the\ first
3940\ \ \ \ line.\ \ In\ this\ way,\ multi\-paragraph\ footnotes\ work\ like
3941\ \ \ \ multi\-paragraph\ list\ items.
3943This\ paragraph\ won\[aq]t\ be\ part\ of\ the\ note,\ because\ it
3948The identifiers in footnote references may not contain spaces, tabs, or
3950These identifiers are used only to correlate the footnote reference with
3951the note itself; in the output, footnotes will be numbered sequentially.
3953The footnotes themselves need not be placed at the end of the document.
3954They may appear anywhere except inside other block elements (lists,
3955block quotes, tables, etc.).
3956.SS Extension: \f[C]inline_notes\f[]
3958Inline footnotes are also allowed (though, unlike regular notes, they
3959cannot contain multiple paragraphs).
3960The syntax is as follows:
3964Here\ is\ an\ inline\ note.^[Inlines\ notes\ are\ easier\ to\ write,\ since
3965you\ don\[aq]t\ have\ to\ pick\ an\ identifier\ and\ move\ down\ to\ type\ the
3970Inline and regular footnotes may be mixed freely.
3972.SS Extension: \f[C]citations\f[]
3974Using an external filter, \f[C]pandoc\-citeproc\f[], pandoc can
3975automatically generate citations and a bibliography in a number of
3981pandoc\ \-\-filter\ pandoc\-citeproc\ myinput.txt
3985In order to use this feature, you will need to specify a bibliography
3986file using the \f[C]bibliography\f[] metadata field in a YAML metadata
3987section, or \f[C]\-\-bibliography\f[] command line argument.
3988You can supply multiple \f[C]\-\-bibliography\f[] arguments or set
3989\f[C]bibliography\f[] metadata field to YAML array, if you want to use
3990multiple bibliography files.
3991The bibliography may have any of these formats:
4059Note that \f[C]\&.bib\f[] can be used with both BibTeX and BibLaTeX
4060files; use \f[C]\&.bibtex\f[] to force BibTeX.
4062Note that \f[C]pandoc\-citeproc\ \-\-bib2json\f[] and
4063\f[C]pandoc\-citeproc\ \-\-bib2yaml\f[] can produce \f[C]\&.json\f[] and
4064\f[C]\&.yaml\f[] files from any of the supported formats.
4066In\-field markup: In BibTeX and BibLaTeX databases, pandoc\-citeproc
4067parses a subset of LaTeX markup; in CSL YAML databases, pandoc Markdown;
4068and in CSL JSON databases, an HTML\-like markup:
4070.B \f[C]<i>...</i>\f[]
4075.B \f[C]<b>...</b>\f[]
4080.B \f[C]<span\ style="font\-variant:small\-caps;">...</span>\f[] or \f[C]<sc>...</sc>\f[]
4085.B \f[C]<sub>...</sub>\f[]
4090.B \f[C]<sup>...</sup>\f[]
4095.B \f[C]<span\ class="nocase">...</span>\f[]
4096prevent a phrase from being capitalized as title case
4100\f[C]pandoc\-citeproc\ \-j\f[] and \f[C]\-y\f[] interconvert the CSL
4101JSON and CSL YAML formats as far as possible.
4103As an alternative to specifying a bibliography file using
4104\f[C]\-\-bibliography\f[] or the YAML metadata field
4105\f[C]bibliography\f[], you can include the citation data directly in the
4106\f[C]references\f[] field of the document\[aq]s YAML metadata.
4107The field should contain an array of YAML\-encoded references, for
4114\-\ type:\ article\-journal
4115\ \ id:\ WatsonCrick1953
4117\ \ \-\ family:\ Watson
4118\ \ \ \ given:\ J.\ D.
4119\ \ \-\ family:\ Crick
4120\ \ \ \ given:\ F.\ H.\ C.
4126\ \ title:\ \[aq]Molecular\ structure\ of\ nucleic\ acids:\ a\ structure\ for\ deoxyribose
4127\ \ \ \ nucleic\ acid\[aq]
4128\ \ title\-short:\ Molecular\ structure\ of\ nucleic\ acids
4129\ \ container\-title:\ Nature
4133\ \ DOI:\ 10.1038/171737a0
4134\ \ URL:\ http://www.nature.com/nature/journal/v171/n4356/abs/171737a0.html
4135\ \ language:\ en\-GB
4140(\f[C]pandoc\-citeproc\ \-\-bib2yaml\f[] can produce these from a
4141bibliography file in one of the supported formats.)
4143Citations and references can be formatted using any style supported by
4144the Citation Style Language, listed in the Zotero Style Repository.
4145These files are specified using the \f[C]\-\-csl\f[] option or the
4146\f[C]csl\f[] metadata field.
4147By default, \f[C]pandoc\-citeproc\f[] will use the Chicago Manual of
4148Style author\-date format.
4149The CSL project provides further information on finding and editing
4152To make your citations hyperlinks to the corresponding bibliography
4153entries, add \f[C]link\-citations:\ true\f[] to your YAML metadata.
4155Citations go inside square brackets and are separated by semicolons.
4156Each citation must have a key, composed of \[aq]\@\[aq] + the citation
4157identifier from the database, and may optionally have a prefix, a
4158locator, and a suffix.
4159The citation key must begin with a letter, digit, or \f[C]_\f[], and may
4160contain alphanumerics, \f[C]_\f[], and internal punctuation characters
4161(\f[C]:.#$%&\-+?<>~/\f[]).
4162Here are some examples:
4166Blah\ blah\ [see\ \@doe99,\ pp.\ 33\-35;\ also\ \@smith04,\ chap.\ 1].
4168Blah\ blah\ [\@doe99,\ pp.\ 33\-35,\ 38\-39\ and\ *passim*].
4170Blah\ blah\ [\@smith04;\ \@doe99].
4174\f[C]pandoc\-citeproc\f[] detects locator terms in the CSL locale files.
4175Either abbreviated or unabbreviated forms are accepted.
4176In the \f[C]en\-US\f[] locale, locator terms can be written in either
4177singular or plural forms, as \f[C]book\f[], \f[C]bk.\f[]/\f[C]bks.\f[];
4178\f[C]chapter\f[], \f[C]chap.\f[]/\f[C]chaps.\f[]; \f[C]column\f[],
4179\f[C]col.\f[]/\f[C]cols.\f[]; \f[C]figure\f[],
4180\f[C]fig.\f[]/\f[C]figs.\f[]; \f[C]folio\f[],
4181\f[C]fol.\f[]/\f[C]fols.\f[]; \f[C]number\f[],
4182\f[C]no.\f[]/\f[C]nos.\f[]; \f[C]line\f[], \f[C]l.\f[]/\f[C]ll.\f[];
4183\f[C]note\f[], \f[C]n.\f[]/\f[C]nn.\f[]; \f[C]opus\f[],
4184\f[C]op.\f[]/\f[C]opp.\f[]; \f[C]page\f[], \f[C]p.\f[]/\f[C]pp.\f[];
4185\f[C]paragraph\f[], \f[C]para.\f[]/\f[C]paras.\f[]; \f[C]part\f[],
4186\f[C]pt.\f[]/\f[C]pts.\f[]; \f[C]section\f[],
4187\f[C]sec.\f[]/\f[C]secs.\f[]; \f[C]sub\ verbo\f[],
4188\f[C]s.v.\f[]/\f[C]s.vv.\f[]; \f[C]verse\f[], \f[C]v.\f[]/\f[C]vv.\f[];
4189\f[C]volume\f[], \f[C]vol.\f[]/\f[C]vols.\f[]; \f[C]¶\f[]/\f[C]¶¶\f[];
4190\f[C]§\f[]/\f[C]§§\f[].
4191If no locator term is used, "page" is assumed.
4193A minus sign (\f[C]\-\f[]) before the \f[C]\@\f[] will suppress mention
4194of the author in the citation.
4195This can be useful when the author is already mentioned in the text:
4199Smith\ says\ blah\ [\-\@smith04].
4203You can also write an in\-text citation, as follows:
4207\@smith04\ says\ blah.
4209\@smith04\ [p.\ 33]\ says\ blah.
4213If the style calls for a list of works cited, it will be placed at the
4215Normally, you will want to end your document with an appropriate header:
4225The bibliography will be inserted after this header.
4226Note that the \f[C]unnumbered\f[] class will be added to this header, so
4227that the section will not be numbered.
4229If you want to include items in the bibliography without actually citing
4230them in the body text, you can define a dummy \f[C]nocite\f[] metadata
4231field and put the citations there:
4237\ \ \@item1,\ \@item2
4244In this example, the document will contain a citation for \f[C]item3\f[]
4245only, but the bibliography will contain entries for \f[C]item1\f[],
4246\f[C]item2\f[], and \f[C]item3\f[].
4248For LaTeX or PDF output, you can also use \f[C]natbib\f[] or
4249\f[C]biblatex\f[] to render bibliography.
4250In order to do so, specify bibliography files as outlined above, and add
4251\f[C]\-\-natbib\f[] or \f[C]\-\-biblatex\f[] argument to \f[C]pandoc\f[]
4253Bear in mind that bibliography files have to be in respective format
4254(either BibTeX or BibLaTeX).
4256For more information, see the pandoc\-citeproc man page.
4257.SS Non\-pandoc extensions
4259The following Markdown syntax extensions are not enabled by default in
4260pandoc, but may be enabled by adding \f[C]+EXTENSION\f[] to the format
4261name, where \f[C]EXTENSION\f[] is the name of the extension.
4262Thus, for example, \f[C]markdown+hard_line_breaks\f[] is Markdown with
4264.SS Extension: \f[C]angle_brackets_escapable\f[]
4266Allow \f[C]<\f[] and \f[C]>\f[] to be backslash\-escaped, as they can be
4267in GitHub flavored Markdown but not original Markdown.
4268This is implied by pandoc\[aq]s default \f[C]all_symbols_escapable\f[].
4269.SS Extension: \f[C]lists_without_preceding_blankline\f[]
4271Allow a list to occur right after a paragraph, with no intervening blank
4273.SS Extension: \f[C]hard_line_breaks\f[]
4275Causes all newlines within a paragraph to be interpreted as hard line
4276breaks instead of spaces.
4277.SS Extension: \f[C]ignore_line_breaks\f[]
4279Causes newlines within a paragraph to be ignored, rather than being
4280treated as spaces or as hard line breaks.
4281This option is intended for use with East Asian languages where spaces
4282are not used between words, but text is divided into lines for
4284.SS Extension: \f[C]east_asian_line_breaks\f[]
4286Causes newlines within a paragraph to be ignored, rather than being
4287treated as spaces or as hard line breaks, when they occur between two
4288East Asian wide characters.
4289This is a better choice than \f[C]ignore_line_breaks\f[] for texts that
4290include a mix of East Asian wide characters and other characters.
4291.SS Extension: \f[C]emoji\f[]
4293Parses textual emojis like \f[C]:smile:\f[] as Unicode emoticons.
4294.SS Extension: \f[C]tex_math_single_backslash\f[]
4296Causes anything between \f[C]\\(\f[] and \f[C]\\)\f[] to be interpreted
4297as inline TeX math, and anything between \f[C]\\[\f[] and \f[C]\\]\f[]
4298to be interpreted as display TeX math.
4299Note: a drawback of this extension is that it precludes escaping
4300\f[C](\f[] and \f[C][\f[].
4301.SS Extension: \f[C]tex_math_double_backslash\f[]
4303Causes anything between \f[C]\\\\(\f[] and \f[C]\\\\)\f[] to be
4304interpreted as inline TeX math, and anything between \f[C]\\\\[\f[] and
4305\f[C]\\\\]\f[] to be interpreted as display TeX math.
4306.SS Extension: \f[C]markdown_attribute\f[]
4308By default, pandoc interprets material inside block\-level tags as
4310This extension changes the behavior so that Markdown is only parsed
4311inside block\-level tags if the tags have the attribute
4313.SS Extension: \f[C]mmd_title_block\f[]
4315Enables a MultiMarkdown style title block at the top of the document,
4320Title:\ \ \ My\ title
4322Date:\ \ \ \ September\ 1,\ 2008
4323Comment:\ This\ is\ a\ sample\ mmd\ title\ block,\ with
4324\ \ \ \ \ \ \ \ \ a\ field\ spanning\ multiple\ lines.
4328See the MultiMarkdown documentation for details.
4329If \f[C]pandoc_title_block\f[] or \f[C]yaml_metadata_block\f[] is
4330enabled, it will take precedence over \f[C]mmd_title_block\f[].
4331.SS Extension: \f[C]abbreviations\f[]
4333Parses PHP Markdown Extra abbreviation keys, like
4337*[HTML]:\ Hypertext\ Markup\ Language
4341Note that the pandoc document model does not support abbreviations, so
4342if this extension is enabled, abbreviation keys are simply skipped (as
4343opposed to being parsed as paragraphs).
4344.SS Extension: \f[C]autolink_bare_uris\f[]
4346Makes all absolute URIs into links, even when not surrounded by pointy
4347braces \f[C]<...>\f[].
4348.SS Extension: \f[C]ascii_identifiers\f[]
4350Causes the identifiers produced by \f[C]auto_identifiers\f[] to be pure
4352Accents are stripped off of accented latin letters, and non\-latin
4354.SS Extension: \f[C]mmd_link_attributes\f[]
4356Parses multimarkdown style key\-value attributes on link and image
4358This extension should not be confused with the \f[C]link_attributes\f[]
4363This\ is\ a\ reference\ ![image][ref]\ with\ multimarkdown\ attributes.
4365[ref]:\ http://path.to/image\ "Image\ title"\ width=20px\ height=30px
4366\ \ \ \ \ \ \ id=myId\ class="myClass1\ myClass2"
4369.SS Extension: \f[C]mmd_header_identifiers\f[]
4371Parses multimarkdown style header identifiers (in square brackets, after
4372the header but before any trailing \f[C]#\f[]s in an ATX header).
4373.SS Extension: \f[C]compact_definition_lists\f[]
4375Activates the definition list syntax of pandoc 1.12.x and earlier.
4376This syntax differs from the one described above under Definition lists
4379No blank line is required between consecutive items of the definition
4382To get a "tight" or "compact" list, omit space between consecutive
4383items; the space between a term and its definition does not affect
4386Lazy wrapping of paragraphs is not allowed: the entire definition must
4387be indented four spaces.
4388.SS Markdown variants
4390In addition to pandoc\[aq]s extended Markdown, the following Markdown
4391variants are supported:
4393.B \f[C]markdown_phpextra\f[] (PHP Markdown Extra)
4394\f[C]footnotes\f[], \f[C]pipe_tables\f[], \f[C]raw_html\f[],
4395\f[C]markdown_attribute\f[], \f[C]fenced_code_blocks\f[],
4396\f[C]definition_lists\f[], \f[C]intraword_underscores\f[],
4397\f[C]header_attributes\f[], \f[C]link_attributes\f[],
4398\f[C]abbreviations\f[], \f[C]shortcut_reference_links\f[].
4402.B \f[C]markdown_github\f[] (GitHub\-Flavored Markdown)
4403\f[C]pipe_tables\f[], \f[C]raw_html\f[], \f[C]fenced_code_blocks\f[],
4404\f[C]auto_identifiers\f[], \f[C]ascii_identifiers\f[],
4405\f[C]backtick_code_blocks\f[], \f[C]autolink_bare_uris\f[],
4406\f[C]intraword_underscores\f[], \f[C]strikeout\f[],
4407\f[C]hard_line_breaks\f[], \f[C]emoji\f[],
4408\f[C]shortcut_reference_links\f[], \f[C]angle_brackets_escapable\f[].
4412.B \f[C]markdown_mmd\f[] (MultiMarkdown)
4413\f[C]pipe_tables\f[], \f[C]raw_html\f[], \f[C]markdown_attribute\f[],
4414\f[C]mmd_link_attributes\f[], \f[C]tex_math_double_backslash\f[],
4415\f[C]intraword_underscores\f[], \f[C]mmd_title_block\f[],
4416\f[C]footnotes\f[], \f[C]definition_lists\f[],
4417\f[C]all_symbols_escapable\f[], \f[C]implicit_header_references\f[],
4418\f[C]auto_identifiers\f[], \f[C]mmd_header_identifiers\f[],
4419\f[C]shortcut_reference_links\f[].
4423.B \f[C]markdown_strict\f[] (Markdown.pl)
4427.SS Extensions with formats other than Markdown
4429Some of the extensions discussed above can be used with formats other
4432\f[C]auto_identifiers\f[] can be used with \f[C]latex\f[], \f[C]rst\f[],
4433\f[C]mediawiki\f[], and \f[C]textile\f[] input (and is used by default).
4435\f[C]tex_math_dollars\f[], \f[C]tex_math_single_backslash\f[], and
4436\f[C]tex_math_double_backslash\f[] can be used with \f[C]html\f[] input.
4437(This is handy for reading web pages formatted using MathJax, for
4439.SH PRODUCING SLIDE SHOWS WITH PANDOC
4441You can use pandoc to produce an HTML + javascript slide presentation
4442that can be viewed via a web browser.
4443There are five ways to do this, using S5, DZSlides, Slidy, Slideous, or
4445You can also produce a PDF slide show using LaTeX \f[C]beamer\f[].
4447Here\[aq]s the Markdown source for a simple slide show,
4461\-\ Get\ out\ of\ bed
4475\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
4477
4486To produce an HTML/javascript slide show, simply type
4490pandoc\ \-t\ FORMAT\ \-s\ habits.txt\ \-o\ habits.html
4494where \f[C]FORMAT\f[] is either \f[C]s5\f[], \f[C]slidy\f[],
4495\f[C]slideous\f[], \f[C]dzslides\f[], or \f[C]revealjs\f[].
4497For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with
4498the \f[C]\-s/\-\-standalone\f[] option embeds a link to javascripts and
4499CSS files, which are assumed to be available at the relative path
4500\f[C]s5/default\f[] (for S5), \f[C]slideous\f[] (for Slideous),
4501\f[C]reveal.js\f[] (for reveal.js), or at the Slidy website at
4502\f[C]w3.org\f[] (for Slidy).
4503(These paths can be changed by setting the \f[C]slidy\-url\f[],
4504\f[C]slideous\-url\f[], \f[C]revealjs\-url\f[], or \f[C]s5\-url\f[]
4505variables; see Variables for slides, above.) For DZSlides, the
4506(relatively short) javascript and css are included in the file by
4509With all HTML slide formats, the \f[C]\-\-self\-contained\f[] option can
4510be used to produce a single file that contains all of the data necessary
4511to display the slide show, including linked scripts, stylesheets,
4514To produce a PDF slide show using beamer, type
4518pandoc\ \-t\ beamer\ habits.txt\ \-o\ habits.pdf
4522Note that a reveal.js slide show can also be converted to a PDF by
4523printing it to a file from the browser.
4524.SS Structuring the slide show
4526By default, the \f[I]slide level\f[] is the highest header level in the
4527hierarchy that is followed immediately by content, and not another
4528header, somewhere in the document.
4529In the example above, level 1 headers are always followed by level 2
4530headers, which are followed by content, so 2 is the slide level.
4531This default can be overridden using the \f[C]\-\-slide\-level\f[]
4534The document is carved up into slides according to the following rules:
4536A horizontal rule always starts a new slide.
4538A header at the slide level always starts a new slide.
4540Headers \f[I]below\f[] the slide level in the hierarchy create headers
4541\f[I]within\f[] a slide.
4543Headers \f[I]above\f[] the slide level in the hierarchy create "title
4544slides," which just contain the section title and help to break the
4545slide show into sections.
4547A title page is constructed automatically from the document\[aq]s title
4549(In the case of beamer, this can be disabled by commenting out some
4550lines in the default template.)
4552These rules are designed to support many different styles of slide show.
4553If you don\[aq]t care about structuring your slides into sections and
4554subsections, you can just use level 1 headers for all each slide.
4555(In that case, level 1 will be the slide level.) But you can also
4556structure the slide show into sections, as in the example above.
4558Note: in reveal.js slide shows, if slide level is 2, a two\-dimensional
4559layout will be produced, with level 1 headers building horizontally and
4560level 2 headers building vertically.
4561It is not recommended that you use deeper nesting of section levels with
4563.SS Incremental lists
4565By default, these writers produce lists that display "all at once." If
4566you want your lists to display incrementally (one item at a time), use
4567the \f[C]\-i\f[] option.
4568If you want a particular list to depart from the default (that is, to
4569display incrementally without the \f[C]\-i\f[] option and all at once
4570with the \f[C]\-i\f[] option), put it in a block quote:
4574>\ \-\ Eat\ spaghetti
4579In this way incremental and nonincremental lists can be mixed in a
4583You can add "pauses" within a slide by including a paragraph containing
4584three dots, separated by spaces:
4588#\ Slide\ with\ a\ pause
4590content\ before\ the\ pause
4594content\ after\ the\ pause
4597.SS Styling the slides
4599You can change the style of HTML slides by putting customized CSS files
4600in \f[C]$DATADIR/s5/default\f[] (for S5), \f[C]$DATADIR/slidy\f[] (for
4601Slidy), or \f[C]$DATADIR/slideous\f[] (for Slideous), where
4602\f[C]$DATADIR\f[] is the user data directory (see
4603\f[C]\-\-data\-dir\f[], above).
4604The originals may be found in pandoc\[aq]s system data directory
4605(generally \f[C]$CABALDIR/pandoc\-VERSION/s5/default\f[]).
4606Pandoc will look there for any files it does not find in the user data
4609For dzslides, the CSS is included in the HTML file itself, and may be
4612All reveal.js configuration options can be set through variables.
4613For example, themes can be used by setting the \f[C]theme\f[] variable:
4621Or you can specify a custom stylesheet using the \f[C]\-\-css\f[]
4624To style beamer slides, you can specify a \f[C]theme\f[],
4625\f[C]colortheme\f[], \f[C]fonttheme\f[], \f[C]innertheme\f[], and
4626\f[C]outertheme\f[], using the \f[C]\-V\f[] option:
4630pandoc\ \-t\ beamer\ habits.txt\ \-V\ theme:Warsaw\ \-o\ habits.pdf
4634Note that header attributes will turn into slide attributes (on a
4635\f[C]<div>\f[] or \f[C]<section>\f[]) in HTML slide formats, allowing
4636you to style individual slides.
4637In beamer, the only header attribute that affects slides is the
4638\f[C]allowframebreaks\f[] class, which sets the
4639\f[C]allowframebreaks\f[] option, causing multiple slides to be created
4640if the content overfills the frame.
4641This is recommended especially for bibliographies:
4645#\ References\ {.allowframebreaks}
4650reveal.js has good support for speaker notes.
4651You can add notes to your Markdown document thus:
4658\-\ It\ can\ contain\ Markdown
4665To show the notes window, press \f[C]s\f[] while viewing the
4667Notes are not yet supported for other slide formats, but the notes will
4668not appear on the slides themselves.
4669.SS Frame attributes in beamer
4671Sometimes it is necessary to add the LaTeX \f[C][fragile]\f[] option to
4672a frame in beamer (for example, when using the \f[C]minted\f[]
4674This can be forced by adding the \f[C]fragile\f[] class to the header
4675introducing the slide:
4679#\ Fragile\ slide\ {.fragile}
4683All of the other frame attributes described in Section 8.1 of the Beamer
4684User\[aq]s Guide may also be used: \f[C]allowdisplaybreaks\f[],
4685\f[C]allowframebreaks\f[], \f[C]b\f[], \f[C]c\f[], \f[C]t\f[],
4686\f[C]environment\f[], \f[C]label\f[], \f[C]plain\f[], \f[C]shrink\f[].
4687.SH CREATING EPUBS WITH PANDOC
4690EPUB metadata may be specified using the \f[C]\-\-epub\-metadata\f[]
4691option, but if the source document is Markdown, it is better to use a
4702\ \ text:\ An\ investigation\ of\ metadata
4705\ \ text:\ John\ Smith
4707\ \ text:\ Sarah\ Jones
4710\ \ text:\ doi:10.234234.234/33
4711publisher:\ \ My\ Press
4712rights:\ ©\ 2007\ John\ Smith,\ CC\ BY\-NC
4717The following fields are recognized:
4719.B \f[C]identifier\f[]
4720Either a string value or an object with fields \f[C]text\f[] and
4722Valid values for \f[C]scheme\f[] are \f[C]ISBN\-10\f[],
4723\f[C]GTIN\-13\f[], \f[C]UPC\f[], \f[C]ISMN\-10\f[], \f[C]DOI\f[],
4724\f[C]LCCN\f[], \f[C]GTIN\-14\f[], \f[C]ISBN\-13\f[],
4725\f[C]Legal\ deposit\ number\f[], \f[C]URN\f[], \f[C]OCLC\f[],
4726\f[C]ISMN\-13\f[], \f[C]ISBN\-A\f[], \f[C]JP\f[], \f[C]OLCC\f[].
4731Either a string value, or an object with fields \f[C]file\-as\f[] and
4732\f[C]type\f[], or a list of such objects.
4733Valid values for \f[C]type\f[] are \f[C]main\f[], \f[C]subtitle\f[],
4734\f[C]short\f[], \f[C]collection\f[], \f[C]edition\f[],
4740Either a string value, or an object with fields \f[C]role\f[],
4741\f[C]file\-as\f[], and \f[C]text\f[], or a list of such objects.
4742Valid values for \f[C]role\f[] are MARC relators, but pandoc will
4743attempt to translate the human\-readable versions (like "author" and
4744"editor") to the appropriate marc relators.
4748.B \f[C]contributor\f[]
4749Same format as \f[C]creator\f[].
4754A string value in \f[C]YYYY\-MM\-DD\f[] format.
4755(Only the year is necessary.) Pandoc will attempt to convert other
4760.B \f[C]lang\f[] (or legacy: \f[C]language\f[])
4761A string value in BCP 47 format.
4762Pandoc will default to the local language if nothing is specified.
4767A string value or a list of such values.
4771.B \f[C]description\f[]
4801.B \f[C]cover\-image\f[]
4802A string value (path to cover image).
4806.B \f[C]stylesheet\f[]
4807A string value (path to CSS stylesheet).
4811.B \f[C]page\-progression\-direction\f[]
4812Either \f[C]ltr\f[] or \f[C]rtl\f[].
4813Specifies the \f[C]page\-progression\-direction\f[] attribute for the
4814\f[C]spine\f[] element.
4819By default, pandoc will download linked media (including audio and
4820video) and include it in the EPUB container, yielding a completely
4821self\-contained EPUB.
4822If you want to link to external media resources instead, use raw HTML in
4823your source and add \f[C]data\-external="1"\f[] to the tag with the
4824\f[C]src\f[] attribute.
4829<audio\ controls="1">
4830\ \ <source\ src="http://example.com/music/toccata.mp3"
4831\ \ \ \ \ \ \ \ \ \ data\-external="1"\ type="audio/mpeg">
4836.SH LITERATE HASKELL SUPPORT
4838If you append \f[C]+lhs\f[] (or \f[C]+literate_haskell\f[]) to an
4839appropriate input or output format (\f[C]markdown\f[],
4840\f[C]markdown_strict\f[], \f[C]rst\f[], or \f[C]latex\f[] for input or
4841output; \f[C]beamer\f[], \f[C]html\f[] or \f[C]html5\f[] for output
4842only), pandoc will treat the document as literate Haskell source.
4845In Markdown input, "bird track" sections will be parsed as Haskell code
4846rather than block quotations.
4847Text between \f[C]\\begin{code}\f[] and \f[C]\\end{code}\f[] will also
4848be treated as Haskell code.
4849For ATX\-style headers the character \[aq]=\[aq] will be used instead of
4852In Markdown output, code blocks with classes \f[C]haskell\f[] and
4853\f[C]literate\f[] will be rendered using bird tracks, and block
4854quotations will be indented one space, so they will not be treated as
4856In addition, headers will be rendered setext\-style (with underlines)
4857rather than ATX\-style (with \[aq]#\[aq] characters).
4858(This is because ghc treats \[aq]#\[aq] characters in column 1 as
4859introducing line numbers.)
4861In restructured text input, "bird track" sections will be parsed as
4864In restructured text output, code blocks with class \f[C]haskell\f[]
4865will be rendered using bird tracks.
4867In LaTeX input, text in \f[C]code\f[] environments will be parsed as
4870In LaTeX output, code blocks with class \f[C]haskell\f[] will be
4871rendered inside \f[C]code\f[] environments.
4873In HTML output, code blocks with class \f[C]haskell\f[] will be rendered
4874with class \f[C]literatehaskell\f[] and bird tracks.
4880pandoc\ \-f\ markdown+lhs\ \-t\ html
4884reads literate Haskell source formatted with Markdown conventions and
4885writes ordinary HTML (without bird tracks).
4889pandoc\ \-f\ markdown+lhs\ \-t\ html+lhs
4893writes HTML with the Haskell code in bird tracks, so it can be copied
4894and pasted as literate Haskell source.
4895.SH SYNTAX HIGHLIGHTING
4897Pandoc will automatically highlight syntax in fenced code blocks that
4898are marked with a language name.
4899The Haskell library highlighting\-kate is used for highlighting, which
4900works in HTML, Docx, and LaTeX/PDF output.
4901The color scheme can be selected using the \f[C]\-\-highlight\-style\f[]
4903The default color scheme is \f[C]pygments\f[], which imitates the
4904default color scheme used by the Python library pygments, but pygments
4905is not actually used to do the highlighting.
4907To see a list of language names that pandoc will recognize, type
4908\f[C]pandoc\ \-\-version\f[].
4910To disable highlighting, use the \f[C]\-\-no\-highlight\f[] option.
4911.SH CUSTOM STYLES IN DOCX OUTPUT
4913By default, pandoc\[aq]s docx output applies a predefined set of styles
4914for blocks such as paragraphs and block quotes, and uses largely default
4915formatting (italics, bold) for inlines.
4916This will work for most purposes, especially alongside a
4917\f[C]reference.docx\f[] file.
4918However, if you need to apply your own styles to blocks, or match a
4919preexisting set of styles, pandoc allows you to define custom styles for
4920blocks and text using \f[C]div\f[]s and \f[C]span\f[]s, respecitively.
4922If you define a \f[C]div\f[] or \f[C]span\f[] with the attribute
4923\f[C]custom\-style\f[], pandoc will apply your specified style to the
4929<span\ custom\-style="Emphatically">Get\ out,</span>\ he\ said.
4933would produce a docx file with "Get out," styled with character style
4934\f[C]Emphatically\f[].
4939Dickinson\ starts\ the\ poem\ simply:
4941<div\ custom\-style="Poetry">
4942|\ A\ Bird\ came\ down\ the\ Walk\-\-\-
4943|\ He\ did\ not\ know\ I\ saw\-\-\-
4948would style the two contained lines with the \f[C]Poetry\f[] paragraph
4951If the styles are not yet in your reference.docx, they will be defined
4952in the output file as inheriting from normal text.
4953If they are already defined, pandoc will not alter the definition.
4955This feature allows for greatest customization in conjunction with
4957If you want all paragraphs after block quotes to be indented, you can
4958write a filter to apply the styles necessary.
4959If you want all italics to be transformed to the \f[C]Emphasis\f[]
4960character style (perhaps to change their color), you can write a filter
4961which will transform all italicized inlines to inlines within an
4962\f[C]Emphasis\f[] custom\-style \f[C]span\f[].
4965Pandoc can be extended with custom writers written in lua.
4966(Pandoc includes a lua interpreter, so lua need not be installed
4969To use a custom writer, simply specify the path to the lua script in
4970place of the output format.
4975pandoc\ \-t\ data/sample.lua
4979Creating a custom writer requires writing a lua function for each
4980possible element in a pandoc document.
4981To get a documented example which you can modify according to your
4986pandoc\ \-\-print\-default\-data\-file\ sample.lua
4991© 2006\-2016 John MacFarlane (jgm\@berkeley.edu).
4992Released under the GPL, version 2 or greater.
4993This software carries no warranty of any kind.
4994(See COPYRIGHT for full copyright and warranty notices.)
4996Contributors include Arata Mizuki, Aaron Wolen, Albert Krewinkel, Alex
4997Ivkin, Alex Vong, Alexander Kondratskiy, Alexander Sulfrian, Alexander V
4998Vershilov, Alfred Wechselberger, Andreas Lööw, Andrew Dunning, Antoine
4999Latter, Arata Mizuki, Arlo O\[aq]Keeffe, Artyom Kazak, B.
5000Scott Michel, Ben Gamari, Beni Cherniavsky\-Paskin, Benoit Schweblin,
5001Bjorn Buckwalter, Bradley Kuhn, Brent Yorgey, Bryan O\[aq]Sullivan,
5002Caleb McDaniel, Calvin Beck, Carlos Sosa, Chris Black, Christian Conkle,
5003Christoffer Ackelman, Christoffer Sawicki, Clare Macrae, Clint Adams,
5004Conal Elliott, Craig S.
5005Bosma, Daniel Bergey, Daniel T.
5006Staal, Daniele D\[aq]Orazio, David Lazar, David Röthlisberger, Denis
5007Laxalde, Douglas Calvert, Emanuel Evans, Emily Eisenberg, Eric Kow, Eric
5008Seidel, Felix Yan, Florian Eitel, François Gannaz, Freiric Barral,
5009Freirich Raabe, Frerich Raabe, Fyodor Sheremetyev, Gabor Pali, Gavin
5010Beatty, Gottfried Haider, Greg Maslov, Greg Rundlett, Grégory Bataille,
5011Gwern Branwen, Hans\-Peter Deifel, Henrik Tramberend, Henry de Valence,
5012Hubert Plociniczak, Ilya V.
5013Portnov, Ivo Clarysse, J.
5014Lewis Muir, Jaime Marquínez Ferrándiz, Jakob Voß, James Aspnes, Jamie F.
5015Olson, Jan Larres, Jan Schulz, Jason Ronallo, Jeff Arnold, Jeff
5016Runningen, Jens Petersen, Jesse Rosenthal, Joe Hillenbrand, John
5017MacFarlane, Jonas Smedegaard, Jonathan Daugherty, Jose Luis Duran, Josef
5018Svenningsson, Julien Cretel, Juliusz Gonera, Justin Bogner, Jérémy
5019Bobbio, Kelsey Hightower, Kolen Cheung, KolenCheung, Konstantin Zudov,
5020Kristof Bastiaensen, Lars\-Dominik Braun, Luke Plant, Mark Szepieniec,
5021Mark Wright, Martin Linn, Masayoshi Takahashi, Matej Kollar, Mathias
5022Schenner, Mathieu Duponchelle, Matthew Eddey, Matthew Pickering,
5025Troffaes, Mauro Bieg, Max Bolingbroke, Max Rydahl Andersen, Merijn
5026Verstraaten, Michael Beaumont, Michael Chladek, Michael Snoyman, Michael
5027Thompson, MinRK, Morton Fox, Nathan Gass, Neil Mayhew, Nick Bart,
5028Nicolas Kaiser, Nikolay Yakimov, Oliver Matthews, Ophir Lifshitz, Pablo
5029Rodríguez, Paul Rivier, Paulo Tanimoto, Peter Wang, Philippe Ombredanne,
5030Phillip Alday, Prayag Verma, Puneeth Chaganti, Ralf Stephan, Raniere
5031Silva, Recai Oktaş, RyanGlScott, Scott Morrison, Sergei Trofimovich,
5032Sergey Astanin, Shahbaz Youssefi, Shaun Attfield, Sidarth Kapur,
5033Sidharth Kapur, Simon Hengel, Sumit Sahrawat, Thomas Hodgson, Thomas
5034Weißschuh, Tim Lin, Timothy Humphries, Tiziano Müller, Todd Sifleet, Tom
5035Leese, Uli Köhler, Václav Zeman, Viktor Kronvall, Vincent, Václav Zeman,
5036Waldir Pimenta, Wikiwide, Xavier Olive, csforste, infinity0x, nkalvi,
5037qerub, robabla, roblabla, rodja.trappe, rski, shreevatsa.public,
5038takahashim, thsutton.
5040The Pandoc source code and all documentation may be downloaded
5041from <http://pandoc.org>.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list