git.iko.soy/typeable/pandoc
on 2.5 help sign in
typeable/pandoc/README.md
209 lines 9.7 kB history raw
1<!-- Do not edit this file. It is generated automatically from
2README.template and MANUAL.txt via the command:
3pandoc --lua-filter tools/update-readme.lua README.template -o README.md
4-->
6# Pandoc
8[![github
9release](https://img.shields.io/github/release/jgm/pandoc.svg?label=current+release)](https://github.com/jgm/pandoc/releases)
10[![hackage
11release](https://img.shields.io/hackage/v/pandoc.svg?label=hackage)](http://hackage.haskell.org/package/pandoc)
12[![homebrew](https://img.shields.io/homebrew/v/pandoc.svg)](http://brewformulas.org/Pandoc)
13[![stackage LTS
14package](http://stackage.org/package/pandoc/badge/lts)](http://stackage.org/lts/package/pandoc)
15[![travis build
16status](https://img.shields.io/travis/jgm/pandoc/master.svg?label=travis+build)](https://travis-ci.org/jgm/pandoc)
17[![appveyor build
18status](https://ci.appveyor.com/api/projects/status/nvqs4ct090igjiqc?svg=true)](https://ci.appveyor.com/project/jgm/pandoc)
19[![license](https://img.shields.io/badge/license-GPLv2+-lightgray.svg)](https://www.gnu.org/licenses/gpl.html)
20[![pandoc-discuss on google
21groups](https://img.shields.io/badge/pandoc-discuss-red.svg?style=social)](https://groups.google.com/forum/#!forum/pandoc-discuss)
23## The universal markup converter
25Pandoc is a [Haskell](http://haskell.org) library for converting from
26one markup format to another, and a command-line tool that uses this
27library. It can convert *from*
29<div id="input-formats">
31 - `commonmark` ([CommonMark](http://commonmark.org) Markdown)
32 - `creole` ([Creole 1.0](http://www.wikicreole.org/wiki/Creole1.0))
33 - `docbook` ([DocBook](http://docbook.org))
34 - `docx` ([Word docx](https://en.wikipedia.org/wiki/Office_Open_XML))
35 - `epub` ([EPUB](http://idpf.org/epub))
36 - `fb2`
37 ([FictionBook2](http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1)
38 e-book)
39 - `gfm` ([GitHub-Flavored
40 Markdown](https://help.github.com/articles/github-flavored-markdown/)),
41 or the deprecated and less accurate `markdown_github`; use
42 [`markdown_github`](#markdown-variants) only if you need extensions
43 not supported in [`gfm`](#markdown-variants).
44 - `haddock` ([Haddock
45 markup](https://www.haskell.org/haddock/doc/html/ch03s08.html))
46 - `html` ([HTML](http://www.w3.org/html/))
47 - `jats` ([JATS](https://jats.nlm.nih.gov) XML)
48 - `json` (JSON version of native AST)
49 - `latex` ([LaTeX](http://latex-project.org))
50 - `markdown` ([Pandoc’s Markdown](#pandocs-markdown))
51 - `markdown_mmd`
52 ([MultiMarkdown](http://fletcherpenney.net/multimarkdown/))
53 - `markdown_phpextra` ([PHP Markdown
54 Extra](https://michelf.ca/projects/php-markdown/extra/))
55 - `markdown_strict` (original unextended
56 [Markdown](http://daringfireball.net/projects/markdown/))
57 - `mediawiki` ([MediaWiki
58 markup](https://www.mediawiki.org/wiki/Help:Formatting))
59 - `man` ([roff
60 man](http://man7.org/linux/man-pages/man7/groff_man.7.html))
61 - `muse` ([Muse](https://amusewiki.org/library/manual))
62 - `native` (native Haskell)
63 - `odt` ([ODT](http://en.wikipedia.org/wiki/OpenDocument))
64 - `opml` ([OPML](http://dev.opml.org/spec2.html))
65 - `org` ([Emacs Org mode](http://orgmode.org))
66 - `rst`
67 ([reStructuredText](http://docutils.sourceforge.net/docs/ref/rst/introduction.html))
68 - `t2t` ([txt2tags](http://txt2tags.org))
69 - `textile` ([Textile](http://redcloth.org/textile))
70 - `tikiwiki` ([TikiWiki
71 markup](https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wiki-Syntax))
72 - `twiki` ([TWiki
73 markup](http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules))
74 - `vimwiki` ([Vimwiki](https://vimwiki.github.io))
76</div>
78It can convert *to*
80<div id="output-formats">
82 - `asciidoc` ([AsciiDoc](http://www.methods.co.nz/asciidoc/))
83 - `beamer` ([LaTeX beamer](https://ctan.org/pkg/beamer) slide show)
84 - `commonmark` ([CommonMark](http://commonmark.org) Markdown)
85 - `context` ([ConTeXt](http://www.contextgarden.net/))
86 - `docbook` or `docbook4` ([DocBook](http://docbook.org) 4)
87 - `docbook5` (DocBook 5)
88 - `docx` ([Word docx](https://en.wikipedia.org/wiki/Office_Open_XML))
89 - `dokuwiki` ([DokuWiki markup](https://www.dokuwiki.org/dokuwiki))
90 - `epub` or `epub3` ([EPUB](http://idpf.org/epub) v3 book)
91 - `epub2` (EPUB v2)
92 - `fb2`
93 ([FictionBook2](http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1)
94 e-book)
95 - `gfm` ([GitHub-Flavored
96 Markdown](https://help.github.com/articles/github-flavored-markdown/)),
97 or the deprecated and less accurate `markdown_github`; use
98 [`markdown_github`](#markdown-variants) only if you need extensions
99 not supported in [`gfm`](#markdown-variants).
100 - `haddock` ([Haddock
101 markup](https://www.haskell.org/haddock/doc/html/ch03s08.html))
102 - `html` or `html5` ([HTML](http://www.w3.org/html/),
103 i.e. [HTML5](http://www.w3.org/TR/html5/)/XHTML [polyglot
104 markup](https://www.w3.org/TR/html-polyglot/))
105 - `html4` ([XHTML](http://www.w3.org/TR/xhtml1/) 1.0 Transitional)
106 - `icml` ([InDesign
107 ICML](http://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-cookbook.pdf))
108 - `jats` ([JATS](https://jats.nlm.nih.gov) XML)
109 - `json` (JSON version of native AST)
110 - `latex` ([LaTeX](http://latex-project.org))
111 - `man` ([roff
112 man](http://man7.org/linux/man-pages/man7/groff_man.7.html))
113 - `markdown` ([Pandoc’s Markdown](#pandocs-markdown))
114 - `markdown_mmd`
115 ([MultiMarkdown](http://fletcherpenney.net/multimarkdown/))
116 - `markdown_phpextra` ([PHP Markdown
117 Extra](https://michelf.ca/projects/php-markdown/extra/))
118 - `markdown_strict` (original unextended
119 [Markdown](http://daringfireball.net/projects/markdown/))
120 - `mediawiki` ([MediaWiki
121 markup](https://www.mediawiki.org/wiki/Help:Formatting))
122 - `ms` ([roff
123 ms](http://man7.org/linux/man-pages/man7/groff_ms.7.html))
124 - `muse` ([Muse](https://amusewiki.org/library/manual)),
125 - `native` (native Haskell),
126 - `odt` ([OpenOffice text
127 document](http://en.wikipedia.org/wiki/OpenDocument))
128 - `opml` ([OPML](http://dev.opml.org/spec2.html))
129 - `opendocument` ([OpenDocument](http://opendocument.xml.org))
130 - `org` ([Emacs Org mode](http://orgmode.org))
131 - `plain` (plain text),
132 - `pptx`
133 ([PowerPoint](https://en.wikipedia.org/wiki/Microsoft_PowerPoint)
134 slide show)
135 - `rst`
136 ([reStructuredText](http://docutils.sourceforge.net/docs/ref/rst/introduction.html))
137 - `rtf` ([Rich Text
138 Format](http://en.wikipedia.org/wiki/Rich_Text_Format))
139 - `texinfo` ([GNU Texinfo](http://www.gnu.org/software/texinfo/))
140 - `textile` ([Textile](http://redcloth.org/textile))
141 - `slideous` ([Slideous](http://goessner.net/articles/slideous/) HTML
142 and JavaScript slide show)
143 - `slidy` ([Slidy](http://www.w3.org/Talks/Tools/Slidy/) HTML and
144 JavaScript slide show)
145 - `dzslides` ([DZSlides](http://paulrouget.com/dzslides/) HTML5 +
146 JavaScript slide show),
147 - `revealjs` ([reveal.js](http://lab.hakim.se/reveal-js/) HTML5 +
148 JavaScript slide show)
149 - `s5` ([S5](http://meyerweb.com/eric/tools/s5/) HTML and JavaScript
150 slide show)
151 - `tei` ([TEI Simple](https://github.com/TEIC/TEI-Simple))
152 - `zimwiki` ([ZimWiki
153 markup](http://zim-wiki.org/manual/Help/Wiki_Syntax.html))
154 - the path of a custom lua writer, see [Custom
155 writers](#custom-writers) below
157</div>
159Pandoc can also produce PDF output via LaTeX, Groff ms, or HTML.
161Pandoc’s enhanced version of Markdown includes syntax for tables,
162definition lists, metadata blocks, footnotes, citations, math, and much
163more. See the User’s Manual below under [Pandoc’s
164Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown).
166Pandoc has a modular design: it consists of a set of readers, which
167parse text in a given format and produce a native representation of the
168document (an *abstract syntax tree* or AST), and a set of writers, which
169convert this native representation into a target format. Thus, adding an
170input or output format requires only adding a reader or writer. Users
171can also run custom pandoc filters to modify the intermediate AST (see
172the documentation for [filters](https://pandoc.org/filters.html) and
173[lua filters](https://pandoc.org/lua-filters.html)).
175Because pandoc’s intermediate representation of a document is less
176expressive than many of the formats it converts between, one should not
177expect perfect conversions between every format and every other. Pandoc
178attempts to preserve the structural elements of a document, but not
179formatting details such as margin size. And some document elements, such
180as complex tables, may not fit into pandoc’s simple document model.
181While conversions from pandoc’s Markdown to all formats aspire to be
182perfect, conversions from formats more expressive than pandoc’s Markdown
183can be expected to be lossy.
185## Installing
187Here’s [how to install pandoc](INSTALL.md).
189## Documentation
191Pandoc’s website contains a full [User’s
192Guide](https://pandoc.org/MANUAL.html). It is also available
193[here](MANUAL.txt) as pandoc-flavored Markdown. The website also
194contains some [examples of the use of
195pandoc](https://pandoc.org/demos.html) and a limited [online
196demo](https://pandoc.org/try).
198## Contributing
200Pull requests, bug reports, and feature requests are welcome. Please
201make sure to read [the contributor guidelines](CONTRIBUTING.md) before
202opening a new issue.
204## License
206© 2006-2018 John MacFarlane (jgm@berkeley.edu). Released under the
207[GPL](http://www.gnu.org/copyleft/gpl.html "GNU General Public License"),
208version 2 or greater. This software carries no warranty of any kind.
209(See COPYRIGHT for full copyright and warranty notices.)