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],
9and [S5] HTML slide shows. Pandoc's version of markdown contains some
10enhancements, like footnotes and embedded LaTeX.
12In contrast to existing tools for converting markdown to HTML, which
13use regex substitutions, Pandoc has a modular design: it consists of a
14set of readers, which parse text in a given format and produce a native
15representation of the document, and a set of writers, which convert
16this native representation into a target format. Thus, adding an input
17or output format requires only adding a reader or writer.
19[markdown]: http://daringfireball.net/projects/markdown/
20[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
21[S5]: http://meyerweb.com/eric/tools/s5/
22[HTML]: http://www.w3.org/TR/html40/
23[LaTeX]: http://www.latex-project.org/
24[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
25[Haskell]: http://www.haskell.org/
27(c) 2006 John MacFarlane (jgm At berkeley.edu). Released under the
28[GPL], version 2 or greater. This software carries no warranty of
29any kind. (See LICENSE for full copyright and warranty notices.)
30Recai Oktaş (roktas At debian.org) deserves credit for the build
31system, the debian package, and the robust wrapper scripts.
33[GPL]: http://www.gnu.org/copyleft/gpl.html
37If you run `pandoc` without arguments, it will accept input from
38STDIN. If you run it with file names as arguments, it will take input
39from those files. It accepts several command-line options. For a
44The most important options specify the format of the source file and
45the output. The default reader is markdown; the default writer is
46HTML. So if you don't specify a reader or writer, `pandoc` will
47convert markdown to HTML. For example,
51will convert `hello.txt` from markdown to HTML. For other conversions,
52you must specify a reader and/or a writer using the `-r` and `-w`
53flags. To convert markdown to LaTeX, you would write:
55 pandoc -w latex hello.txt
57To convert html to markdown:
59 pandoc -r html -w markdown hello.txt
61Supported writers include `markdown`, `latex`, `html`, `rtf` (rich text
62format), `rst` (reStructuredText), and `s5` (which produces an HTML
63file that acts like powerpoint). Supported readers include `markdown`,
64`html`, `latex`, and `rst`. Note that the `rst` reader only parses
65a subset of reStructuredText syntax. For example, it doesn't handle
66tables, definition lists, option lists, or footnotes. It handles only the
67constructs expressible in unextended markdown. But for simple documents
68it should be adequate. The `latex` and `html` readers are also limited
71`pandoc` writes its output to STDOUT. If you want to write to a file,
74 pandoc hello.txt > hello.html
76Note that you can specify multiple input files on the command line.
77`pandoc` will concatenate them all (with blank lines between them)
80 pandoc -s chapter1.txt chapter2.txt chapter3.txt references.txt > book.html
82(The `-s` option here tells `pandoc` to produce a standalone HTML file,
83with a proper header, rather than a fragment. For more details on this
84and many other command-line options, see below.)
88Unfortunately, due to limitations in GHC, `pandoc` does not automatically
89detect the system's local character encoding. Hence, all input and
90output is assumed to be in the UTF-8 encoding. If your local character
91encoding is not UTF-8 and you use accented or foreign characters,
92you should pipe the input and output through [`iconv`]. For example,
94 iconv -t utf-8 source.txt | pandoc | iconv -f utf-8 > output.html
96will convert `source.txt` from the local encoding to UTF-8, then
97convert it to HTML, then convert back to the local encoding,
98putting the output in `output.html`.
100[`iconv`]: http://www.gnu.org/software/libiconv/
102The shell scripts (described below) automatically convert the input
103from the local encoding to UTF-8 before running them through `pandoc`,
104then convert the output back to the local encoding.
108For convenience, five shell scripts have been included that make it
109easy to run `pandoc` without remembering all the command-line options.
110All of the scripts use `iconv` to convert to and from the local
111character encoding. All of the scripts presuppose that `pandoc`
112is in the path, and some have additional requirements. (For example,
113`html2markdown` uses `tidy`, and `markdown2pdf` uses `pdflatex`.)
1151. `markdown2html` converts markdown to HTML. (This can be used
116 as a replacement for `Markdown.pl`.)
1182. `html2markdown` can take either a filename or a URL as argument. If
119 it is given a URL, it uses `curl`, `wget`, or an available text-based
120 browser to fetch the contents of the specified URL, then filters this
121 through `tidy` to straighten up the HTML, and finally passes
122 this HTML to `pandoc` to produce markdown text:
124 html2markdown http://www.fsf.org
126 html2markdown www.fsf.org
128 html2markdown subdir/mylocalfile.html
1303. `latex2markdown` converts a LaTeX file to markdown:
132 latex2markdown mytexfile.tex
1344. `markdown2latex` converts markdown to LaTeX:
136 markdown2latex mytextfile.txt
1385. `markdown2pdf` converts markdown to PDF using `pdflatex`:
140 markdown2pdf mytextfile.txt
142 creates a file `mytextfile.pdf`.
144# Command-line options
146Various command-line options can be used to customize the output.
147For a complete list, type
151`-p` or `--preserve-tabs` causes tabs in the source text to be
152preserved, rather than converted to spaces (the default).
154`--tabstop` allows the user to set the tab stop (which defaults to 4).
156`-R` or `--parse-raw` causes the HTML and LaTeX readers to parse HTML
157codes and LaTeX environments that it can't translate as raw HTML or
158LaTeX. Raw HTML can be printed in markdown, reStructuredText, HTML,
159and S5 output; raw LaTeX can be printed in markdown, reStructuredText,
160and LaTeX output. The default is for the readers to omit
161untranslatable HTML codes and LaTeX environments. (The LaTeX reader
162does pass through untranslatable LaTeX commands, even if `-R` is not
165`-s` or `--standalone` causes `pandoc` to produce a standalone file,
166complete with appropriate document headers. By default, `pandoc`
169`--custom-header` can be used to specify a custom document header. To
170see the headers used by default, use the `-D` option: for example,
171`pandoc -D html` prints the default HTML header.
173`-c` or `--css` allows the user to specify a custom stylesheet that
174will be linked to in HTML and S5 output.
176`-H` or `--include-in-header` specifies a file to be included
177(verbatim) at the end of the document header. This can be used, for
178example, to include special CSS or javascript in HTML documents.
180`-B` or `--include-before-body` specifies a file to be included
181(verbatim) at the beginning of the document body (after the `<body>`
182tag in HTML, or the `\begin{document}` command in LaTeX). This can be
183used to include navigation bars or banners in HTML documents.
185`-A` or `--include-after-body` specifies a file to be included
186(verbatim) at the end of the docment body (before the `</body>` tag in
187HTML, or the `\end{document}` command in LaTeX).
189`-T` or `--title-prefix` specifies a string to be included as a prefix
190at the beginning of the title that appears in the HTML header (but not
191in the title as it appears at the beginning of the HTML body). (See
194`-S` or `--smartypants` causes `pandoc` to produce typographically
195correct HTML output, along the lines of John Gruber's [Smartypants].
196Straight quotes are converted to curly quotes, `---` to dashes, and
199[Smartypants]: http://daringfireball.net/projects/smartypants/
201`-m` or `--asciimathml` will cause LaTeX formulas (between $ signs) in
202HTML or S5 to display as formulas rather than as code. The trick will
203not work in all browsers, but it works in Firefox. Peter Jipsen's
204[ASCIIMathML] script is used to do the magic.
206[ASCIIMathML]: http://www1.chapman.edu/~jipsen/mathml/asciimath.html
208`-i` or `--incremental` causes all lists in S5 output to be displayed
209incrementally by default (one item at a time). The normal default
210is for lists to be displayed all at once.
212`-N` or `--number-sections` causes sections to be numbered in LaTeX
213output. By default, sections are not numbered.
215# Pandoc's markdown vs. standard markdown
217In parsing markdown, Pandoc departs from and extends [standard markdown]
218in a few respects. (To run Pandoc on the official
219markdown test suite, type `make test-markdown`.)
221[standard markdown]: http://daringfireball.net/projects/markdown/syntax
225Pandoc behaves differently from standard markdown on some "edge
226cases" involving lists. Consider this source:
236Pandoc transforms this into a "compact list" (with no `<p>` tags
237around "First", "Second", or "Third"), while markdown puts `<p>`
238tags around "Second" and "Third" (but not "First"), because of
239the blank space around "Third". Pandoc follows a simple rule:
240if the text is followed by a blank line, it is treated as a
241paragraph. Since "Second" is followed by a list, and not a blank
242line, it isn't treated as a paragraph. The fact that the list
243is followed by a blank line is irrelevant.
245## Literal quotes in titles
247Standard markdown allows unescaped literal quotes in titles, as
250 [foo]: "bar "embedded" baz"
252Pandoc requires all quotes within titles to be escaped:
254 [foo]: "bar \"embedded\" baz"
258Pandoc allows implicit reference links in either of two styles:
261 2. Here's my [link][]
265If there's no corresponding reference, the implicit reference link
266will appear as regular bracketed text. Note: even `[link][]` will
267appear as `[link]` if there's no reference for `link`. If you want
268`[link][]`, use a backslash escape: `\[link]\[]`.
272Pandoc's markdown allows footnotes, using the following syntax:
274 here is a footnote reference,^(1) and another.^(longnote)
276 ^(1) Here is the footnote. It can go anywhere in the document,
277 except in embedded contexts like block quotes or lists.
279 ^(longnote) Here's the other note. This one contains multiple
282 ^ Caret characters are used to indicate that the blocks all belong
283 to a single footnote (as with block quotes).
285 ^ If you want, you can use a caret at the beginning of every line,
286 ^ as with blockquotes, but all that you need is a caret at the
287 ^ beginning of the first line of the block and any preceding
290Footnote references may not contain spaces, tabs, or newlines.
294Pandoc treats embedded HTML in markdown a bit differently than
295Markdown 1.0. While Markdown 1.0 leaves HTML blocks exactly as they
296are, Pandoc treats text between HTML tags as markdown. Thus, for
297example, Pandoc will turn
302 <td>[a link](http://google.com)</td>
310 <td><em>one</em></td>
311 <td><a href="http://google.com">a link</a></td>
315whereas Markdown 1.0 will preserve it as is.
317There is one exception to this rule: text between `<script>` and
318`</script>` tags is not interpreted as markdown.
320This departure from standard markdown should make it easier to mix
321markdown with HTML block elements. For example, one can surround
322a block of markdown text with `<div>` tags without preventing it
323from being interpreted as markdown.
327If the file begins with a title block
330 % author(s) (separated by commas)
333it will be parsed as bibliographic information, not regular text. (It
334will be used, for example, in the title of standalone LaTeX or HTML
335output.) The block may contain just a title, a title and an author,
336or all three lines. Each must begin with a % and fit on one line.
337The title may contain standard inline formatting. If you want to
338include an author but no title, or a title and a date but no author,
339you need a blank line:
345Titles will be written only when the `--standalone` (`-s`) option is
346chosen. In HTML output, titles will appear twice: once in the
347document head -- this is the title that will appear at the top of the
348window in a browser -- and once at the beginning of the document body.
349The title in the document head can have an optional prefix attached
350(`--title-prefix` or `-T` option). The title in the body appears as
351an H1 element with class "title", so it can be suppressed or
354If a title prefix is specified with `-T` and no title block appears
355in the document, the title prefix will be used by itself as the
358## Box-style blockquotes
360Pandoc supports emacs-style boxquote block quotes, in addition to
361standard markdown (email-style) boxquotes:
364 | They look like this.
369Anything between two $ characters will be parsed as LaTeX math. The
370opening $ must have a character immediately to its right, while the
371closing $ must have a character immediately to its left. Thus,
372`$20,000 and $30,000` won't parse as math. The $ character can be
373escaped with a backslash if needed.
375If you pass the `-m` (`--asciimathml`) option to `pandoc`, it will
376include the [ASCIIMathML] script in the resulting HTML. This will
377cause LaTeX math to be displayed as formulas in better browsers.
379[ASCIIMathML]: http://www1.chapman.edu/~jipsen/asciimath.html
381Inline LaTeX commands will also be preserved and passed unchanged
382to the LaTeX writer. Thus, for example, you can use LaTeX to
383include BibTeX citations:
385 This result was proved in \cite{jones.1967}.
387You can also use LaTeX environments. For example,
389 \begin{tabular}{|l|l|}\hline
390 Age & Frequency \\ \hline
393 36--45 & 22 \\ \hline
396Note, however, that material between the begin and end tags will
397be interpreted as raw LaTeX, not as markdown.
401When run with the "standalone" option (`-s`), `pandoc` creates a
402standalone file, complete with an appropriate header. To see the
403default headers used for html and latex, use the following commands:
409If you want to use a different header, just create a file containing
410it and specify it on the command line as follows:
412 pandoc --header=MyHeaderFile
414# Producing S5 with Pandoc
416Producing an [S5] slide show with Pandoc is easy. A title page is
417constructed automatically from the document's title block (see above).
418Each section (with a level-one header) produces a single slide. (Note
419that if the section is too big, the slide will not fit on the page; S5
420is not smart enough to produce multiple pages.)
422Here's the markdown source for a simple slide show, `eating.txt`:
438To produce the slide show, simply type
440 pandoc -w s5 -s eating.txt > eating.html
442and open up `eating.html` in a browser. The HTML file embeds
443all the required javascript and CSS, so no other files are necessary.
445Note that by default, the S5 writer produces lists that display
446"all at once." If you want your lists to display incrementally
447(one item at a time), use the `-i` option. If you want a
448particular list to depart from the default (that is, to display
449incrementally without the `-i` option and all at once with the
450`-i` option), put it in a block quote:
455In 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