git.iko.soy/typeable/pandoc
on 2fee077 help sign in
typeable/pandoc/README.md
146 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], 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
104[footnotes]: http://pandoc.org/MANUAL.html#footnotes
105[tables]: http://pandoc.org/MANUAL.html#tables
106[ordered lists]: http://pandoc.org/MANUAL.html#ordered-lists
107[definition lists]: http://pandoc.org/MANUAL.html#definition-lists
108[fenced code blocks]: http://pandoc.org/MANUAL.html#fenced-code-blocks
109[superscripts and subscripts]: http://pandoc.org/MANUAL.html#superscripts-and-subscripts
110[strikeout]: http://pandoc.org/MANUAL.html#strikeout
111[metadata blocks]: http://pandoc.org/MANUAL.html#metadata-blocks
112[math]: http://pandoc.org/MANUAL.html#math
113[citations]: http://pandoc.org/MANUAL.html#citations
114[Markdown inside HTML block elements]: http://pandoc.org/MANUAL.html#extension-markdown_in_html_blocks
115[Pandoc's Markdown]: http://pandoc.org/MANUAL.html#pandocs-markdown
117Installing
118----------
120Here's [how to install pandoc](INSTALL.md).
122Documentation
123-------------
125Pandoc's website contains a full [User's Guide](https://pandoc.org/MANUAL.html).
126It is also available [here](MANUAL.txt) as pandoc-flavored Markdown.
127The website also contains some [examples of the use of
128pandoc](https://pandoc.org/demos.html) and a limited [online
129demo](https://pandoc.org/try).
131Contributing
132------------
134Pull requests, bug reports, and feature requests are welcome. Please make
135sure to read [the contributor guidelines](CONTRIBUTING.md) before opening a
136new issue.
139License
140-------
142© 2006-2016 John MacFarlane (jgm@berkeley.edu). Released under the
143[GPL], version 2 or greater. This software carries no warranty of
144any kind. (See COPYRIGHT for full copyright and warranty notices.)
146[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"