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