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