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