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