git.iko.soy/typeable/pandoc
on 34412cf help sign in
typeable/pandoc/README.md
147 lines 7.5 kB history raw
1Pandoc
2======
4[![github release](https://img.shields.io/github/release/jgm/pandoc.svg?label=current+release)](https://github.com/jgm/pandoc/releases)
5[![hackage release](https://img.shields.io/hackage/v/pandoc.svg?label=hackage)](http://hackage.haskell.org/package/pandoc)
6[![homebrew](https://img.shields.io/homebrew/v/pandoc.svg)](http://brewformulas.org/Pandoc)
7[![stackage LTS package](http://stackage.org/package/pandoc/badge/lts)](http://stackage.org/lts/package/pandoc)
8[![travis build status](https://img.shields.io/travis/jgm/pandoc/master.svg?label=travis+build)](https://travis-ci.org/jgm/pandoc)
9[![appveyor build status](https://ci.appveyor.com/api/projects/status/nvqs4ct090igjiqc?svg=true)](https://ci.appveyor.com/project/jgm/pandoc)
10[![license](https://img.shields.io/badge/license-GPLv2+-lightgray.svg)](https://www.gnu.org/licenses/gpl.html)
11[![pandoc-discuss on google groups](https://img.shields.io/badge/pandoc-discuss-red.svg?style=social)](https://groups.google.com/forum/#!forum/pandoc-discuss)
14The universal markup converter
15------------------------------
17Pandoc is a [Haskell] library for converting from one markup format to
18another, and a command-line tool that uses this library. It can read
19[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown],
20[MultiMarkdown], and (subsets of) [Textile], [reStructuredText], [HTML],
21[LaTeX], [MediaWiki markup], [TWiki markup], [Haddock markup], [OPML], [Emacs
22Org mode], [DocBook], [txt2tags], [EPUB], [ODT] and [Word docx]; and it can
23write plain text, [Markdown], [CommonMark], [PHP Markdown Extra],
24[GitHub-Flavored Markdown], [MultiMarkdown], [reStructuredText], [XHTML],
25[HTML5], [LaTeX] \(including [`beamer`] slide shows\), [ConTeXt], [RTF], [OPML],
26[DocBook], [OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki
27markup], [DokuWiki markup], [ZimWiki markup], [Haddock markup],
28[EPUB] \(v2 or v3\), [FictionBook2], [Textile], [groff man] pages,
29[Emacs Org mode], [AsciiDoc], [InDesign ICML], [TEI Simple], [Muse], and [Slidy],
30[Slideous], [DZSlides], [reveal.js] or [S5] HTML slide shows. It can also
31produce [PDF] output on systems where LaTeX, ConTeXt, or `wkhtmltopdf` is
32installed.
34Pandoc's enhanced version of Markdown includes syntax for [footnotes],
35[tables], flexible [ordered lists], [definition lists], [fenced code blocks],
36[superscripts and subscripts], [strikeout], [metadata blocks], automatic tables of
37contents, embedded LaTeX [math], [citations], and [Markdown inside HTML block
38elements]. (These enhancements, described
39further under [Pandoc's Markdown], can be disabled using the
40`markdown_strict` input or output format.)
42In contrast to most existing tools for converting Markdown to HTML, which
43use regex substitutions, pandoc has a modular design: it consists of a
44set of readers, which parse text in a given format and produce a native
45representation of the document, and a set of writers, which convert
46this native representation into a target format. Thus, adding an input
47or output format requires only adding a reader or writer.
49Because pandoc's intermediate representation of a document is less
50expressive than many of the formats it converts between, one should
51not expect perfect conversions between every format and every other.
52Pandoc attempts to preserve the structural elements of a document, but
53not formatting details such as margin size. And some document elements,
54such as complex tables, may not fit into pandoc's simple document
55model. While conversions from pandoc's Markdown to all formats aspire
56to be perfect, conversions from formats more expressive than pandoc's
57Markdown can be expected to be lossy.
59[Markdown]: http://daringfireball.net/projects/markdown/
60[CommonMark]: http://commonmark.org
61[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/
62[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/
63[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/
64[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
65[S5]: http://meyerweb.com/eric/tools/s5/
66[Slidy]: http://www.w3.org/Talks/Tools/Slidy/
67[Slideous]: http://goessner.net/articles/slideous/
68[HTML]: http://www.w3.org/html/
69[HTML5]: http://www.w3.org/TR/html5/
70[XHTML]: http://www.w3.org/TR/xhtml1/
71[LaTeX]: http://latex-project.org
72[`beamer`]: https://ctan.org/pkg/beamer
73[Beamer User's Guide]: http://ctan.math.utah.edu/ctan/tex-archive/macros/latex/contrib/beamer/doc/beameruserguide.pdf
74[ConTeXt]: http://www.contextgarden.net/
75[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
76[DocBook]: http://docbook.org
77[txt2tags]: http://txt2tags.org
78[EPUB]: http://idpf.org/epub
79[OPML]: http://dev.opml.org/spec2.html
80[OpenDocument]: http://opendocument.xml.org
81[ODT]: http://en.wikipedia.org/wiki/OpenDocument
82[Textile]: http://redcloth.org/textile
83[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting
84[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
85[ZimWiki markup]: http://zim-wiki.org/manual/Help/Wiki_Syntax.html
86[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
87[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
88[groff man]: http://man7.org/linux/man-pages/man7/groff_man.7.html
89[Haskell]: https://www.haskell.org
90[GNU Texinfo]: http://www.gnu.org/software/texinfo/
91[Emacs Org mode]: http://orgmode.org
92[AsciiDoc]: http://www.methods.co.nz/asciidoc/
93[DZSlides]: http://paulrouget.com/dzslides/
94[Word docx]: https://en.wikipedia.org/wiki/Office_Open_XML
95[PDF]: https://www.adobe.com/pdf/
96[reveal.js]: http://lab.hakim.se/reveal-js/
97[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
98[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf
99[TEI Simple]: https://github.com/TEIC/TEI-Simple
100[Muse]: https://amusewiki.org/library/manual
105[footnotes]: http://pandoc.org/MANUAL.html#footnotes
106[tables]: http://pandoc.org/MANUAL.html#tables
107[ordered lists]: http://pandoc.org/MANUAL.html#ordered-lists
108[definition lists]: http://pandoc.org/MANUAL.html#definition-lists
109[fenced code blocks]: http://pandoc.org/MANUAL.html#fenced-code-blocks
110[superscripts and subscripts]: http://pandoc.org/MANUAL.html#superscripts-and-subscripts
111[strikeout]: http://pandoc.org/MANUAL.html#strikeout
112[metadata blocks]: http://pandoc.org/MANUAL.html#metadata-blocks
113[math]: http://pandoc.org/MANUAL.html#math
114[citations]: http://pandoc.org/MANUAL.html#citations
115[Markdown inside HTML block elements]: http://pandoc.org/MANUAL.html#extension-markdown_in_html_blocks
116[Pandoc's Markdown]: http://pandoc.org/MANUAL.html#pandocs-markdown
118Installing
119----------
121Here's [how to install pandoc](INSTALL.md).
123Documentation
124-------------
126Pandoc's website contains a full [User's Guide](https://pandoc.org/MANUAL.html).
127It is also available [here](MANUAL.txt) as pandoc-flavored Markdown.
128The website also contains some [examples of the use of
129pandoc](https://pandoc.org/demos.html) and a limited [online
130demo](https://pandoc.org/try).
132Contributing
133------------
135Pull requests, bug reports, and feature requests are welcome. Please make
136sure to read [the contributor guidelines](CONTRIBUTING.md) before opening a
137new issue.
140License
141-------
143© 2006-2016 John MacFarlane (jgm@berkeley.edu). Released under the
144[GPL], version 2 or greater. This software carries no warranty of
145any kind. (See COPYRIGHT for full copyright and warranty notices.)
147[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"