git.iko.soy/typeable/pandoc
on rc/2.11.2 help sign in
typeable/pandoc/README.md
242 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[![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](http://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- `commonmark` ([CommonMark](https://commonmark.org) Markdown)
99- `commonmark_x` ([CommonMark](https://commonmark.org) Markdown with
100 extensions)
101- `context` ([ConTeXt](https://www.contextgarden.net/))
102- `csljson` ([CSL
103 JSON](https://citeproc-js.readthedocs.io/en/latest/csl-json/markup.html)
104 bibliography)
105- `docbook` or `docbook4` ([DocBook](https://docbook.org) 4)
106- `docbook5` (DocBook 5)
107- `docx` ([Word docx](https://en.wikipedia.org/wiki/Office_Open_XML))
108- `dokuwiki` ([DokuWiki markup](https://www.dokuwiki.org/dokuwiki))
109- `epub` or `epub3` ([EPUB](http://idpf.org/epub) v3 book)
110- `epub2` (EPUB v2)
111- `fb2`
112 ([FictionBook2](http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1)
113 e-book)
114- `gfm` ([GitHub-Flavored
115 Markdown](https://help.github.com/articles/github-flavored-markdown/)),
116 or the deprecated and less accurate `markdown_github`; use
117 [`markdown_github`](https://pandoc.org/MANUAL.html#markdown-variants)
118 only if you need extensions not supported in
119 [`gfm`](https://pandoc.org/MANUAL.html#markdown-variants).
120- `haddock` ([Haddock
121 markup](https://www.haskell.org/haddock/doc/html/ch03s08.html))
122- `html` or `html5` ([HTML](https://www.w3.org/html/),
123 i.e. [HTML5](https://html.spec.whatwg.org/)/XHTML [polyglot
124 markup](https://www.w3.org/TR/html-polyglot/))
125- `html4` ([XHTML](https://www.w3.org/TR/xhtml1/) 1.0 Transitional)
126- `icml` ([InDesign
127 ICML](https://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-cookbook.pdf))
128- `ipynb` ([Jupyter
129 notebook](https://nbformat.readthedocs.io/en/latest/))
130- `jats_archiving` ([JATS](https://jats.nlm.nih.gov) XML, Archiving
131 and Interchange Tag Set)
132- `jats_articleauthoring` ([JATS](https://jats.nlm.nih.gov) XML,
133 Article Authoring Tag Set)
134- `jats_publishing` ([JATS](https://jats.nlm.nih.gov) XML, Journal
135 Publishing Tag Set)
136- `jats` (alias for `jats_archiving`)
137- `jira`
138 ([Jira](https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all)/Confluence
139 wiki markup)
140- `json` (JSON version of native AST)
141- `latex` ([LaTeX](https://www.latex-project.org/))
142- `man` ([roff man](https://man.cx/groff_man(7)))
143- `markdown` ([Pandoc’s
144 Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown))
145- `markdown_mmd`
146 ([MultiMarkdown](https://fletcherpenney.net/multimarkdown/))
147- `markdown_phpextra` ([PHP Markdown
148 Extra](https://michelf.ca/projects/php-markdown/extra/))
149- `markdown_strict` (original unextended
150 [Markdown](https://daringfireball.net/projects/markdown/))
151- `mediawiki` ([MediaWiki
152 markup](https://www.mediawiki.org/wiki/Help:Formatting))
153- `ms` ([roff ms](https://man.cx/groff_ms(7)))
154- `muse` ([Muse](https://amusewiki.org/library/manual)),
155- `native` (native Haskell),
156- `odt` ([OpenOffice text
157 document](https://en.wikipedia.org/wiki/OpenDocument))
158- `opml` ([OPML](http://dev.opml.org/spec2.html))
159- `opendocument` ([OpenDocument](http://opendocument.xml.org))
160- `org` ([Emacs Org mode](https://orgmode.org))
161- `pdf` ([PDF](https://www.adobe.com/pdf/))
162- `plain` (plain text),
163- `pptx`
164 ([PowerPoint](https://en.wikipedia.org/wiki/Microsoft_PowerPoint)
165 slide show)
166- `rst`
167 ([reStructuredText](https://docutils.sourceforge.io/docs/ref/rst/introduction.html))
168- `rtf` ([Rich Text
169 Format](https://en.wikipedia.org/wiki/Rich_Text_Format))
170- `texinfo` ([GNU Texinfo](https://www.gnu.org/software/texinfo/))
171- `textile` ([Textile](https://www.promptworks.com/textile))
172- `slideous` ([Slideous](https://goessner.net/articles/slideous/) HTML
173 and JavaScript slide show)
174- `slidy` ([Slidy](https://www.w3.org/Talks/Tools/Slidy2/) HTML and
175 JavaScript slide show)
176- `dzslides` ([DZSlides](http://paulrouget.com/dzslides/) HTML5 +
177 JavaScript slide show),
178- `revealjs` ([reveal.js](https://revealjs.com/) HTML5 + JavaScript
179 slide show)
180- `s5` ([S5](https://meyerweb.com/eric/tools/s5/) HTML and JavaScript
181 slide show)
182- `tei` ([TEI Simple](https://github.com/TEIC/TEI-Simple))
183- `xwiki` ([XWiki
184 markup](https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/))
185- `zimwiki` ([ZimWiki
186 markup](https://zim-wiki.org/manual/Help/Wiki_Syntax.html))
187- the path of a custom Lua writer, see [Custom
188 writers](https://pandoc.org/MANUAL.html#custom-writers) below
190</div>
192Pandoc can also produce PDF output via LaTeX, Groff ms, or HTML.
194Pandoc’s enhanced version of Markdown includes syntax for tables,
195definition lists, metadata blocks, footnotes, citations, math, and much
196more. See the User’s Manual below under [Pandoc’s
197Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown).
199Pandoc has a modular design: it consists of a set of readers, which
200parse text in a given format and produce a native representation of the
201document (an *abstract syntax tree* or AST), and a set of writers, which
202convert this native representation into a target format. Thus, adding an
203input or output format requires only adding a reader or writer. Users
204can also run custom pandoc filters to modify the intermediate AST (see
205the documentation for [filters](https://pandoc.org/filters.html) and
206[Lua filters](https://pandoc.org/lua-filters.html)).
208Because pandoc’s intermediate representation of a document is less
209expressive than many of the formats it converts between, one should not
210expect perfect conversions between every format and every other. Pandoc
211attempts to preserve the structural elements of a document, but not
212formatting details such as margin size. And some document elements, such
213as complex tables, may not fit into pandoc’s simple document model.
214While conversions from pandoc’s Markdown to all formats aspire to be
215perfect, conversions from formats more expressive than pandoc’s Markdown
216can be expected to be lossy.
218## Installing
220Here’s [how to install pandoc](INSTALL.md).
222## Documentation
224Pandoc’s website contains a full [User’s
225Guide](https://pandoc.org/MANUAL.html). It is also available
226[here](MANUAL.txt) as pandoc-flavored Markdown. The website also
227contains some [examples of the use of
228pandoc](https://pandoc.org/demos.html) and a limited [online
229demo](https://pandoc.org/try).
231## Contributing
233Pull requests, bug reports, and feature requests are welcome. Please
234make sure to read [the contributor guidelines](CONTRIBUTING.md) before
235opening a new issue.
237## License
239© 2006-2020 John MacFarlane (jgm@berkeley.edu). Released under the
240[GPL](http://www.gnu.org/copyleft/gpl.html "GNU General Public License"),
241version 2 or greater. This software carries no warranty of any kind.
242(See COPYRIGHT for full copyright and warranty notices.)