@@ -1,155 +1,168 @@
1+<!-- Do not edit this file. It is generated automatically from
2+README.template and MANUAL.txt via the command:
3+pandoc --lua-filter tools/update-readme.lua README.template -o README.md
4+-->
15Pandoc
26======
37
4−[](https://github.com/jgm/pandoc/releases)
5−[](http://hackage.haskell.org/package/pandoc)
6−[](http://brewformulas.org/Pandoc)
7−[](http://stackage.org/lts/package/pandoc)
8−[](https://travis-ci.org/jgm/pandoc)
9−[](https://ci.appveyor.com/project/jgm/pandoc)
10−[](https://www.gnu.org/licenses/gpl.html)
11−[](https://groups.google.com/forum/#!forum/pandoc-discuss)
12−
8+[![github release][]][] [![hackage release][]][] [![homebrew][]][]
9+[![stackage LTS package][]][] [![travis build status][]][] [![appveyor
10+build status][]][] [![license][]][] [![pandoc-discuss on google groups]]
11+
12+ [github release]: https://img.shields.io/github/release/jgm/pandoc.svg?label=current+release
13+ [![github release][]]: https://github.com/jgm/pandoc/releases
14+ [hackage release]: https://img.shields.io/hackage/v/pandoc.svg?label=hackage
15+ [![hackage release][]]: http://hackage.haskell.org/package/pandoc
16+ [homebrew]: https://img.shields.io/homebrew/v/pandoc.svg
17+ [![homebrew][]]: http://brewformulas.org/Pandoc
18+ [stackage LTS package]: http://stackage.org/package/pandoc/badge/lts
19+ [![stackage LTS package][]]: http://stackage.org/lts/package/pandoc
20+ [travis build status]: https://img.shields.io/travis/jgm/pandoc/master.svg?label=travis+build
21+ [![travis build status][]]: https://travis-ci.org/jgm/pandoc
22+ [appveyor build status]: https://ci.appveyor.com/api/projects/status/nvqs4ct090igjiqc?svg=true
23+ [![appveyor build status][]]: https://ci.appveyor.com/project/jgm/pandoc
24+ [license]: https://img.shields.io/badge/license-GPLv2+-lightgray.svg
25+ [![license][]]: https://www.gnu.org/licenses/gpl.html
26+ [pandoc-discuss on google groups]: https://img.shields.io/badge/pandoc-discuss-red.svg?style=social
27+ [![pandoc-discuss on google groups]]: https://groups.google.com/forum/#!forum/pandoc-discuss
1328
1429The universal markup converter
1530------------------------------
1631
32+::: {#description}
1733Pandoc is a [Haskell] library for converting from one markup format to
18−another, and a command-line tool that uses this library. It can read
19−[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored
20−Markdown], [MultiMarkdown], and (subsets of) [Textile],
34+another, and a command-line tool that uses this library.
35+
36+Pandoc can read [Markdown], [CommonMark], [PHP Markdown Extra],
37+[GitHub-Flavored Markdown], [MultiMarkdown], and (subsets of) [Textile],
2138[reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki markup],
22−[TikiWiki markup], [Creole 1.0], [Haddock markup], [OPML], [Emacs Org mode],
23−[DocBook], [JATS], [Muse], [txt2tags], [Vimwiki], [EPUB], [ODT], and
24−[Word docx]; and it can write plain text, [Markdown], [CommonMark], [PHP
25−Markdown Extra], [GitHub-Flavored Markdown], [MultiMarkdown],
26−[reStructuredText], [XHTML], [HTML5], [LaTeX] \(including
27−[`beamer`] slide shows\), [ConTeXt], [RTF], [OPML], [DocBook], [JATS],
28−[OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki
29−markup], [DokuWiki markup], [ZimWiki markup], [Haddock markup],
30−[EPUB] \(v2 or v3\), [FictionBook2], [Textile], [groff man],
31−[groff ms], [Emacs Org mode], [AsciiDoc], [InDesign ICML], [TEI
39+[TikiWiki markup], [Creole 1.0], [Haddock markup], [OPML], [Emacs Org
40+mode], [DocBook], [JATS], [Muse], [txt2tags], [Vimwiki], [EPUB], [ODT],
41+and [Word docx].
42+
43+Pandoc can write plain text, [Markdown], [CommonMark], [PHP Markdown
44+Extra], [GitHub-Flavored Markdown], [MultiMarkdown], [reStructuredText],
45+[XHTML], [HTML5], [LaTeX] (including [`beamer`] slide shows), [ConTeXt],
46+[RTF], [OPML], [DocBook], [JATS], [OpenDocument], [ODT], [Word docx],
47+[GNU Texinfo], [MediaWiki markup], [DokuWiki markup], [ZimWiki markup],
48+[Haddock markup], [EPUB] (v2 or v3), [FictionBook2], [Textile], [groff
49+man], [groff ms], [Emacs Org mode], [AsciiDoc], [InDesign ICML], [TEI
3250Simple], [Muse], [PowerPoint] slide shows and [Slidy], [Slideous],
3351[DZSlides], [reveal.js] or [S5] HTML slide shows. It can also produce
3452[PDF] output on systems where LaTeX, ConTeXt, `pdfroff`, `wkhtmltopdf`,
3553`prince`, or `weasyprint` is installed.
3654
37−Pandoc's enhanced version of Markdown includes syntax for [footnotes],
38−[tables], flexible [ordered lists], [definition lists], [fenced code
39−blocks], [superscripts and subscripts], [strikeout], [metadata blocks],
40−automatic tables of contents, embedded LaTeX [math], [citations], and
41−[Markdown inside HTML block elements](#extension-markdown_in_html_blocks).
42−(These enhancements, described further under
43−[Pandoc's Markdown], can be disabled using the `markdown_strict` input
44−or output format.)
45−
46−In contrast to most existing tools for converting Markdown to HTML, which
47−use regex substitutions, pandoc has a modular design: it consists of a
48−set of readers, which parse text in a given format and produce a native
49−representation of the document, and a set of writers, which convert
50−this native representation into a target format. Thus, adding an input
51−or output format requires only adding a reader or writer.
55+Pandoc's enhanced version of Markdown includes syntax for tables,
56+definition lists, metadata blocks, `Div` blocks, footnotes and
57+citations, embedded LaTeX (including math), Markdown inside HTML block
58+elements, and much more. These enhancements, described further under
59+Pandoc's Markdown, can be disabled using the `markdown_strict` format.
60+
61+Pandoc has a modular design: it consists of a set of readers, which
62+parse text in a given format and produce a native representation of the
63+document (like an *abstract syntax tree* or AST), and a set of writers,
64+which convert this native representation into a target format. Thus,
65+adding an input or output format requires only adding a reader or
66+writer. Users can also run custom [pandoc filters] to modify the
67+intermediate AST.
5268
5369Because pandoc's intermediate representation of a document is less
54−expressive than many of the formats it converts between, one should
55−not expect perfect conversions between every format and every other.
56−Pandoc attempts to preserve the structural elements of a document, but
57−not formatting details such as margin size. And some document elements,
58−such as complex tables, may not fit into pandoc's simple document
59−model. While conversions from pandoc's Markdown to all formats aspire
60−to be perfect, conversions from formats more expressive than pandoc's
61−Markdown can be expected to be lossy.
62−
63−[Markdown]: http://daringfireball.net/projects/markdown/
64−[CommonMark]: http://commonmark.org
65−[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/
66−[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/
67−[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/
68−[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
69−[S5]: http://meyerweb.com/eric/tools/s5/
70−[Slidy]: http://www.w3.org/Talks/Tools/Slidy/
71−[Slideous]: http://goessner.net/articles/slideous/
72−[HTML]: http://www.w3.org/html/
73−[HTML5]: http://www.w3.org/TR/html5/
74−[XHTML]: http://www.w3.org/TR/xhtml1/
75−[LaTeX]: http://latex-project.org
76−[`beamer`]: https://ctan.org/pkg/beamer
77−[Beamer User's Guide]: http://ctan.math.utah.edu/ctan/tex-archive/macros/latex/contrib/beamer/doc/beameruserguide.pdf
78−[ConTeXt]: http://www.contextgarden.net/
79−[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
80−[Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0
81−[DocBook]: http://docbook.org
82−[JATS]: https://jats.nlm.nih.gov
83−[txt2tags]: http://txt2tags.org
84−[EPUB]: http://idpf.org/epub
85−[OPML]: http://dev.opml.org/spec2.html
86−[OpenDocument]: http://opendocument.xml.org
87−[ODT]: http://en.wikipedia.org/wiki/OpenDocument
88−[Textile]: http://redcloth.org/textile
89−[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting
90−[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
91−[ZimWiki markup]: http://zim-wiki.org/manual/Help/Wiki_Syntax.html
92−[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
93−[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
94−[groff man]: http://man7.org/linux/man-pages/man7/groff_man.7.html
95−[groff ms]: http://man7.org/linux/man-pages/man7/groff_ms.7.html
96−[Haskell]: https://www.haskell.org
97−[GNU Texinfo]: http://www.gnu.org/software/texinfo/
98−[Emacs Org mode]: http://orgmode.org
99−[AsciiDoc]: http://www.methods.co.nz/asciidoc/
100−[DZSlides]: http://paulrouget.com/dzslides/
101−[Word docx]: https://en.wikipedia.org/wiki/Office_Open_XML
102−[PDF]: https://www.adobe.com/pdf/
103−[reveal.js]: http://lab.hakim.se/reveal-js/
104−[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
105−[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf
106−[TEI Simple]: https://github.com/TEIC/TEI-Simple
107−[Muse]: https://amusewiki.org/library/manual
108−[PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint
109−[Vimwiki]: https://vimwiki.github.io
110−
111−
112−
113−[footnotes]: http://pandoc.org/MANUAL.html#footnotes
114−[tables]: http://pandoc.org/MANUAL.html#tables
115−[ordered lists]: http://pandoc.org/MANUAL.html#ordered-lists
116−[definition lists]: http://pandoc.org/MANUAL.html#definition-lists
117−[fenced code blocks]: http://pandoc.org/MANUAL.html#fenced-code-blocks
118−[superscripts and subscripts]: http://pandoc.org/MANUAL.html#superscripts-and-subscripts
119−[strikeout]: http://pandoc.org/MANUAL.html#strikeout
120−[metadata blocks]: http://pandoc.org/MANUAL.html#metadata-blocks
121−[math]: http://pandoc.org/MANUAL.html#math
122−[citations]: http://pandoc.org/MANUAL.html#citations
123−[Markdown inside HTML block elements]: http://pandoc.org/MANUAL.html#extension-markdown_in_html_blocks
124−[Pandoc's Markdown]: http://pandoc.org/MANUAL.html#pandocs-markdown
70+expressive than many of the formats it converts between, one should not
71+expect perfect conversions between every format and every other. Pandoc
72+attempts to preserve the structural elements of a document, but not
73+formatting details such as margin size. And some document elements, such
74+as complex tables, may not fit into pandoc's simple document model.
75+While conversions from pandoc's Markdown to all formats aspire to be
76+perfect, conversions from formats more expressive than pandoc's Markdown
77+can be expected to be lossy.
78+
79+Using `pandoc`
80+--------------
81+:::
82+
83+ [Haskell]: https://www.haskell.org
84+ [Markdown]: http://daringfireball.net/projects/markdown/
85+ [CommonMark]: http://commonmark.org
86+ [PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/
87+ [GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/
88+ [MultiMarkdown]: http://fletcherpenney.net/multimarkdown/
89+ [Textile]: http://redcloth.org/textile
90+ [reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
91+ [HTML]: http://www.w3.org/html/
92+ [LaTeX]: http://latex-project.org
93+ [MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting
94+ [TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
95+ [TikiWiki markup]: https://doc.tiki.org/Wiki-Syntax-Text#The_Markup_Language_Wiki-Syntax
96+ [Creole 1.0]: http://www.wikicreole.org/wiki/Creole1.0
97+ [Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
98+ [OPML]: http://dev.opml.org/spec2.html
99+ [Emacs Org mode]: http://orgmode.org
100+ [DocBook]: http://docbook.org
101+ [JATS]: https://jats.nlm.nih.gov
102+ [Muse]: https://amusewiki.org/library/manual
103+ [txt2tags]: http://txt2tags.org
104+ [Vimwiki]: https://vimwiki.github.io
105+ [EPUB]: http://idpf.org/epub
106+ [ODT]: http://en.wikipedia.org/wiki/OpenDocument
107+ [Word docx]: https://en.wikipedia.org/wiki/Office_Open_XML
108+ [XHTML]: http://www.w3.org/TR/xhtml1/
109+ [HTML5]: http://www.w3.org/TR/html5/
110+ [`beamer`]: https://ctan.org/pkg/beamer
111+ [ConTeXt]: http://www.contextgarden.net/
112+ [RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
113+ [OpenDocument]: http://opendocument.xml.org
114+ [GNU Texinfo]: http://www.gnu.org/software/texinfo/
115+ [DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
116+ [ZimWiki markup]: http://zim-wiki.org/manual/Help/Wiki_Syntax.html
117+ [FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
118+ [groff man]: http://man7.org/linux/man-pages/man7/groff_man.7.html
119+ [groff ms]: http://man7.org/linux/man-pages/man7/groff_ms.7.html
120+ [AsciiDoc]: http://www.methods.co.nz/asciidoc/
121+ [InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf
122+ [TEI Simple]: https://github.com/TEIC/TEI-Simple
123+ [PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint
124+ [Slidy]: http://www.w3.org/Talks/Tools/Slidy/
125+ [Slideous]: http://goessner.net/articles/slideous/
126+ [DZSlides]: http://paulrouget.com/dzslides/
127+ [reveal.js]: http://lab.hakim.se/reveal-js/
128+ [S5]: http://meyerweb.com/eric/tools/s5/
129+ [PDF]: https://www.adobe.com/pdf/
130+ [pandoc filters]: http://pandoc.org/filters.html
125131
126132Installing
127133----------
128134
129−Here's [how to install pandoc](INSTALL.md).
135+Here's [how to install pandoc].
136+
137+ [how to install pandoc]: INSTALL.md
130138
131139Documentation
132140-------------
133141
134−Pandoc's website contains a full [User's Guide](https://pandoc.org/MANUAL.html).
135−It is also available [here](MANUAL.txt) as pandoc-flavored Markdown.
136−The website also contains some [examples of the use of
137−pandoc](https://pandoc.org/demos.html) and a limited [online
138−demo](https://pandoc.org/try).
142+Pandoc's website contains a full [User's Guide]. It is also available
143+[here] as pandoc-flavored Markdown. The website also contains some
144+[examples of the use of pandoc] and a limited [online demo].
145+
146+ [User's Guide]: https://pandoc.org/MANUAL.html
147+ [here]: MANUAL.txt
148+ [examples of the use of pandoc]: https://pandoc.org/demos.html
149+ [online demo]: https://pandoc.org/try
139150
140151Contributing
141152------------
142153
143−Pull requests, bug reports, and feature requests are welcome. Please make
144−sure to read [the contributor guidelines](CONTRIBUTING.md) before opening a
145−new issue.
154+Pull requests, bug reports, and feature requests are welcome. Please
155+make sure to read [the contributor guidelines] before opening a new
156+issue.
146157
158+ [the contributor guidelines]: CONTRIBUTING.md
147159
148160License
149161-------
150162
151163© 2006-2017 John MacFarlane (jgm@berkeley.edu). Released under the
152−[GPL], version 2 or greater. This software carries no warranty of
153−any kind. (See COPYRIGHT for full copyright and warranty notices.)
164+[GPL], version 2 or greater. This software carries no warranty of any
165+kind. (See COPYRIGHT for full copyright and warranty notices.)
154166
155−[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
167+ [GPL]: http://www.gnu.org/copyleft/gpl.html
168+ "GNU General Public License"