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 you use accented or
91foreign characters, you should convert the input file to UTF-8 before
92processing it with `pandoc`. This can be done by piping the input through
93[`iconv`]: for example,
95 iconv -t utf-8 source.txt | pandoc > output.html
97will convert `source.txt` from the local encoding to UTF-8, then
98convert it to HTML, putting the output in `output.html`.
100[`iconv`]: http://www.gnu.org/software/libiconv/
102The shell scripts (described below) automatically convert the source
103from the local encoding to UTF-8 before running them through `pandoc`.
107For convenience, five shell scripts have been included that make it
108easy to run `pandoc` without remembering all the command-line options.
109All of the scripts presuppose that `pandoc` is in the path, and
110some have additional requirements. (For example, `html2markdown`
111uses `tidy`, and `markdown2pdf` uses `pdflatex`.)
1131. `markdown2html` converts markdown to HTML, running `iconv` first to
114 convert the file to UTF-8. (This can be used as a replacement for
1172. `html2markdown` can take either a filename or a URL as argument. If
118 it is given a URL, it uses `curl`, `wget`, or an available text-based
119 browser to fetch the contents of the specified URL, then filters this
120 through `tidy` to straighten up the HTML and convert to UTF-8,
121 and finally passes this HTML to `pandoc` to produce markdown text:
123 html2markdown http://www.fsf.org
125 html2markdown www.fsf.org
127 html2markdown subdir/mylocalfile.html
1293. `latex2markdown` converts a LaTeX file to markdown.
131 latex2markdown mytexfile.tex
1334. `markdown2latex` converts markdown to LaTeX:
135 markdown2latex mytextfile.txt
1375. `markdown2pdf` converts markdown to PDF using `pdflatex`. Example:
139 markdown2pdf mytextfile.txt
141 creates a file `mytextfile.pdf`.
143# Command-line options
145Various command-line options can be used to customize the output.
146For a complete list, type
150`-p` or `--preserve-tabs` causes tabs in the source text to be
151preserved, rather than converted to spaces (the default).
153`--tabstop` allows the user to set the tab stop (which defaults to 4).
155`-R` or `--parse-raw` causes the HTML and LaTeX readers to parse HTML
156codes and LaTeX environments that it can't translate as raw HTML or
157LaTeX. Raw HTML can be printed in markdown, reStructuredText, HTML,
158and S5 output; raw LaTeX can be printed in markdown, reStructuredText,
159and LaTeX output. The default is for the readers to omit
160untranslatable HTML codes and LaTeX environments. (The LaTeX reader
161does pass through untranslatable LaTeX commands, even if `-R` is not
164`-s` or `--standalone` causes `pandoc` to produce a standalone file,
165complete with appropriate document headers. By default, `pandoc`
168`--custom-header` can be used to specify a custom document header. To
169see the headers used by default, use the `-D` option: for example,
170`pandoc -D html` prints the default HTML header.
172`-c` or `--css` allows the user to specify a custom stylesheet that
173will be linked to in HTML and S5 output.
175`-H` or `--include-in-header` specifies a file to be included
176(verbatim) at the end of the document header. This can be used, for
177example, to include special CSS or javascript in HTML documents.
179`-B` or `--include-before-body` specifies a file to be included
180(verbatim) at the beginning of the document body (after the `<body>`
181tag in HTML, or the `\begin{document}` command in LaTeX). This can be
182used to include navigation bars or banners in HTML documents.
184`-A` or `--include-after-body` specifies a file to be included
185(verbatim) at the end of the docment body (before the `</body>` tag in
186HTML, or the `\end{document}` command in LaTeX).
188`-T` or `--title-prefix` specifies a string to be included as a prefix
189at the beginning of the title that appears in the HTML header (but not
190in the title as it appears at the beginning of the HTML body). (See
193`-S` or `--smartypants` causes `pandoc` to produce typographically
194correct HTML output, along the lines of John Gruber's [Smartypants].
195Straight quotes are converted to curly quotes, `---` to dashes, and
198[Smartypants]: http://daringfireball.net/projects/smartypants/
200`-m` or `--asciimathml` will cause LaTeX formulas (between $ signs) in
201HTML or S5 to display as formulas rather than as code. The trick will
202not work in all browsers, but it works in Firefox. Peter Jipsen's
203[ASCIIMathML] script is used to do the magic.
205[ASCIIMathML]: http://www1.chapman.edu/~jipsen/mathml/asciimath.html
207`-i` or `--incremental` causes all lists in S5 output to be displayed
208incrementally by default (one item at a time). The normal default
209is for lists to be displayed all at once.
211`-N` or `--number-sections` causes sections to be numbered in LaTeX
212output. By default, sections are not numbered.
214# Pandoc's markdown vs. standard markdown
216In parsing markdown, Pandoc departs from and extends [standard markdown]
217in a few respects. (To run Pandoc on the official
218markdown test suite, type `make test-markdown`.)
220[standard markdown]: http://daringfireball.net/projects/markdown/syntax
224Pandoc behaves differently from standard markdown on some "edge
225cases" involving lists. Consider this source:
235Pandoc transforms this into a "compact list" (with no `<p>` tags
236around "First", "Second", or "Third"), while markdown puts `<p>`
237tags around "Second" and "Third" (but not "First"), because of
238the blank space around "Third". Pandoc follows a simple rule:
239if the text is followed by a blank line, it is treated as a
240paragraph. Since "Second" is followed by a list, and not a blank
241line, it isn't treated as a paragraph. The fact that the list
242is followed by a blank line is irrelevant.
244## Literal quotes in titles
246Standard markdown allows unescaped literal quotes in titles, as
249 [foo]: "bar "embedded" baz"
251Pandoc requires all quotes within titles to be escaped:
253 [foo]: "bar \"embedded\" baz"
257Pandoc allows implicit reference links in either of two styles:
260 2. Here's my [link][]
264If there's no corresponding reference, the implicit reference link
265will appear as regular bracketed text. Note: even `[link][]` will
266appear as `[link]` if there's no reference for `link`. If you want
267`[link][]`, use a backslash escape: `\[link]\[]`.
271Pandoc's markdown allows footnotes, using the following syntax:
273 here is a footnote reference,^(1) and another.^(longnote)
275 ^(1) Here is the footnote. It can go anywhere in the document,
276 except in embedded contexts like block quotes or lists.
278 ^(longnote) Here's the other note. This one contains multiple
281 ^ Caret characters are used to indicate that the blocks all belong
282 to a single footnote (as with block quotes).
284 ^ If you want, you can use a caret at the beginning of every line,
285 ^ as with blockquotes, but all that you need is a caret at the
286 ^ beginning of the first line of the block and any preceding
289Footnote references may not contain spaces, tabs, or newlines.
293Pandoc treats embedded HTML in markdown a bit differently than
294Markdown 1.0. While Markdown 1.0 leaves HTML blocks exactly as they
295are, Pandoc treats text between HTML tags as markdown. Thus, for
296example, Pandoc will turn
301 <td>[a link](http://google.com)</td>
309 <td><em>one</em></td>
310 <td><a href="http://google.com">a link</a></td>
314whereas Markdown 1.0 will preserve it as is.
316There is one exception to this rule: text between `<script>` and
317`</script>` tags is not interpreted as markdown.
319This departure from standard markdown should make it easier to mix
320markdown with HTML block elements. For example, one can surround
321a block of markdown text with `<div>` tags without preventing it
322from being interpreted as markdown.
326If the file begins with a title block
329 % author(s) (separated by commas)
332it will be parsed as bibliographic information, not regular text. (It
333will be used, for example, in the title of standalone LaTeX or HTML
334output.) The block may contain just a title, a title and an author,
335or all three lines. Each must begin with a % and fit on one line.
336The title may contain standard inline formatting. If you want to
337include an author but no title, or a title and a date but no author,
338you need a blank line:
344Titles will be written only when the `--standalone` (`-s`) option is
345chosen. In HTML output, titles will appear twice: once in the
346document head -- this is the title that will appear at the top of the
347window in a browser -- and once at the beginning of the document body.
348The title in the document head can have an optional prefix attached
349(`--title-prefix` or `-T` option). The title in the body appears as
350an H1 element with class "title", so it can be suppressed or
353If a title prefix is specified with `-T` and no title block appears
354in the document, the title prefix will be used by itself as the
357## Box-style blockquotes
359Pandoc supports emacs-style boxquote block quotes, in addition to
360standard markdown (email-style) boxquotes:
363 | They look like this.
368Anything between two $ characters will be parsed as LaTeX math. The
369opening $ must have a character immediately to its right, while the
370closing $ must have a character immediately to its left. Thus,
371`$20,000 and $30,000` won't parse as math. The $ character can be
372escaped with a backslash if needed.
374If you pass the `-m` (`--asciimathml`) option to `pandoc`, it will
375include the [ASCIIMathML] script in the resulting HTML. This will
376cause LaTeX math to be displayed as formulas in better browsers.
378[ASCIIMathML]: http://www1.chapman.edu/~jipsen/asciimath.html
380Inline LaTeX commands will also be preserved and passed unchanged
381to the LaTeX writer. Thus, for example, you can use LaTeX to
382include BibTeX citations:
384 This result was proved in \cite{jones.1967}.
386You can also use LaTeX environments. For example,
388 \begin{tabular}{|l|l|}\hline
389 Age & Frequency \\ \hline
392 36--45 & 22 \\ \hline
395Note, however, that material between the begin and end tags will
396be interpreted as raw LaTeX, not as markdown.
400When run with the "standalone" option (`-s`), `pandoc` creates a
401standalone file, complete with an appropriate header. To see the
402default headers used for html and latex, use the following commands:
408If you want to use a different header, just create a file containing
409it and specify it on the command line as follows:
411 pandoc --header=MyHeaderFile
413# Producing S5 with Pandoc
415Producing an [S5] slide show with Pandoc is easy. A title page is
416constructed automatically from the document's title block (see above).
417Each section (with a level-one header) produces a single slide. (Note
418that if the section is too big, the slide will not fit on the page; S5
419is not smart enough to produce multiple pages.)
421Here's the markdown source for a simple slide show, `eating.txt`:
437To produce the slide show, simply type
439 pandoc -w s5 -s eating.txt > eating.html
441and open up `eating.html` in a browser. The HTML file embeds
442all the required javascript and CSS, so no other files are necessary.
444Note that by default, the S5 writer produces lists that display
445"all at once." If you want your lists to display incrementally
446(one item at a time), use the `-i` option. If you want a
447particular list to depart from the default (that is, to display
448incrementally without the `-i` option and all at once with the
449`-i` option), put it in a block quote:
454In 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