git.iko.soy/typeable/pandoc
on 1.3 help sign in
typeable/pandoc/web/index.txt.in
265 lines 11 kB history raw
1% Pandoc
3# Overview
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], [ConTeXt],
9[PDF], [RTF], [DocBook XML], [OpenDocument XML], [ODT], [GNU Texinfo],
10[MediaWiki markup], [groff man] pages, and [S5] HTML slide shows.
12Pandoc features
14- Modular design, using separate writers and readers for each
15 supported format.
16- A real markdown parser, not based on regex substitutions.
17 [More accurate] and [much faster] than `Markdown.pl`.
18- Also parses (subsets of) reStructuredText, LaTeX, and HTML.
19- Multiple output formats: HTML, Docbook XML, LaTeX, ConTeXt,
20 reStructuredText, Markdown, RTF, groff man pages, OpenDocument
21 XML, ODT (Open Office document), MediaWiki, GNU Texinfo,
22 S5 slide shows.
23- Unicode support.
24- Optional "smart" quotes, dashes, and ellipses.
25- Automatically generated tables of contents.
26- Support for displaying math in HTML.
27- Extensions to markdown syntax:
28 + Document metadata (title, author, date).
29 + Footnotes, tables, and definition lists.
30 + Superscripts, subscripts, and strikeout.
31 + Inline LaTeX math and LaTeX commands.
32 + Markdown inside HTML blocks.
33 + Enhanced ordered lists: start number and numbering style
34 are significant.
35 + Delimited (unindented) code blocks with syntax highlighting.
36 + Compatibility mode to turn off syntax entensions and emulate
37 `Markdown.pl`.
38- Convenient wrapper scripts:
39 + `markdown2pdf` converts directly from markdown to PDF, using
40 `pdflatex`.
41 + `html2markdown` makes it easy to produce a markdown version
42 of any web page.
43 + `hsmarkdown` is a drop-in replacement for `Markdown.pl`.
44- Multi-platform: runs on Windows, MacOS X, Linux, Unix.
45- Free software, released under the [GPL].
47To see what pandoc can do, see the [demonstration page](examples.html),
48or [try pandoc on the web](/pandoc/try).
50# Documentation
52- [User's Guide](README.html)
53- Man pages
54 - [`pandoc(1)`](pandoc.1.html)
55 - [`markdown2pdf(1)`](markdown2pdf.1.html)
56 - [`html2markdown(1)`](html2markdown.1.html)
57 - [`hsmarkdown(1)`](hsmarkdown.1.html)
58- [Library documentation](doc/pandoc/index.html) (for Haskell programmers)
59- [Installation instructions](INSTALL.html)
60- [Changelog](changelog.txt)
62# Demonstrations
64- [Examples](examples.html)
65- [Try pandoc online](http://johnmacfarlane.net/pandoc/try)
67# Installing pandoc
69Pandoc is in the [MacPorts], [Debian], [Ubuntu], [Slackware], [Arch],
70[NetBSD], and [FreeBSD ports] repositories. Note that the version of
71pandoc in these repositories may not be the most recent. There
72is also a [Windows installer].
74If an up-to-date package is not available for your system, an
75excellent way to install the latest release of pandoc is to
76install the [Haskell platform] on your system, then use the `cabal`
77tool:
79 cabal install pandoc
81This will download and compile pandoc and all of its dependencies. If
82you want syntax highlighting support, add the flag `-fhighlighting`
83(this requires that the [pcre](http://www.pcre.org/) library be
84installed). If you want to install the wrapper scripts `hsmarkdown` and
85`markdown2pdf`, add `-fwrappers`.
87Alternatively, you can download the [source tarball] and
88follow the instructions in [INSTALL](INSTALL.html).
90# Extras
92- [pandoc-mode for emacs], by Joost Kremers
93- [vim syntax file for pandoc], courtesy of tao_zhyn
94- [WordPress EasyFilter], by Yang Zhang, makes it easy to use pandoc
95 with WordPress blogs.
96- [a build configuration for Pandoc that produces a standalone C-callable
97 system library](http://github.com/toyvo/libpandoc/tree/master),
98 by Anton Tayanovskyy.
100# Code repository
102Pandoc has a publicly accesible subversion repository at Google
103Code (<http://code.google.com/p/pandoc>). To check out the latest,
104bleeding-edge source code:
106 svn checkout http://pandoc.googlecode.com/svn/trunk/ pandoc
108# Reporting bugs
110You may view existing bug reports and submit new ones at
111<http://code.google.com/p/pandoc/issues/list>.
113# Mailing lists
115- [pandoc-announce]: Announcements of new releases only.
116- [pandoc-discuss]: General discussion of pandoc.
118# News
120- Version 1.3 release (??? ??, 2009).
122 + Added --id-prefix option to help prevent duplicate
123 identifiers when you're generating HTML fragments.
124 + Added --indented-code-classes option, which specifies
125 default highlighting syntax for indented code blocks.
126 + --number-sections now affects HTML output.
127 + Improved syntax for markdown definition lists.
128 + Better looking simple tables.
129 + Markdown tables without headers are now possible.
130 + New hard line break syntax: backslash followed by newline.
131 + Improved performance of markdown reader by ~10% by eliminating the
132 need for a separate parsing pass for notes.
133 + Improved syntax highlighting for literate Haskell.
134 + Support for "..code-block" directive in RST reader.
135 + Windows binary now includes highlighting support.
136 + Many bug fixes and small improvements. See [changelog]
137 for details.
139- Version 1.2.1 release (July 18, 2009).
141 + Improved the efficiency of the markdown reader's
142 abbreviation parsing (should give a big performance
143 boost with --smart).
144 + HTML writer now wraps sections in divs with unique
145 identifiers, for easier manipulation.
146 + Improved LaTeX reader's coverage of math modes.
147 + Added a portable Haskell version of markdown2pdf (thanks
148 to Paolo Tanimoto).
149 + Made --strict compatible with --standalone and --toc.
150 + Many other small improvements and bug fixes.
151 See [changelog] for details.
153- Version 1.2 release (March 1, 2009).
155 + Added support for literate Haskell. lhs support is triggered by
156 '+lhs' suffixes in formats. For example, 'latex+lhs' is literate
157 Haskell LaTeX. '.lhs' files are treated by default as literate
158 markdown.
159 + Added --email-obfuscation option.
160 + Brought citeproc support up to date for citeproc-hs-0.2.
161 + Many bugs fixed. See [changelog] for details.
163- Version 1.1 release (November 6, 2008).
165 + New --jsmath option supporting use of pandoc with [jsMath].
166 + Classes on HTML table output for better CSS styling.
167 + Windows installer no longer requires admin privileges.
168 + Many bugs fixed. See [changelog] for details.
170- Version 1.0 release (September 13, 2008).
172 + New writers for MediaWiki, GNU Texinfo (thanks to Peter Wang),
173 OpenDocument XML (thanks to Andrea Rossato), and ODT (OpenOffice
174 document).
175 + New [delimited code blocks](README.html#delimited-code-blocks),
176 with optional syntax highlighting.
177 + Reorganized build system: pandoc can now be built using standard
178 Cabal tools. It can be compiled on Windows without Cygwin.
179 The tests can also be run without perl or unix tools.
180 + LaTeXMathML replaces ASCIIMathML for rendering math in HTML.
181 + Support for "displayed" math.
182 + Common abbreviations are now handled more intelligently, with
183 a non-breaking space (and not a sentence-ending space) after
184 the period.
185 + Code is -Wall clean.
186 + Many bug fixes and small improvements. See [changelog] for
187 full details.
189- Version 0.46 released (January 8, 2008).
191 + Added a `--sanitize-html` option (and a corresponding parameter
192 in `ParserState` for those using the pandoc libraries in programs).
193 This option causes pandoc to sanitize HTML (in HTML or Markdown
194 input) using a whitelist method. Possibly harmful HTML elements
195 are replaced with HTML comments. This should be useful in the
196 context of web applications, where pandoc may be used to convert
197 user input into HTML.
198 + Made -H, -A, and -B options cumulative: if they are specified
199 multiple times, multiple files will be included.
200 + Many bug fixes and small improvements. See [changelog] for full
201 details.
203- Version 0.45 released (December 9, 2007).
205 + Many bug fixes and structural improvements. See [changelog] for
206 full details.
207 + Improved treatment of math. Math is now rendered using unicode
208 by default in HTML, RTF, and DocBook output. For more accurate
209 display of math in HTML, `--gladtex`, `--mimetex`, and `--asciimathml`
210 options are provided. See the [User's Guide](README.html#math) for
211 details.
212 + Removed support for box-style block quotes in markdown.
213 + More idiomatic ConTeXt output.
214 + Text wrapping in ConTeXt and LaTeX output.
215 + Pandoc now correctly handles all standard line endings
216 (CR, LF, CRLF).
217 + New `--no-wrap` option that disables line wrapping and minimizes
218 whitespace in HTML output.
219 + Build process is now compatible with both GHC 6.8 and GHC 6.6.
220 GHC and GHC_PKG environment variables may be used to specify
221 which version of the compiler to use, when multiple versions are
222 installed.
224# Disclaimer
226Pandoc carries no warranties of any kind.
228[More accurate]: http://code.google.com/p/pandoc/wiki/PandocVsMarkdownPl
229[much faster]: http://code.google.com/p/pandoc/wiki/Benchmarks
231[John MacFarlane]: http://johnmacfarlane.net/
232[markdown]: http://daringfireball.net/projects/markdown/
233[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
234[S5]: http://meyerweb.com/eric/tools/s5/
235[HTML]: http://www.w3.org/TR/html40/
236[LaTeX]: http://www.latex-project.org/
237[ConTeXt]: http://www.pragma-ade.nl/
238[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
239[PDF]: http://en.wikipedia.org/wiki/Portable_Document_Format
240[ODT]: http://en.wikipedia.org/wiki/OpenDocument
241[DocBook XML]: http://www.docbook.org/
242[OpenDocument XML]: http://opendocument.xml.org/
243[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting
244[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
245[GNU Texinfo]: http://www.gnu.org/software/texinfo/
246[Haskell]: http://www.haskell.org/
247[GHC]: http://www.haskell.org/ghc/
248[GPL]: http://www.gnu.org/copyleft/gpl.html
249[Source tarball]: http://code.google.com/p/pandoc/downloads/detail?name=pandoc-@VERSION@.tar.gz "Download source tarball from Pandoc's Google Code site"
250[Windows installer]: http://code.google.com/p/pandoc/downloads/detail?name=pandoc-@VERSION@-setup.exe "Download Windows installer from Pandoc's Google Code site"
251[Debian]: http://packages.debian.org/lenny/pandoc
252[Slackware]: http://www.linuxpackages.net/search_view.php?by=name&name=pandoc&ver=
253[Arch]: http://aur.archlinux.org/packages.php?ID=19804
254[NetBSD]: http://pkgsrc.se/wip/pandoc
255[FreeBSD ports]: http://www.freshports.org/textproc/pandoc/
256[Ubuntu]: http://www.ubuntu.com
257[MacPorts]: http://db.macports.org/port/show/4218
258[pandoc-announce]: http://groups.google.com/group/pandoc-announce
259[pandoc-discuss]: http://groups.google.com/group/pandoc-discuss
260[changelog]: changelog.txt
261[vim syntax file for pandoc]: http://www.vim.org/scripts/script.php?script_id=2389
262[jsMath]: http://www.math.union.edu/~dpvc/jsMath/
263[WordPress EasyFilter]: http://assorted.sourceforge.net/wp-easy-filter/
264[Haskell platform]: http://hackage.haskell.org/platform/
265[pandoc-mode for emacs]: http://joostkremers.fastmail.fm/pandoc-mode.html