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