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