% Pandoc

# Overview

Pandoc is a [Haskell] library for converting from one markup format
to another, and a command-line tool that uses this library. It can read
[markdown] and (subsets of) [reStructuredText], [HTML], and [LaTeX],
and it can write [markdown], [reStructuredText], [HTML], [LaTeX], [ConTeXt],
[PDF], [RTF], [DocBook XML], [OpenDocument XML], [ODT], [GNU Texinfo],
[MediaWiki markup], [groff man] pages, and [S5] HTML slide shows.

Pandoc features

- Modular design, using separate writers and readers for each
  supported format.
- A real markdown parser, not based on regex substitutions.
  [More accurate] and [much faster] than `Markdown.pl`.
- Also parses (subsets of) reStructuredText, LaTeX, and HTML.
- Multiple output formats: HTML, Docbook XML, LaTeX, ConTeXt,
  reStructuredText, Markdown, RTF, groff man pages, OpenDocument
  XML, ODT (Open Office document), MediaWiki, GNU Texinfo,
  S5 slide shows.
- Unicode support.
- Optional "smart" quotes, dashes, and ellipses.
- Automatically generated tables of contents.
- Support for displaying math in HTML.
- Extensions to markdown syntax:
    + Document metadata (title, author, date).
    + Footnotes, tables, and definition lists.
    + Superscripts, subscripts, and strikeout.
    + Inline LaTeX math and LaTeX commands.
    + Markdown inside HTML blocks.
    + Enhanced ordered lists:  start number and numbering style
      are significant.
    + Delimited (unindented) code blocks with syntax highlighting.
    + Compatibility mode to turn off syntax entensions and emulate
      `Markdown.pl`.
- Convenient `markdown2pdf` wrapper script that converts directly
  from markdown to PDF, using `pdflatex`.
- Multi-platform:  runs on Windows, MacOS X, Linux, Unix.
- Free software, released under the [GPL].

To see what pandoc can do, see the [demonstration page](examples.html),
or [try pandoc on the web](/pandoc/try).

# Documentation

- [User's Guide](README.html)
- Man pages
    - [`pandoc(1)`](pandoc.1.html)
    - [`markdown2pdf(1)`](markdown2pdf.1.html)
- [Library documentation](doc/pandoc/index.html) (for Haskell programmers)
- [Installation instructions](INSTALL.html)
- [Changelog](changelog.txt)

# Demonstrations

- [Examples](examples.html)
- [Try pandoc online](http://johnmacfarlane.net/pandoc/try)

# Installing pandoc

Pandoc is in the [MacPorts], [Debian], [Ubuntu], [Slackware], [Arch],
[NetBSD], and [FreeBSD ports] repositories. Note that the version of
pandoc in these repositories may not be the most recent.  There
is also a [Windows installer].

If an up-to-date package is not available for your system, an
excellent way to install the latest release of pandoc is to
install the [Haskell platform] on your system, then use the `cabal`
tool:

    cabal install pandoc

This will download and compile pandoc and all of its dependencies. If
you want syntax highlighting support, add the flag `-fhighlighting`
(this requires that the [pcre](http://www.pcre.org/) library be
installed). If you do not want to install the wrapper script
`markdown2pdf`, add `-f-wrappers`. If you do not want to install
the Haskell library, add `-f-library`.

Alternatively, you can download the [source tarball] and
follow the instructions in [INSTALL](INSTALL.html).

# Extras

- [pandoc-mode for emacs], by Joost Kremers
- [vim syntax file for pandoc], courtesy of tao_zhyn
- [TextMate bundle for pandoc], courtesy of dsanson
- [WordPress EasyFilter], by Yang Zhang, makes it easy to use pandoc
  with WordPress blogs.
- [a build configuration for Pandoc that produces a standalone C-callable
  system library](http://github.com/toyvo/libpandoc/tree/master),
  by Anton Tayanovskyy.

# Code repository

Pandoc has a publicly accesible subversion repository at Google
Code (<http://code.google.com/p/pandoc>). To check out the latest,
bleeding-edge source code:

    svn checkout http://pandoc.googlecode.com/svn/trunk/ pandoc

# Reporting bugs

You may view existing bug reports and submit new ones at 
<http://code.google.com/p/pandoc/issues/list>.

# Mailing lists

- [pandoc-announce]:  Announcements of new releases only.
- [pandoc-discuss]:  General discussion of pandoc.

# News

-   Version 1.4 release (January 2, 2010).

    + New template system replaces old headers, giving users much
      more control over pandoc's output in `--standalone` mode.
      Added `--template` and `--variable` options.  The `--print-default-header`
      option is now `--print-default-template`.  See README under
      "Templates" for details.
    + The old `--custom-header` option should still work, but it has
      been deprecated.
    + New `--reference-odt` option allows users to customize styles
      in ODT output.
    + Users may now put custom templates, s5 styles, and a reference
      ODT in the `~/.pandoc` directory, where they will override system
      defaults. See README for details.
    + Unicode is now used whenever possible in HTML and XML output. Entities
      are used only where necessary (`&gt;`, `&lt;`, `&quot;`, `&amp;`).
    + Authors and dates may now include formatting and notes.
    + Added `--xetex` option for `pandoc` and `markdown2pdf`.
    + Windows installer now includes highlighting support and
      `markdown2pdf` and `hsmarkdown` wrappers.
    + Pandoc no longer requires Template Haskell, which should make
      it more portable.
    + Pandoc can now be built on GHC 6.12, as well as earlier versions.
    + See README for other small improvements and bug fixes.

-   Version 1.3 release (December 10, 2009).

    + Added --id-prefix option to help prevent duplicate
      identifiers when you're generating HTML fragments.
    + Added --indented-code-classes option, which specifies
      default highlighting syntax for indented code blocks.
    + --number-sections now affects HTML output.
    + Improved syntax for markdown definition lists.
    + Better looking simple tables.
    + Markdown tables without headers are now possible.
    + New hard line break syntax:  backslash followed by newline.
    + Improved performance of markdown reader by ~10% by eliminating the
      need for a separate parsing pass for notes.
    + Improved syntax highlighting for literate Haskell.
    + Support for "..code-block" directive in RST reader.
    + Windows binary now includes highlighting support.
    + Many bug fixes and small improvements. See [changelog]
      for details.

-   Version 1.2.1 release (July 18, 2009).

    + Improved the efficiency of the markdown reader's
      abbreviation parsing (should give a big performance
      boost with --smart).
    + HTML writer now wraps sections in divs with unique
      identifiers, for easier manipulation.
    + Improved LaTeX reader's coverage of math modes.
    + Added a portable Haskell version of markdown2pdf (thanks
      to Paolo Tanimoto).
    + Made --strict compatible with --standalone and --toc.
    + Many other small improvements and bug fixes.
      See [changelog] for details.

-   Version 1.2 release (March 1, 2009).

    + Added support for literate Haskell. lhs support is triggered by
      '+lhs' suffixes in formats. For example, 'latex+lhs' is literate
      Haskell LaTeX. '.lhs' files are treated by default as literate
      markdown.
    + Added --email-obfuscation option.
    + Brought citeproc support up to date for citeproc-hs-0.2.
    + Many bugs fixed. See [changelog] for details.

-   Version 1.1 release (November 6, 2008).

    + New --jsmath option supporting use of pandoc with [jsMath].
    + Classes on HTML table output for better CSS styling.
    + Windows installer no longer requires admin privileges.
    + Many bugs fixed.  See [changelog] for details.

-   Version 1.0 release (September 13, 2008).

    + New writers for MediaWiki, GNU Texinfo (thanks to Peter Wang),
      OpenDocument XML (thanks to Andrea Rossato), and ODT (OpenOffice
      document).
    + New [delimited code blocks](README.html#delimited-code-blocks),
      with optional syntax highlighting.
    + Reorganized build system:  pandoc can now be built using standard
      Cabal tools.  It can be compiled on Windows without Cygwin.
      The tests can also be run without perl or unix tools.
    + LaTeXMathML replaces ASCIIMathML for rendering math in HTML.
    + Support for "displayed" math.
    + Common abbreviations are now handled more intelligently, with
      a non-breaking space (and not a sentence-ending space) after
      the period.
    + Code is -Wall clean.
    + Many bug fixes and small improvements.  See [changelog] for
      full details.

-   Version 0.46 released (January 8, 2008).

    + Added a `--sanitize-html` option (and a corresponding parameter
      in `ParserState` for those using the pandoc libraries in programs).
      This option causes pandoc to sanitize HTML (in HTML or Markdown
      input) using a whitelist method. Possibly harmful HTML elements
      are replaced with HTML comments. This should be useful in the
      context of web applications, where pandoc may be used to convert
      user input into HTML.
    + Made -H, -A, and -B options cumulative: if they are specified
      multiple times, multiple files will be included.
    + Many bug fixes and small improvements.  See [changelog] for full
      details.

-   Version 0.45 released (December 9, 2007).

    + Many bug fixes and structural improvements.  See [changelog] for
      full details.
    + Improved treatment of math. Math is now rendered using unicode
      by default in HTML, RTF, and DocBook output. For more accurate
      display of math in HTML, `--gladtex`, `--mimetex`, and `--asciimathml`
      options are provided. See the [User's Guide](README.html#math) for
      details.
    + Removed support for box-style block quotes in markdown.
    + More idiomatic ConTeXt output.
    + Text wrapping in ConTeXt and LaTeX output.
    + Pandoc now correctly handles all standard line endings
      (CR, LF, CRLF).
    + New `--no-wrap` option that disables line wrapping and minimizes
      whitespace in HTML output.
    + Build process is now compatible with both GHC 6.8 and GHC 6.6.
      GHC and GHC_PKG environment variables may be used to specify
      which version of the compiler to use, when multiple versions are
      installed.

# Disclaimer

Pandoc carries no warranties of any kind.

[More accurate]: http://code.google.com/p/pandoc/wiki/PandocVsMarkdownPl
[much faster]: http://code.google.com/p/pandoc/wiki/Benchmarks
 
[John MacFarlane]: http://johnmacfarlane.net/
[markdown]: http://daringfireball.net/projects/markdown/
[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
[S5]: http://meyerweb.com/eric/tools/s5/
[HTML]:  http://www.w3.org/TR/html40/
[LaTeX]:  http://www.latex-project.org/
[ConTeXt]: http://www.pragma-ade.nl/ 
[RTF]:  http://en.wikipedia.org/wiki/Rich_Text_Format
[PDF]: http://en.wikipedia.org/wiki/Portable_Document_Format
[ODT]: http://en.wikipedia.org/wiki/OpenDocument
[DocBook XML]: http://www.docbook.org/
[OpenDocument XML]: http://opendocument.xml.org/
[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting
[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
[GNU Texinfo]: http://www.gnu.org/software/texinfo/
[Haskell]:  http://www.haskell.org/
[GHC]:  http://www.haskell.org/ghc/
[GPL]:  http://www.gnu.org/copyleft/gpl.html
[Source tarball]: http://code.google.com/p/pandoc/downloads/detail?name=pandoc-@VERSION@.tar.gz "Download source tarball from Pandoc's Google Code site"
[Windows installer]: http://code.google.com/p/pandoc/downloads/detail?name=pandoc-@VERSION@-setup.exe "Download Windows installer from Pandoc's Google Code site"
[Debian]: http://packages.debian.org/lenny/pandoc
[Slackware]: http://www.linuxpackages.net/search_view.php?by=name&name=pandoc&ver=
[Arch]: http://aur.archlinux.org/packages.php?ID=19804
[NetBSD]: http://pkgsrc.se/wip/pandoc
[FreeBSD ports]: http://www.freshports.org/textproc/pandoc/
[Ubuntu]: http://www.ubuntu.com
[MacPorts]: http://db.macports.org/port/show/4218
[pandoc-announce]: http://groups.google.com/group/pandoc-announce
[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
[changelog]: changelog.txt
[vim syntax file for pandoc]: http://www.vim.org/scripts/script.php?script_id=2389
[TextMate bundle for pandoc]: http://github.com/dsanson/Pandoc.tmbundle
[jsMath]: http://www.math.union.edu/~dpvc/jsMath/
[WordPress EasyFilter]: http://assorted.sourceforge.net/wp-easy-filter/
[Haskell platform]: http://hackage.haskell.org/platform/
[pandoc-mode for emacs]:  http://joostkremers.fastmail.fm/pandoc-mode.html