5Pandoc is a [Haskell] library for converting from one markup format
6to another, and a command-line tool that uses this library. It can read
7[markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX],
8and it can write [markdown], [reStructuredText], [HTML], [LaTeX], [RTF],
9[DocBook XML], [groff man] pages, and [S5] HTML slide shows. Pandoc's
10version of markdown contains some enhancements, like footnotes and
13In contrast to existing tools for converting markdown to HTML, which
14use regex substitutions, Pandoc has a modular design: it consists of a
15set of readers, which parse text in a given format and produce a native
16representation of the document, and a set of writers, which convert
17this native representation into a target format. Thus, adding an input
18or output format requires only adding a reader or writer.
20[markdown]: http://daringfireball.net/projects/markdown/
21[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
22[S5]: http://meyerweb.com/eric/tools/s5/
23[HTML]: http://www.w3.org/TR/html40/
24[LaTeX]: http://www.latex-project.org/
25[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
26[DocBook XML]: http://www.docbook.org/
27[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
28[Haskell]: http://www.haskell.org/
30(c) 2006 John MacFarlane (jgm at berkeley dot edu). Released under the
31[GPL], version 2 or greater. This software carries no warranty of
32any kind. (See COPYRIGHT for full copyright and warranty notices.)
33Recai Oktaş (roktas at debian dot org) deserves credit for the build
34system, the debian package, and the robust wrapper scripts.
36[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
41The `pandoc` program itself does not depend on any external libraries
44The wrapper script `html2markdown` requires
46 - `pandoc` (which must be in the PATH)
47 - a POSIX-compliant shell (installed by default on all linux and unix
48 systems, including Mac OS X, and in [Cygwin] for Windows),
50 - `iconv` (for character encoding conversion). (If `iconv` is absent,
51 `html2markdown` will still work, but it will treat everything as UTF-8.)
53The wrapper script `markdown2pdf` requires
55 - `pandoc` (which must be in the PATH)
56 - a POSIX-compliant shell
57 - `pdflatex`, which should be part of any [LaTeX] distribution
58 - the [unicode] and [fancyvrb] LaTeX packages, which are included
59 in many LaTeX distributions.[^1] If your installation of LaTeX
60 does not include these packages, you will get an error (complaining
61 about missing `ucs.sty` or `fancyvrb.sty`) when you try to compile
62 a LaTeX file produced by Pandoc, or when you use the `markdown2pdf`
63 script (described below). If this happens, install the [unicode] and
64 [fancyvrb] packages package from [CTAN]. (Get the zip file from CTAN
65 and unpack it into `~/texmf/tex/latex/`. You may also need to run
66 `mktexlsr` or `texhash` before the files can be found by TeX.)
68The wrapper script `hsmarkdown` requires only a POSIX-compliant shell.
70[Cygwin]: http://www.cygwin.com/
71[HTML Tidy]: http://tidy.sourceforge.net/
72[`iconv`]: http://www.gnu.org/software/libiconv/
73[CTAN]: http://www.ctan.org "Comprehensive TeX Archive Network"
74[unicode]: http://www.ctan.org/tex-archive/macros/latex/contrib/unicode/
75[fancyvrb]: http://www.ctan.org/tex-archive/macros/latex/contrib/fancyvrb/
77[^1]: The [unicode] package allows LaTeX to process UTF-8 characters.
78[fancyvrb] allows code blocks and verbatim text to be used within
84If you run `pandoc` without arguments, it will accept input from
85STDIN. If you run it with file names as arguments, it will take input
86from those files. By default, `pandoc` writes its output to STDOUT.
87If you want to write to a file, use the `-o` option:
89 pandoc -o hello.html hello.txt
91Note that you can specify multiple input files on the command line.
92`pandoc` will concatenate them all (with blank lines between them)
95 pandoc -s chapter1.txt chapter2.txt references.txt > book.html
97(The `-s` option here tells `pandoc` to produce a standalone HTML file,
98with a proper header, rather than a fragment. For more details on this
99and many other command-line options, see below.)
101The format of the input and output can be specified explicitly using
102command-line options. The input format can be specified using the
103`-r/--read` or `-f/--from` options, the output format using the
104`-w/--write` or `-t/--to` options. Thus, to convert `hello.txt` from
105markdown to LaTeX, you could type:
107 pandoc -f markdown -t latex hello.txt
109To convert `hello.html` from html to markdown:
111 pandoc -f html -t markdown hello.html
113Supported output formats include `markdown`, `latex`, `html`, `rtf`
114(rich text format), `rst` (reStructuredText), `docbook` (DocBook
115XML), `man` (groff man), and `s5` (which produces an HTML file that
116acts like powerpoint). Supported input formats include `markdown`,
117`html`, `latex`, and `rst`. Note that the `rst` reader only parses
118a subset of reStructuredText syntax. For example, it doesn't handle
119tables, definition lists, option lists, or footnotes. It handles only
120the constructs expressible in unextended markdown. But for simple
121documents it should be adequate. The `latex` and `html` readers are also
122limited in what they can do. Because the `html` reader is picky about
123the HTML it parses, it is recommended that you pipe HTML through [HTML
124Tidy] before sending it to `pandoc`, or use the `html2markdown` script
127If you don't specify a reader or writer explicitly, `pandoc` will
128try to determine the input and output format from the extensions of
129the input and output filenames. Thus, for example,
131 pandoc -o hello.tex hello.txt
133will convert `hello.txt` from markdown to LaTeX. If no output file
134is specified (so that output goes to STDOUT), or if the output file's
135extension is unknown, the output format will default to HTML.
136If no input file is specified (so that input comes from STDIN), or
137if the input files' extensions are unknown, the input format will
138be assumed to be markdown unless explicitly specified.
143All input is assumed to be in the UTF-8 encoding, and all output
144is in UTF-8. If your local character encoding is not UTF-8 and you use
145accented or foreign characters, you should pipe the input and output
146through [`iconv`]. For example,
148 iconv -t utf-8 source.txt | pandoc | iconv -f utf-8 > output.html
150will convert `source.txt` from the local encoding to UTF-8, then
151convert it to HTML, then convert back to the local encoding,
152putting the output in `output.html`.
154The shell scripts (described below) automatically convert the input
155from the local encoding to UTF-8 before running them through `pandoc`,
156then convert the output back to the local encoding.
161Three shell scripts, `markdown2pdf`, `html2markdown`, and `hsmarkdown`,
162are included in the standard Pandoc installation. (They are not included
163in the Windows binary package, as they require a POSIX shell, but they
164may be used in Windows under Cygwin.)
1661. `markdown2pdf` produces a PDF file from markdown-formatted
167 text, using `pandoc` and `pdflatex`. The default
168 behavior of `markdown2pdf` is to create a file with the same
169 base name as the first argument and the extension `pdf`; thus,
172 markdown2pdf sample.txt endnotes.txt
174 will produce `sample.pdf`. (If `sample.pdf` exists already,
175 it will be backed up before being overwritten.) An output file
176 name can be specified explicitly using the `-o` option:
178 markdown2pdf -o "My Book.pdf" chap1.txt chap2.txt chap3.txt
180 If no input file is specified, input will be taken from STDIN.
181 All of `pandoc`'s options will work with `markdown2pdf` as well.
1832. `html2markdown` grabs a web page from a file or URL and converts
184 it to markdown-formatted text, using `tidy` and `pandoc`.
186 All of `pandoc`'s options will work with `html2markdown` as well.
187 In addition, the following special options may be used.
188 The special options must be separated from the `html2markdown`
189 command and any regular Pandoc options by the delimiter `--`:
191 html2markdown -o out.txt -- -e latin1 -g curl google.com
193 The `-e` or `--encoding` option specifies the character encoding
194 of the HTML input. If this option is not specified, and input
195 is not from STDIN, `html2markdown` will attempt to determine the
196 page's character encoding from the "Content-type" meta tag.
197 If this is not present, UTF-8 is assumed.
199 The `-g` or `--grabber` option specifies the command to be used to
200 fetch the contents of a URL:
202 html2markdown -g 'curl --user foo:bar' www.mysite.com
204 If this option is not specified, `html2markdown` searches for an
205 available program (`wget`, `curl`, or a text-mode browser) to fetch
206 the contents of a URL.
2083. `hsmarkdown` is designed to be used as a drop-in replacement for
209 `Markdown.pl`. It forces `pandoc` to convert from markdown to
210 HTML, and to use the `--strict` flag for maximal compliance with
211 official markdown syntax. (All of Pandoc's syntax extensions and
212 variants, described below, are disabled.) No other command-line
213 options are allowed. (In fact, options will be interpreted as
216 As an alternative to using the `hsmarkdown` shell script, the
217 user may create a symbolic link to `pandoc` called `hsmarkdown`.
218 When invoked under the name `hsmarkdown`, `pandoc` will behave
219 as if the `--strict` flag had been selected, and no command-line
220 options will be recognized. However, this approach does not work
221 under Cygwin, due to problems with its simulation of symbolic
227Various command-line options can be used to customize the output.
228For further documentation, see the `pandoc(1)` man page.
230`-f`, `--from`, `-r`, or `--read` can be used to specify the input
231format -- the format Pandoc will be converting *from*. Available
232formats are `native`, `markdown`, `rst`, `html`, and `latex`.
234`-t`, `--to`, `-w`, or `--write` can be used to specify the output
235format -- the format Pandoc will be converting *to*. Available formats
236are `native`, `html`, `s5`, `docbook`, `latex`, `markdown`, `rst`, and
239`-s` or `--standalone` indicates that a standalone document is to be
240produced (with appropriate headers and footers), rather than a fragment.
242`-o` or `--output` specifies the name of the output file. If this
243option is not specified, or if its argument is `-`, output will be sent
246`-p` or `--preserve-tabs` causes tabs in the source text to be
247preserved, rather than converted to spaces (the default).
249`--tabstop` allows the user to set the tab stop (which defaults to 4).
251`--strict` specifies that strict markdown syntax is to be used, without
252pandoc's usual extensions and variants (described below).
254`--reference-links` causes reference-style links to be used in markdown
255and reStructuredText output. By default inline links are used.
257`-R` or `--parse-raw` causes the HTML and LaTeX readers to parse HTML
258codes and LaTeX environments that it can't translate as raw HTML or
259LaTeX. Raw HTML can be printed in markdown, reStructuredText, HTML,
260and S5 output; raw LaTeX can be printed in markdown, reStructuredText,
261and LaTeX output. The default is for the readers to omit
262untranslatable HTML codes and LaTeX environments. (The LaTeX reader
263does pass through untranslatable LaTeX commands, even if `-R` is not
266`-C` or `--custom-header` can be used to specify a custom document
267header. To see the headers used by default, use the `-D` option:
268for example, `pandoc -D html` prints the default HTML header.
270`-c` or `--css` allows the user to specify a custom stylesheet that
271will be linked to in HTML and S5 output.
273`-H` or `--include-in-header` specifies a file to be included
274(verbatim) at the end of the document header. This can be used, for
275example, to include special CSS or javascript in HTML documents.
277`-B` or `--include-before-body` specifies a file to be included
278(verbatim) at the beginning of the document body (after the `<body>`
279tag in HTML, or the `\begin{document}` command in LaTeX). This can be
280used to include navigation bars or banners in HTML documents.
282`-A` or `--include-after-body` specifies a file to be included
283(verbatim) at the end of the docment body (before the `</body>` tag in
284HTML, or the `\end{document}` command in LaTeX).
286`-T` or `--title-prefix` specifies a string to be included as a prefix
287at the beginning of the title that appears in the HTML header (but not
288in the title as it appears at the beginning of the HTML body). (See
291`-S` or `--smart` causes `pandoc` to produce typographically
292correct output, along the lines of John Gruber's [Smartypants].
293Straight quotes are converted to curly quotes, `---` to dashes, and
294`...` to ellipses. (Note: This option is only significant when
295the input format is `markdown`. It is selected automatically
296when the output format is `latex`.)
298[Smartypants]: http://daringfireball.net/projects/smartypants/
300`-m` or `--asciimathml` will cause LaTeX formulas (between $ signs) in
301HTML or S5 to display as formulas rather than as code. The trick will
302not work in all browsers, but it works in Firefox. Peter Jipsen's
303[ASCIIMathML] script is used to do the magic.
305[ASCIIMathML]: http://www1.chapman.edu/~jipsen/mathml/asciimath.html
307`-i` or `--incremental` causes all lists in S5 output to be displayed
308incrementally by default (one item at a time). The normal default
309is for lists to be displayed all at once.
311`-N` or `--number-sections` causes sections to be numbered in LaTeX
312output. By default, sections are not numbered.
314`--dump-args` is intended to make it easier to create wrapper scripts
315that use Pandoc. It causes Pandoc to dump information about the arguments
316with which it was called to STDOUT, then exit. The first line printed
317is the name of the output file specified using the `-o` or `--output`
318option, or `-` if output would go to STDOUT. The remaining lines, if any,
319list command-line arguments. These will include the names of input
320files and any special options passed after ` -- ` on the command line.
323 pandoc --dump-args -o foo.html -s foo.txt appendix.txt -- -e latin1
325will cause the following to be printed to STDOUT:
333`--ignore-args` causes Pandoc to ignore all command-line arguments.
334Regular Pandoc options are not ignored. Thus, for example,
336 pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1
340 pandoc -o foo.html -s
342`-v` or `--version` prints the version number to STDERR.
344`-h` or `--help` prints a usage message to STDERR.
346Pandoc's markdown vs. standard markdown
347=======================================
349In parsing markdown, Pandoc departs from and extends [standard markdown]
350in a few respects. (To run Pandoc on the official markdown test suite,
351type `make test-markdown`.) Except where noted, these differences can
352be suppressed by specifying the `--strict` command-line option or by
353using the `hsmarkdown` wrapper.
355[standard markdown]: http://daringfireball.net/projects/markdown/syntax
356 "Markdown syntax description"
361Except inside a code block or inline code, any punctuation or space
362character preceded by a backslash will be treated literally, even if it
363would normally indicate formatting. Thus, for example, if one writes
373 <strong>hello</strong>
375This rule is easier to remember than standard markdown's rule,
376which allows only the following characters to be backslash-escaped:
383Pandoc behaves differently from standard markdown on some "edge
384cases" involving lists. Consider this source:
394Pandoc transforms this into a "compact list" (with no `<p>` tags
395around "First", "Second", or "Third"), while markdown puts `<p>`
396tags around "Second" and "Third" (but not "First"), because of
397the blank space around "Third". Pandoc follows a simple rule:
398if the text is followed by a blank line, it is treated as a
399paragraph. Since "Second" is followed by a list, and not a blank
400line, it isn't treated as a paragraph. The fact that the list
401is followed by a blank line is irrelevant. (Note: Pandoc works
402this way even when the `--strict` option is specified. This
403behavior is consistent with the official markdown syntax
404description, even though it is different from that of `Markdown.pl`.)
406Unlike standard markdown, Pandoc allows ordered list items to be
407marked with single lowercase letters (from 'a' to 'n'), instead of
408numbers. So, for example, this source yields a nested ordered list:
416The letters may be followed by either '.' or ')':
424Note that Pandoc pays no attention to the *type* of ordered list
425item marker used. Thus, the following is treated just the same as
437Pandoc supports definition lists, using a syntax inspired by
438[PHP Markdown Extra] and [reStructuredText]:
440 [PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/
448 : Second paragraph of definition 2.
450Each term must fit on one line. The definition must begin on the line
451after the term. The definition consists of one or more block elements
452(paragraph, code block, list, etc.), each beginning with a colon and
453(aside from the colon) indented one tab stop.
455 Term *with inline markup*
456 : Here is the definition. It may
457 contain multiple blocks. Here is some code:
461 : Here is the third paragraph of this definition.
463If you leave space after the definition (as in the first example above),
464the definitions will be considered paragraphs. In some output formats,
465this will mean greater spacing between term/definition pairs. For a
466compact definition list, do not leave space between the definition and
477Pandoc allows implicit reference links with just a single set of
478brackets. So, the following links are equivalent:
481 2. Here's my [link][]
485(Note: Pandoc works this way even if `--strict` is specified, because
486`Markdown.pl` 1.0.2b7 allows single-bracket links.)
491Pandoc's markdown allows footnotes, using the following syntax:
493 Here is a footnote reference,[^1] and another.[^longnote]
495 [^1]: Here is the footnote. It can go anywhere in the document,
496 except in embedded contexts like block quotes or lists.
498 [^longnote]: Here's the other note. This one contains multiple
501 Subsequent paragraphs are indented to show that they belong to
502 the previous footnote.
506 The whole paragraph can be indented, or just the first line.
507 In this way, multi-paragraph footnotes work just like
508 multi-paragraph list items in markdown.
510 This paragraph won't be part of the note, because it isn't indented.
512The identifiers in footnote references may not contain spaces, tabs,
513or newlines. These identifiers are used only to correlate the
514footnote reference with the note itself; in the output, footnotes
515will be numbered sequentially.
517The footnotes themselves need not be placed at the end of the
518document. They may appear anywhere except inside other block elements
519(lists, block quotes, tables, etc.).
521Inline footnotes are also allowed (though, unlike regular notes,
522they cannot contain multiple paragraphs). The syntax is as follows:
524 Here is an inline note.^[Inlines notes are easier to write, since
525 you don't have to pick an identifier and move down to type the
528Inline and regular footnotes may be mixed freely.
533Two kinds of tables may be used. Both kinds presuppose the use of
534a fixed-width font, such as Courier. Currently only the HTML,
535Docbook, and LaTeX writers support tables.
537Simple tables look like this:
539 Right Left Center Default
540 ------- ------ ---------- -------
545 Table: Demonstration of simple table syntax.
547The headers and table rows must each fit on one line. Column
548alignments are determined by the position of the header text relative
549to the dashed line below it:[^2]
551 - If the dashed line is flush with the header text on the right side
552 but extends beyond it on the left, the column is right-aligned.
553 - If the dashed line is flush with the header text on the left side
554 but extends beyond it on the right, the column is left-aligned.
555 - If the dashed line extends beyond the header text on both sides,
556 the column is centered.
557 - If the dashed line is flush with the header text on both sides,
558 the default alignment is used (in most cases, this will be left).
560[^2]: This scheme is due to Michel Fortin, who proposed it on the
561 Markdown discussion list: <http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html>
563The table must end with a blank line. Optionally, a caption may be
564provided (as illustrated in the example above). A caption is a paragraph
565beginning with the string `Table:`, which will be stripped off.
567The table parser pays attention to the widths of the columns, and
568the writers try to reproduce these relative widths in the output.
569So, if you find that one of the columns is too narrow in the output,
570try widening it in the markdown source.
572Multiline tables allow headers and table rows to span multiple lines
573of text. Here is an example:
575 ---------------------------------------------------------------
577 Header Aligned Aligned Default aligned
578 ---------- --------- ----------- ---------------------------
579 First row 12.0 Example of a row that spans
582 Second row 5.0 Here's another one. Note
583 the blank line between rows.
584 ---------------------------------------------------------------
586 Table: Optional caption. This, too, may span multiple
589These work like simple tables, but with the following differences:
591 - They must begin with a row of dashes, before the header text.
592 - They must end with a row of dashes, then a blank line.
593 - The rows must be separated by blank lines.
598Pandoc treats embedded HTML in markdown a bit differently than
599Markdown 1.0. While Markdown 1.0 leaves HTML blocks exactly as they
600are, Pandoc treats text between HTML tags as markdown. Thus, for
601example, Pandoc will turn
606 <td>[a link](http://google.com)</td>
614 <td><em>one</em></td>
615 <td><a href="http://google.com">a link</a></td>
619whereas `Markdown.pl` will preserve it as is.
621There is one exception to this rule: text between `<script>` and
622`</script>` tags is not interpreted as markdown.
624This departure from standard markdown should make it easier to mix
625markdown with HTML block elements. For example, one can surround
626a block of markdown text with `<div>` tags without preventing it
627from being interpreted as markdown.
632If the file begins with a title block
635 % author(s) (separated by commas)
638it will be parsed as bibliographic information, not regular text. (It
639will be used, for example, in the title of standalone LaTeX or HTML
640output.) The block may contain just a title, a title and an author,
641or all three lines. Each must begin with a % and fit on one line.
642The title may contain standard inline formatting. If you want to
643include an author but no title, or a title and a date but no author,
644you need a blank line:
650Titles will be written only when the `--standalone` (`-s`) option is
651chosen. In HTML output, titles will appear twice: once in the
652document head -- this is the title that will appear at the top of the
653window in a browser -- and once at the beginning of the document body.
654The title in the document head can have an optional prefix attached
655(`--title-prefix` or `-T` option). The title in the body appears as
656an H1 element with class "title", so it can be suppressed or
657reformatted with CSS. If a title prefix is specified with `-T` and no
658title block appears in the document, the title prefix will be used by
659itself as the HTML title.
661The man page writer extracts a title, man page section number, and
662other header and footer information from the title line. These should
663be separated by pipe characters (`|`), as follows:
665 % title | section number (1-9) | footer left | header center
669 % pandoc | 1 | Pandoc User Manuals | Version 4.0
671The middle of the man page footer is used for the date.
676Pandoc supports emacs-style boxquote block quotes, in addition to
677standard markdown (email-style) block quotes:
680 | They look like this.
683Blank lines before headers and blockquotes
684------------------------------------------
686Standard markdown syntax does not require a blank line before a header
687or blockquote. Pandoc does require this (except, of course, at the
688beginning of the document). The reason for the requirement is that
689it is all too easy for a `>` or `#` to end up at the beginning of a
690line by accident (perhaps through line wrapping). Consider, for
693 I like several of their flavors of ice cream: #22, for example, and
699Anything between two $ characters will be parsed as LaTeX math. The
700opening $ must have a character immediately to its right, while the
701closing $ must have a character immediately to its left. Thus,
702`$20,000 and $30,000` won't parse as math. The $ character can be
703escaped with a backslash if needed.
705If you pass the `-m` (`--asciimathml`) option to `pandoc`, it will
706include the [ASCIIMathML] script in the resulting HTML. This will
707cause LaTeX math to be displayed as formulas in better browsers.
709[ASCIIMathML]: http://www1.chapman.edu/~jipsen/asciimath.html
711Inline LaTeX commands will also be preserved and passed unchanged
712to the LaTeX writer. Thus, for example, you can use LaTeX to
713include BibTeX citations:
715 This result was proved in \cite{jones.1967}.
717You can also use LaTeX environments. For example,
719 \begin{tabular}{|l|l|}\hline
720 Age & Frequency \\ \hline
723 36--45 & 22 \\ \hline
726Note, however, that material between the begin and end tags will
727be interpreted as raw LaTeX, not as markdown.
732When run with the "standalone" option (`-s`), `pandoc` creates a
733standalone file, complete with an appropriate header. To see the
734default headers used for html and latex, use the following commands:
740If you want to use a different header, just create a file containing
741it and specify it on the command line as follows:
743 pandoc --header=MyHeaderFile
745Producing S5 with Pandoc
746========================
748Producing an [S5] web-based slide show with Pandoc is easy. A title
749page is constructed automatically from the document's title block (see
750above). Each section (with a level-one header) produces a single slide.
751(Note that if the section is too big, the slide will not fit on the page;
752S5 is not smart enough to produce multiple pages.)
754Here's the markdown source for a simple slide show, `eating.txt`:
770To produce the slide show, simply type
772 pandoc -w s5 -s eating.txt > eating.html
774and open up `eating.html` in a browser. The HTML file embeds
775all the required javascript and CSS, so no other files are necessary.
777Note that by default, the S5 writer produces lists that display
778"all at once." If you want your lists to display incrementally
779(one item at a time), use the `-i` option. If you want a
780particular list to depart from the default (that is, to display
781incrementally without the `-i` option and all at once with the
782`-i` option), put it in a block quote:
787In this way incremental and nonincremental lists can be mixed in
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