4caf033392
Appveyor has been difficult to get working, due to timeouts, and lately it has been failing for unknown reasons. We don't need the appveyor build any more, now that we have Windows CI, nightly, and release-candidate builds on GitHub actions.
219 lines
9.9 KiB
Markdown
219 lines
9.9 KiB
Markdown
<!-- Do not edit this file. It is generated automatically from
|
||
README.template and MANUAL.txt via the command:
|
||
pandoc --lua-filter tools/update-readme.lua README.template -o README.md
|
||
-->
|
||
|
||
# Pandoc
|
||
|
||
[](https://github.com/jgm/pandoc/releases)
|
||
[](http://hackage.haskell.org/package/pandoc)
|
||
[](http://brewformulas.org/Pandoc)
|
||
[](http://stackage.org/lts/package/pandoc)
|
||
[](https://circleci.com/gh/jgm/pandoc)
|
||
[](https://github.com/jgm/pandoc/actions)
|
||
[](https://www.gnu.org/licenses/gpl.html)
|
||
[](https://groups.google.com/forum/#!forum/pandoc-discuss)
|
||
|
||
## The universal markup converter
|
||
|
||
Pandoc is a [Haskell](http://haskell.org) library for converting from
|
||
one markup format to another, and a command-line tool that uses this
|
||
library. It can convert *from*
|
||
|
||
<div id="input-formats">
|
||
|
||
- `commonmark` ([CommonMark](http://commonmark.org) Markdown)
|
||
- `creole` ([Creole 1.0](http://www.wikicreole.org/wiki/Creole1.0))
|
||
- `docbook` ([DocBook](http://docbook.org))
|
||
- `docx` ([Word docx](https://en.wikipedia.org/wiki/Office_Open_XML))
|
||
- `dokuwiki` ([DokuWiki markup](https://www.dokuwiki.org/dokuwiki))
|
||
- `epub` ([EPUB](http://idpf.org/epub))
|
||
- `fb2`
|
||
([FictionBook2](http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1)
|
||
e-book)
|
||
- `gfm` ([GitHub-Flavored
|
||
Markdown](https://help.github.com/articles/github-flavored-markdown/)),
|
||
or the deprecated and less accurate `markdown_github`; use
|
||
[`markdown_github`](#markdown-variants) only if you need extensions
|
||
not supported in [`gfm`](#markdown-variants).
|
||
- `haddock` ([Haddock
|
||
markup](https://www.haskell.org/haddock/doc/html/ch03s08.html))
|
||
- `html` ([HTML](http://www.w3.org/html/))
|
||
- `ipynb` ([Jupyter
|
||
notebook](https://nbformat.readthedocs.io/en/latest/))
|
||
- `jats` ([JATS](https://jats.nlm.nih.gov) XML)
|
||
- `json` (JSON version of native AST)
|
||
- `latex` ([LaTeX](http://latex-project.org))
|
||
- `markdown` ([Pandoc’s Markdown](#pandocs-markdown))
|
||
- `markdown_mmd`
|
||
([MultiMarkdown](http://fletcherpenney.net/multimarkdown/))
|
||
- `markdown_phpextra` ([PHP Markdown
|
||
Extra](https://michelf.ca/projects/php-markdown/extra/))
|
||
- `markdown_strict` (original unextended
|
||
[Markdown](http://daringfireball.net/projects/markdown/))
|
||
- `mediawiki` ([MediaWiki
|
||
markup](https://www.mediawiki.org/wiki/Help:Formatting))
|
||
- `man` ([roff
|
||
man](http://man7.org/linux/man-pages/man7/groff_man.7.html))
|
||
- `muse` ([Muse](https://amusewiki.org/library/manual))
|
||
- `native` (native Haskell)
|
||
- `odt` ([ODT](http://en.wikipedia.org/wiki/OpenDocument))
|
||
- `opml` ([OPML](http://dev.opml.org/spec2.html))
|
||
- `org` ([Emacs Org mode](http://orgmode.org))
|
||
- `rst`
|
||
([reStructuredText](http://docutils.sourceforge.net/docs/ref/rst/introduction.html))
|
||
- `t2t` ([txt2tags](http://txt2tags.org))
|
||
- `textile` ([Textile](http://redcloth.org/textile))
|
||
- `tikiwiki` ([TikiWiki
|
||
markup](https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wiki-Syntax))
|
||
- `twiki` ([TWiki
|
||
markup](http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules))
|
||
- `vimwiki` ([Vimwiki](https://vimwiki.github.io))
|
||
|
||
</div>
|
||
|
||
It can convert *to*
|
||
|
||
<div id="output-formats">
|
||
|
||
- `asciidoc` ([AsciiDoc](http://www.methods.co.nz/asciidoc/)) or
|
||
`asciidoctor` ([AsciiDoctor](https://asciidoctor.org/))
|
||
- `beamer` ([LaTeX beamer](https://ctan.org/pkg/beamer) slide show)
|
||
- `commonmark` ([CommonMark](http://commonmark.org) Markdown)
|
||
- `context` ([ConTeXt](http://www.contextgarden.net/))
|
||
- `docbook` or `docbook4` ([DocBook](http://docbook.org) 4)
|
||
- `docbook5` (DocBook 5)
|
||
- `docx` ([Word docx](https://en.wikipedia.org/wiki/Office_Open_XML))
|
||
- `dokuwiki` ([DokuWiki markup](https://www.dokuwiki.org/dokuwiki))
|
||
- `epub` or `epub3` ([EPUB](http://idpf.org/epub) v3 book)
|
||
- `epub2` (EPUB v2)
|
||
- `fb2`
|
||
([FictionBook2](http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1)
|
||
e-book)
|
||
- `gfm` ([GitHub-Flavored
|
||
Markdown](https://help.github.com/articles/github-flavored-markdown/)),
|
||
or the deprecated and less accurate `markdown_github`; use
|
||
[`markdown_github`](#markdown-variants) only if you need extensions
|
||
not supported in [`gfm`](#markdown-variants).
|
||
- `haddock` ([Haddock
|
||
markup](https://www.haskell.org/haddock/doc/html/ch03s08.html))
|
||
- `html` or `html5` ([HTML](http://www.w3.org/html/),
|
||
i.e. [HTML5](http://www.w3.org/TR/html5/)/XHTML [polyglot
|
||
markup](https://www.w3.org/TR/html-polyglot/))
|
||
- `html4` ([XHTML](http://www.w3.org/TR/xhtml1/) 1.0 Transitional)
|
||
- `icml` ([InDesign
|
||
ICML](http://wwwimages.adobe.com/www.adobe.com/content/dam/acom/en/devnet/indesign/sdk/cs6/idml/idml-cookbook.pdf))
|
||
- `ipynb` ([Jupyter
|
||
notebook](https://nbformat.readthedocs.io/en/latest/))
|
||
- `jats` ([JATS](https://jats.nlm.nih.gov) XML)
|
||
- `jira`
|
||
([Jira](https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all)
|
||
wiki markup)
|
||
- `json` (JSON version of native AST)
|
||
- `latex` ([LaTeX](http://latex-project.org))
|
||
- `man` ([roff
|
||
man](http://man7.org/linux/man-pages/man7/groff_man.7.html))
|
||
- `markdown` ([Pandoc’s Markdown](#pandocs-markdown))
|
||
- `markdown_mmd`
|
||
([MultiMarkdown](http://fletcherpenney.net/multimarkdown/))
|
||
- `markdown_phpextra` ([PHP Markdown
|
||
Extra](https://michelf.ca/projects/php-markdown/extra/))
|
||
- `markdown_strict` (original unextended
|
||
[Markdown](http://daringfireball.net/projects/markdown/))
|
||
- `mediawiki` ([MediaWiki
|
||
markup](https://www.mediawiki.org/wiki/Help:Formatting))
|
||
- `ms` ([roff
|
||
ms](http://man7.org/linux/man-pages/man7/groff_ms.7.html))
|
||
- `muse` ([Muse](https://amusewiki.org/library/manual)),
|
||
- `native` (native Haskell),
|
||
- `odt` ([OpenOffice text
|
||
document](http://en.wikipedia.org/wiki/OpenDocument))
|
||
- `opml` ([OPML](http://dev.opml.org/spec2.html))
|
||
- `opendocument` ([OpenDocument](http://opendocument.xml.org))
|
||
- `org` ([Emacs Org mode](http://orgmode.org))
|
||
- `plain` (plain text),
|
||
- `pptx`
|
||
([PowerPoint](https://en.wikipedia.org/wiki/Microsoft_PowerPoint)
|
||
slide show)
|
||
- `rst`
|
||
([reStructuredText](http://docutils.sourceforge.net/docs/ref/rst/introduction.html))
|
||
- `rtf` ([Rich Text
|
||
Format](http://en.wikipedia.org/wiki/Rich_Text_Format))
|
||
- `texinfo` ([GNU Texinfo](http://www.gnu.org/software/texinfo/))
|
||
- `textile` ([Textile](http://redcloth.org/textile))
|
||
- `slideous` ([Slideous](http://goessner.net/articles/slideous/) HTML
|
||
and JavaScript slide show)
|
||
- `slidy` ([Slidy](http://www.w3.org/Talks/Tools/Slidy/) HTML and
|
||
JavaScript slide show)
|
||
- `dzslides` ([DZSlides](http://paulrouget.com/dzslides/) HTML5 +
|
||
JavaScript slide show),
|
||
- `revealjs` ([reveal.js](http://lab.hakim.se/reveal-js/) HTML5 +
|
||
JavaScript slide show)
|
||
- `s5` ([S5](http://meyerweb.com/eric/tools/s5/) HTML and JavaScript
|
||
slide show)
|
||
- `tei` ([TEI Simple](https://github.com/TEIC/TEI-Simple))
|
||
- `xwiki` ([XWiki
|
||
markup](https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiSyntax/))
|
||
- `zimwiki` ([ZimWiki
|
||
markup](http://zim-wiki.org/manual/Help/Wiki_Syntax.html))
|
||
- the path of a custom lua writer, see [Custom
|
||
writers](#custom-writers) below
|
||
|
||
</div>
|
||
|
||
Pandoc can also produce PDF output via LaTeX, Groff ms, or HTML.
|
||
|
||
Pandoc’s enhanced version of Markdown includes syntax for tables,
|
||
definition lists, metadata blocks, footnotes, citations, math, and much
|
||
more. See the User’s Manual below under [Pandoc’s
|
||
Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown).
|
||
|
||
Pandoc has a modular design: it consists of a set of readers, which
|
||
parse text in a given format and produce a native representation of the
|
||
document (an *abstract syntax tree* or AST), and a set of writers, which
|
||
convert this native representation into a target format. Thus, adding an
|
||
input or output format requires only adding a reader or writer. Users
|
||
can also run custom pandoc filters to modify the intermediate AST (see
|
||
the documentation for [filters](https://pandoc.org/filters.html) and
|
||
[lua filters](https://pandoc.org/lua-filters.html)).
|
||
|
||
Because pandoc’s intermediate representation of a document is less
|
||
expressive than many of the formats it converts between, one should not
|
||
expect perfect conversions between every format and every other. Pandoc
|
||
attempts to preserve the structural elements of a document, but not
|
||
formatting details such as margin size. And some document elements, such
|
||
as complex tables, may not fit into pandoc’s simple document model.
|
||
While conversions from pandoc’s Markdown to all formats aspire to be
|
||
perfect, conversions from formats more expressive than pandoc’s Markdown
|
||
can be expected to be lossy.
|
||
|
||
## Installing
|
||
|
||
Here’s [how to install pandoc](INSTALL.md).
|
||
|
||
## Documentation
|
||
|
||
Pandoc’s website contains a full [User’s
|
||
Guide](https://pandoc.org/MANUAL.html). It is also available
|
||
[here](MANUAL.txt) as pandoc-flavored Markdown. The website also
|
||
contains some [examples of the use of
|
||
pandoc](https://pandoc.org/demos.html) and a limited [online
|
||
demo](https://pandoc.org/try).
|
||
|
||
## Contributing
|
||
|
||
Pull requests, bug reports, and feature requests are welcome. Please
|
||
make sure to read [the contributor guidelines](CONTRIBUTING.md) before
|
||
opening a new issue.
|
||
|
||
## License
|
||
|
||
© 2006-2018 John MacFarlane (jgm@berkeley.edu). Released under the
|
||
[GPL](http://www.gnu.org/copyleft/gpl.html "GNU General Public License"),
|
||
version 2 or greater. This software carries no warranty of any kind.
|
||
(See COPYRIGHT for full copyright and warranty notices.)
|