1PANDOC(1) General Commands Manual PANDOC(1)
2
6 pandoc - general markup converter
7
9 pandoc [options] [input-file]...
10
12 Pandoc is a Haskell library for converting from one markup format to
13 another, and a command-line tool that uses this library. It can read
14 markdown and (subsets of) Textile, reStructuredText, HTML, and LaTeX;
15 and it can write plain text, markdown, reStructuredText, HTML, LaTeX,
16 ConTeXt, RTF, DocBook XML, OpenDocument XML, ODT, GNU Texinfo, Medi‐
17 aWiki markup, EPUB, Textile, groff man pages, Emacs Org-Mode, and Slidy
18 or S5 HTML slide shows.
19 Pandoc's enhanced version of markdown includes syntax for footnotes,
21 tables, flexible ordered lists, definition lists, delimited code
22 blocks, superscript, subscript, strikeout, title blocks, automatic
23 tables of contents, embedded LaTeX math, citations, and markdown inside
24 HTML block elements. (These enhancements, described below under Pan‐
25 doc's markdown, can be disabled using the --strict option.)
26 In contrast to most existing tools for converting markdown to HTML,
28 which use regex substitutions, Pandoc has a modular design: it consists
29 of a set of readers, which parse text in a given format and produce a
30 native representation of the document, and a set of writers, which con‐
31 vert this native representation into a target format. Thus, adding an
32 input or output format requires only adding a reader or writer.
33 Using Pandoc
35 If no input-file is specified, input is read from stdin. Otherwise,
36 the input-files are concatenated (with a blank line between each) and
37 used as input. Output goes to stdout by default (though output to std‐
38 out is disabled for the odt and epub output formats). For output to a
39 file, use the -o option:
40 pandoc -o output.html input.txt
42 Instead of a file, an absolute URI may be given. In this case pandoc
44 will fetch the content using HTTP:
45 pandoc -f html -t markdown http://www.fsf.org
47 If multiple input files are given, pandoc will concatenate them all
49 (with blank lines between them) before parsing.
50 The format of the input and output can be specified explicitly using
52 command-line options. The input format can be specified using the
53 -r/--read or -f/--from options, the output format using the -w/--write
54 or -t/--to options. Thus, to convert hello.txt from markdown to LaTeX,
55 you could type:
56 pandoc -f markdown -t latex hello.txt
58 To convert hello.html from html to markdown:
60 pandoc -f html -t markdown hello.html
62 Supported output formats are listed below under the -t/--to option.
64 Supported input formats are listed below under the -f/--from option.
65 Note that the rst, textile, latex, and html readers are not complete;
66 there are some constructs that they do not parse.
67 If the input or output format is not specified explicitly, pandoc will
69 attempt to guess it from the extensions of the input and output file‐
70 names. Thus, for example,
71 pandoc -o hello.tex hello.txt
73 will convert hello.txt from markdown to LaTeX. If no output file is
75 specified (so that output goes to stdout), or if the output file's
76 extension is unknown, the output format will default to HTML. If no
77 input file is specified (so that input comes from stdin), or if the
78 input files' extensions are unknown, the input format will be assumed
79 to be markdown unless explicitly specified.
80 Pandoc uses the UTF-8 character encoding for both input and output. If
82 your local character encoding is not UTF-8, you should pipe input and
83 output through iconv:
84 iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
86
88 -f FORMAT, -r FORMAT,
89 --from=FORMAT, --read=FORMAT Specify input format. FORMAT can
90 be native (native Haskell), json (JSON version of native AST),
91 markdown (markdown), textile (Textile), rst (reStructuredText),
92 html (HTML), or latex (LaTeX). If +lhs is appended to markdown,
93 rst, or latex, the input will be treated as literate Haskell
94 source: see Literate Haskell support, below.
95 -t FORMAT, -w FORMAT,
97 --to=FORMAT, --write=FORMAT Specify output format. FORMAT can
98 be native (native Haskell), json (JSON version of native AST),
99 plain (plain text), markdown (markdown), rst (reStructuredText),
100 html (HTML), latex (LaTeX), context (ConTeXt), man (groff man),
101 mediawiki (MediaWiki markup), textile (Textile), org (Emacs Org-
102 Mode), texinfo (GNU Texinfo), docbook (DocBook XML), opendocu‐
103 ment (OpenDocument XML), odt (OpenOffice text document), epub
104 (EPUB book), slidy (Slidy HTML and javascript slide show), s5
105 (S5 HTML and javascript slide show), or rtf (rich text format).
106 Note that odt and epub output will not be directed to stdout; an
107 output filename must be specified using the -o/--output option.
108 If +lhs is appended to markdown, rst, latex, or html, the output
109 will be rendered as literate Haskell source: see Literate
110 Haskell support, below.
111 -s, --standalone
113 Produce output with an appropriate header and footer (e.g. a
114 standalone HTML, LaTeX, or RTF file, not a fragment).
115 -o FILE, --output=FILE
117 Write output to FILE instead of stdout. If FILE is -, output
118 will go to stdout. (Exception: if the output format is odt or
119 epub, output to stdout is disabled.)
120 -p, --preserve-tabs
122 Preserve tabs instead of converting them to spaces (the
123 default).
124 --tab-stop=NUMBER
126 Specify the number of spaces per tab (default is 4).
127 --strict
129 Use strict markdown syntax, with no pandoc extensions or vari‐
130 ants. When the input format is HTML, this means that constructs
131 that have no equivalents in standard markdown (e.g. definition
132 lists or strikeout text) will be parsed as raw HTML.
133 --normalize
135 Normalize the document after reading: merge adjacent Str or Emph
136 elements, for example, and remove repeated Spaces.
137 --reference-links
139 Use reference-style links, rather than inline links, in writing
140 markdown or reStructuredText. By default inline links are used.
141 -R, --parse-raw
143 Parse untranslatable HTML codes and LaTeX environments as raw
144 HTML or LaTeX, instead of ignoring them. Affects only HTML and
145 LaTeX input. Raw HTML can be printed in markdown, reStructured‐
146 Text, HTML, Slidy, and S5 output; raw LaTeX can be printed in
147 markdown, reStructuredText, LaTeX, and ConTeXt output. The
148 default is for the readers to omit untranslatable HTML codes and
149 LaTeX environments. (The LaTeX reader does pass through
150 untranslatable LaTeX commands, even if -R is not specified.)
151 -S, --smart
153 Produce typographically correct output, converting straight
154 quotes to curly quotes, --- and -- to dashes, ande ... to
155 ellipses. Nonbreaking spaces are inserted after certain abbre‐
156 viations, such as "Mr." (Note: This option is significant only
157 when the input format is markdown or textile. It is selected
158 automatically when the input format is textile or the output
159 format is latex or context.)
160 -5, --html5
162 Produce HTML5 instead of HTML4. This option has no effect for
163 writers other than html.
164 -m [URL], --latexmathml[=URL]
166 Use the LaTeXMathML script to display embedded TeX math in HTML
167 output. To insert a link to a local copy of the LaTeXMathML.js
168 script, provide a URL. If no URL is provided, the contents of
169 the script will be inserted directly into the HTML header, pre‐
170 serving portability at the price of efficiency. If you plan to
171 use math on several pages, it is much better to link to a copy
172 of the script, so it can be cached.
173 --mathml[=URL]
175 Convert TeX math to MathML. In standalone mode, a small
176 javascript (or a link to such a script if a URL is supplied)
177 will be inserted that allows the MathML to be viewed on some
178 browsers.
179 --jsmath[=URL]
181 Use jsMath to display embedded TeX math in HTML output. The URL
182 should point to the jsMath load script (e.g.
183 jsMath/easy/load.js); if provided, it will be linked to in the
184 header of standalone HTML documents. If a URL is not provided,
185 no link to the jsMath load script will be inserted; it is then
186 up to the author to provide such a link in the HTML template.
187 --mathjax=URL
189 Use MathJax to display embedded TeX math in HTML output. The
190 URL should point to the MathJax.js load script.
191 --gladtex
193 Enclose TeX math in <eq> tags in HTML output. These can then be
194 processed by gladTeX to produce links to images of the typeset
195 formulas.
196 --mimetex[=URL]
198 Render TeX math using the mimeTeX CGI script. If URL is not
199 specified, it is assumed that the script is at /cgi-bin/mime‐
200 tex.cgi.
201 --webtex[=URL]
203 Render TeX formulas using an external script that converts TeX
204 formulas to images. The formula will be concatenated with the
205 URL provided. If URL is not specified, the Google Chart API
206 will be used.
207 -i, --incremental
209 Make list items in Slidy or S5 display incrementally (one by
210 one). The default is for lists to be displayed all at once.
211 --offline
213 Include all the CSS and javascript needed for a Slidy or S5
214 slide show in the output, so that the slide show will work even
215 when no internet connection is available.
216 --xetex
218 Create LaTeX outut suitable for processing by XeTeX.
219 --chapters
221 Treat top-level headers as chapters in LaTeX, ConTeXt, and Doc‐
222 Book output.
223 -N, --number-sections
225 Number section headings in LaTeX, ConTeXt, or HTML output. By
226 default, sections are not numbered.
227 --listings
229 Use listings package for LaTeX code blocks
230 --section-divs
232 Wrap sections in <div> tags (or <section> tags in HTML5), and
233 attach identifiers to the enclosing <div> (or <section>) rather
234 than the header itself. See Section identifiers, below.
235 --no-wrap
237 Disable text wrapping in output. By default, text is wrapped
238 appropriately for the output format.
239 --columns=NUMBER
241 Specify length of lines in characters (for text wrapping).
242 --ascii
244 Use only ascii characters in output. Currently supported only
245 for HTML output (which uses numerical entities instead of UTF-8
246 when this option is selected).
247 --email-obfuscation=none|javascript|references
249 Specify a method for obfuscating mailto: links in HTML docu‐
250 ments. none leaves mailto: links as they are. javascript
251 obfuscates them using javascript. references obfuscates them by
252 printing their letters as decimal or hexadecimal character ref‐
253 erences. If --strict is specified, references is used regard‐
254 less of the presence of this option.
255 --id-prefix=STRING
257 Specify a prefix to be added to all automatically generated
258 identifiers in HTML output. This is useful for preventing
259 duplicate identifiers when generating fragments to be included
260 in other pages.
261 --indented-code-classes=CLASSES
263 Specify classes to use for indented code blocks--for example,
264 perl,numberLines or haskell. Multiple classes may be separated
265 by spaces or commas.
266 --toc, --table-of-contents
268 Include an automatically generated table of contents (or, in the
269 case of latex, context, and rst, an instruction to create one)
270 in the output document. This option has no effect on man, doc‐
271 book, slidy, or s5 output.
272 --base-header-level=NUMBER
274 Specify the base level for headers (defaults to 1).
275 --template=FILE
277 Use FILE as a custom template for the generated document.
278 Implies --standalone. See Templates below for a description of
279 template syntax. If this option is not used, a default template
280 appropriate for the output format will be used. See also
281 -D/--print-default-template.
282 -V KEY=VAL, --variable=KEY:VAL
284 Set the template variable KEY to the value VAL when rendering
285 the document in standalone mode. This is only useful when the
286 --template option is used to specify a custom template, since
287 pandoc automatically sets the variables used in the default tem‐
288 plates.
289 -c URL, --css=URL
291 Link to a CSS style sheet.
292 -H FILE, --include-in-header=FILE
294 Include contents of FILE, verbatim, at the end of the header.
295 This can be used, for example, to include special CSS or
296 javascript in HTML documents. This option can be used repeat‐
297 edly to include multiple files in the header. They will be
298 included in the order specified. Implies --standalone.
299 -B FILE,
301 --include-before-body=FILE Include contents of FILE, verbatim,
302 at the beginning of the document body (e.g. after the <body>
303 tag in HTML, or the \begin{document} command in LaTeX). This
304 can be used to include navigation bars or banners in HTML docu‐
305 ments. This option can be used repeatedly to include multiple
306 files. They will be included in the order specified. Implies
307 --standalone.
308 -A FILE,
310 --include-after-body=FILE Include contents of FILE, verbatim, at
311 the end of the document body (before the </body> tag in HTML, or
312 the \end{document} command in LaTeX). This option can be be
313 used repeatedly to include multiple files. They will be
314 included in the order specified. Implies --standalone.
315 --reference-odt=FILE
317 Use the specified file as a style reference in producing an ODT.
318 For best results, the reference ODT should be a modified version
319 of an ODT produced using pandoc. The contents of the reference
320 ODT are ignored, but its stylesheets are used in the new ODT.
321 If no reference ODT is specified on the command line, pandoc
322 will look for a file reference.odt in the user data directory
323 (see --data-dir). If this is not found either, sensible
324 defaults will be used.
325 --epub-stylesheet=FILE
327 Use the specified CSS file to style the EPUB. If no stylesheet
328 is specified, pandoc will look for a file epub.css in the user
329 data directory (see --data-dir, below). If it is not found
330 there, sensible defaults will be used.
331 --epub-metadata=FILE
333 Look in the specified XML file for metadata for the EPUB. The
334 file should contain a series of Dublin Core elements, as docu‐
335 mented at http://dublincore.org/documents/dces/. For example:
336 <dc:rights>Creative Commons</dc:rights>
338 <dc:language>es-AR</dc:language>
339 By default, pandoc will include the following metadata elements:
341 <dc:title> (from the document title), <dc:creator> (from the
342 document authors), <dc:language> (from the locale), and
343 <dc:identifier id="BookId"> (a randomly generated UUID). Any of
344 these may be overridden by elements in the metadata file.
345 -D FORMAT,
347 --print-default-template=FORMAT Print the default template for
348 an output FORMAT. (See -t for a list of possible FORMATs.)
349 -T STRING, --title-prefix=STRING
351 Specify STRING as a prefix at the beginning of the title that
352 appears in the HTML header (but not in the title as it appears
353 at the beginning of the HTML body). Implies --standalone.
354 --bibliography=FILE
356 Specify bibliography database to be used in resolving citations.
357 The database type will be determined from the extension of FILE,
358 which may be .mods (MODS format), .bib (BibTeX format), .bbx
359 (BibLaTeX format), .ris (RIS format), .enl (EndNote format),
360 .xml (EndNote XML format), .wos (ISI format), .medline (MEDLINE
361 format), .copac (Copac format), or .json (citeproc JSON). If
362 you want to use multiple bibliographies, just use this option
363 repeatedly.
364 --csl=FILE
366 Specify CSL style to be used in formatting citations and the
367 bibliography. If FILE is not found, pandoc will look for it in
368 $HOME/.csl
370 in unix and
372 C:\Documents And Settings\USERNAME\Application Data\csl
374 in Windows. If the --csl option is not specified, pandoc will
376 use a default style: either default.csl in the user data direc‐
377 tory (see --data-dir), or, if that is not present, the Chicago
378 author-date style.
379 --data-dir=DIRECTORY
381 Specify the user data directory to search for pandoc data files.
382 If this option is not specified, the default user data directory
383 will be used:
384 $HOME/.pandoc
386 in unix and
388 C:\Documents And Settings\USERNAME\Application Data\pandoc
390 in Windows. A reference.odt, epub.css, templates directory, or
392 s5 directory placed in this directory will override pandoc's
393 normal defaults.
394 --dump-args
396 Print information about command-line arguments to stdout, then
397 exit. This option is intended primarily for use in wrapper
398 scripts. The first line of output contains the name of the out‐
399 put file specified with the -o option, or - (for stdout) if no
400 output file was specified. The remaining lines contain the com‐
401 mand-line arguments, one per line, in the order they appear.
402 These do not include regular Pandoc options and their arguments,
403 but do include any options appearing after a -- separator at the
404 end of the line.
405 --ignore-args
407 Ignore command-line arguments (for use in wrapper scripts).
408 Regular Pandoc options are not ignored. Thus, for example,
409 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
411 is equivalent to
413 pandoc -o foo.html -s
415 -v, --version
417 Print version.
418 -h, --help
420 Show usage message.
421
423 When the -s/--standalone option is used, pandoc uses a template to add
424 header and footer material that is needed for a self-standing document.
425 To see the default template that is used, just type
426 pandoc -D FORMAT
428 where FORMAT is the name of the output format. A custom template can
430 be specified using the --template option. You can also override the
431 system default templates for a given output format FORMAT by putting a
432 file templates/FORMAT.template in the user data directory (see --data-
433 dir, above).
434 Templates may contain variables. Variable names are sequences of
436 alphanumerics, -, and _, starting with a letter. A variable name sur‐
437 rounded by $ signs will be replaced by its value. For example, the
438 string $title$ in
439 <title>$title$</title>
441 will be replaced by the document title.
443 To write a literal $ in a template, use $$.
445 Some variables are set automatically by pandoc. These vary somewhat
447 depending on the output format, but include:
448 header-includes
450 contents specified by -H/--include-in-header (may have multiple
451 values)
452 toc non-null value if --toc/--table-of-contents was specified
454 include-before
456 contents specified by -B/--include-before-body (may have multi‐
457 ple values)
458 include-after
460 contents specified by -A/--include-after-body (may have multiple
461 values)
462 body body of document
464 title title of document, as specified in title block
466 author author of document, as specified in title block (may have multi‐
468 ple values)
469 date date of document, as specified in title block
471 lang language code for HTML documents
473 Variables may be set at the command line using the -V/--variable
475 option. This allows users to include custom variables in their tem‐
476 plates.
477 Templates may contain conditionals. The syntax is as follows:
479 $if(variable)$
481 X
482 $else$
483 Y
484 $endif$
485 This will include X in the template if variable has a non-null value;
487 otherwise it will include Y. X and Y are placeholders for any valid
488 template text, and may include interpolated variables or other condi‐
489 tionals. The $else$ section may be omitted.
490 When variables can have multiple values (for example, author in a
492 multi-author document), you can use the $for$ keyword:
493 $for(author)$
495 <meta name="author" content="$author$" />
496 $endfor$
497 You can optionally specify a separator to be used between consecutive
499 items:
500 $for(author)$$author$$sep$, $endfor$
502
504 You can use Pandoc to produce an HTML + javascript slide presentation
505 that can be viewed via a web browser. There are two ways to do this,
506 using S5 or Slidy.
507 Here's the markdown source for a simple slide show, eating.txt:
509 % Eating Habits
511 % John Doe
512 % March 22, 2005
513 # In the morning
515 - Eat eggs
517 - Drink coffee
518 # In the evening
520 - Eat spaghetti
522 - Drink wine
523 --------------------------
525 
527 To produce the slide show, simply type
529 pandoc -w s5 -s eating.txt > eating.html
531 for S5, or
533 pandoc -w slidy -s eating.txt > eating.html
535 for Slidy.
537 A title page is constructed automatically from the document's title
539 block. Each level-one header and horizontal rule begins a new slide.
540 The file produced by pandoc with the -s/--standalone option embeds a
542 link to javascripts and CSS files, which are assumed to be available at
543 the relative path ui/default (for S5) or at the Slidy website at w3.org
544 (for Slidy). If the --offline option is specified, the scripts and CSS
545 will be included directly in the generated file, so that it may be used
546 offline.
547 You can change the style of the slides by putting customized CSS files
549 in $DATADIR/s5/default (for S5) or $DATADIR/slidy (for Slidy), where
550 $DATADIR is the user data directory (see --data-dir, above). The orig‐
551 inals may be found in pandoc's system data directory (generally
552 $CABALDIR/pandoc-VERSION/s5/default). Pandoc will look there for any
553 files it does not find in the user data directory.
554 Incremental lists
556 By default, these writers produces lists that display "all at once." If
557 you want your lists to display incrementally (one item at a time), use
558 the -i option. If you want a particular list to depart from the
559 default (that is, to display incrementally without the -i option and
560 all at once with the -i option), put it in a block quote:
561 > - Eat spaghetti
563 > - Drink wine
564 In this way incremental and nonincremental lists can be mixed in a sin‐
566 gle document.
567
569 If you append +lhs to an appropriate input or output format (markdown,
570 rst, or latex for input or output; html for output only), pandoc will
571 treat the document as literate Haskell source. This means that
572 · In markdown input, "bird track" sections will be parsed as Haskell
574 code rather than block quotations. Text between \begin{code} and
575 \end{code} will also be treated as Haskell code.
576 · In markdown output, code blocks with class haskell will be rendered
578 using bird tracks, and block quotations will be indented one space,
579 so they will not be treated as Haskell code. In addition, headers
580 will be rendered setext-style (with underlines) rather than atx-style
581 (with '#' characters). (This is because ghc treats '#' characters in
582 column 1 as introducing line numbers.)
583 · In restructured text input, "bird track" sections will be parsed as
585 Haskell code.
586 · In restructured text output, code blocks with class haskell will be
588 rendered using bird tracks.
589 · In LaTeX input, text in code environments will be parsed as Haskell
591 code.
592 · In LaTeX output, code blocks with class haskell will be rendered
594 inside code environments.
595 · In HTML output, code blocks with class haskell will be rendered with
597 class literatehaskell and bird tracks.
598 Examples:
600 pandoc -f markdown+lhs -t html
602 reads literate Haskell source formatted with markdown conventions and
604 writes ordinary HTML (without bird tracks).
605 pandoc -f markdown+lhs -t html+lhs
607 writes HTML with the Haskell code in bird tracks, so it can be copied
609 and pasted as literate Haskell source.
610
612 © 2006-2011 John MacFarlane (jgm at berkeley dot edu). Released under
613 the GPL, version 2 or greater. This software carries no warranty of
614 any kind. (See COPYRIGHT for full copyright and warranty notices.)
615 Other contributors include Recai Oktaş, Paulo Tanimoto, Peter Wang,
616 Andrea Rossato, Eric Kow, infinity0x, Luke Plant, shreevatsa.public,
617 Puneeth Chaganti, Paul Rivier, rodja.trappe, Bradley Kuhn, thsutton,
618 Nathan Gass, Jonathan Daugherty, Jérémy Bobbio, Justin Bogner.
619
621 For a complete description of pandoc's extensions to standard markdown,
622 see pandoc_markdown (5).
623
625 markdown2pdf (1), pandoc_markdown (5).
626 The Pandoc source code and all documentation may be downloaded from
628 <http://johnmacfarlane.net/pandoc/>.
629Pandoc January 29, 2011 PANDOC(1)