@@ -11,13 +11,16 @@ Description
1111===========
1212
1313Pandoc is a [Haskell] library for converting from one markup format to
14−another, and a command-line tool that uses this library. It can read
15−[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored
16−Markdown], [MultiMarkdown], and (subsets of) [Textile],
14+another, and a command-line tool that uses this library.
15+
16+Pandoc can read [Markdown], [CommonMark], [PHP Markdown Extra],
17+[GitHub-Flavored Markdown], [MultiMarkdown], and (subsets of) [Textile],
1718[reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki
1819markup], [TikiWiki markup], [Creole 1.0], [Haddock markup], [OPML],
1920[Emacs Org mode], [DocBook], [JATS], [Muse], [txt2tags], [Vimwiki],
20−[EPUB], [ODT], and [Word docx]; and it can write plain text, [Markdown],
21+[EPUB], [ODT], and [Word docx].
22+
23+Pandoc can write plain text, [Markdown],
2124[CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown],
2225[MultiMarkdown], [reStructuredText], [XHTML], [HTML5], [LaTeX]
2326\(including [`beamer`] slide shows\), [ConTeXt], [RTF], [OPML],
@@ -30,21 +33,20 @@ Simple], [Muse], [PowerPoint] slide shows and [Slidy], [Slideous],
3033[PDF] output on systems where LaTeX, ConTeXt, `pdfroff`,
3134`wkhtmltopdf`, `prince`, or `weasyprint` is installed.
3235
33−Pandoc's enhanced version of Markdown includes syntax for [footnotes],
34−[tables], flexible [ordered lists], [definition lists], [fenced code
35−blocks], [superscripts and subscripts], [strikeout], [metadata blocks],
36−automatic tables of contents, embedded LaTeX [math], [citations], and
37−[Markdown inside HTML block elements][Extension:
38−`markdown_in_html_blocks`]. (These enhancements, described further under
39−[Pandoc's Markdown], can be disabled using the `markdown_strict` input
40−or output format.)
41−
42−In contrast to most existing tools for converting Markdown to HTML, which
43−use regex substitutions, pandoc has a modular design: it consists of a
44−set of readers, which parse text in a given format and produce a native
45−representation of the document, and a set of writers, which convert
36+Pandoc's enhanced version of Markdown includes syntax for [tables],
37+[definition lists], [metadata blocks], [`Div` blocks][Extension:
38+`fenced_divs`], [footnotes] and [citations], embedded
39+[LaTeX][Extension: `raw_tex`] (incl. [math]), [Markdown inside HTML
40+block elements][Extension: `markdown_in_html_blocks`], and much more.
41+These enhancements, described further under [Pandoc's Markdown],
42+can be disabled using the `markdown_strict` format.
43+
44+Pandoc has a modular design: it consists of a set of readers, which parse
45+text in a given format and produce a native representation of the document
46+(like an _abstract syntax tree_ or AST), and a set of writers, which convert
4647this native representation into a target format. Thus, adding an input
47−or output format requires only adding a reader or writer.
48+or output format requires only adding a reader or writer. Users can also
49+run custom [pandoc filters] to modify the intermediate AST.
4850
4951Because pandoc's intermediate representation of a document is less
5052expressive than many of the formats it converts between, one should
@@ -109,45 +111,32 @@ Markdown can be expected to be lossy.
109111Using `pandoc`
110112--------------
111113
112−If no *input-file* is specified, input is read from *stdin*.
113−Otherwise, the *input-files* are concatenated (with a blank
114−line between each) and used as input. Output goes to *stdout* by
115−default (though output to the terminal is disabled for the
116−`odt`, `docx`, `epub2`, and `epub3` output formats, unless it is
117−forced using `-o -`). For output to a file, use the `-o`
118−option:
114+If no *input-files* are specified, input is read from *stdin*.
115+Output goes to *stdout* by default. For output to a file,
116+use the `-o` option:
119117
120118 pandoc -o output.html input.txt
121119
122−By default, pandoc produces a document fragment, not a standalone
123−document with a proper header and footer. To produce a standalone
124−document, use the `-s` or `--standalone` flag:
120+By default, pandoc produces a document fragment. To produce a standalone
121+document (e.g. a valid HTML file including `<head>` and `<body>`),
122+use the `-s` or `--standalone` flag:
125123
126124 pandoc -s -o output.html input.txt
127125
128126For more information on how standalone documents are produced, see
129−[Templates], below.
130−
131−Instead of a file, an absolute URI may be given. In this case
132−pandoc will fetch the content using HTTP:
133−
134− pandoc -f html -t markdown http://www.fsf.org
135−
136−It is possible to supply a custom User-Agent string or other
137−header when requesting a document from a URL:
138−
139− pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
140− http://www.fsf.org
127+[Templates] below.
141128
142129If multiple input files are given, `pandoc` will concatenate them all (with
143−blank lines between them) before parsing. This feature is disabled for
144− binary input formats such as `EPUB`, `odt`, and `docx`.
130+blank lines between them) before parsing. (Use `--file-scope` to parse files
131+individually.)
132+
133+Specifying formats
134+------------------
145135
146136The format of the input and output can be specified explicitly using
147137command-line options. The input format can be specified using the
148−`-r/--read` or `-f/--from` options, the output format using the
149−`-w/--write` or `-t/--to` options. Thus, to convert `hello.txt` from
150−Markdown to LaTeX, you could type:
138+`-f/--from` option, the output format using the `-t/--to` option.
139+Thus, to convert `hello.txt` from Markdown to LaTeX, you could type:
151140
152141 pandoc -f markdown -t latex hello.txt
153142
@@ -155,14 +144,11 @@ To convert `hello.html` from HTML to Markdown:
155144
156145 pandoc -f html -t markdown hello.html
157146
158−Supported output formats are listed below under the `-t/--to` option.
159−Supported input formats are listed below under the `-f/--from` option. Note
160−that the `rst`, `textile`, `latex`, and `html` readers are not complete;
161−there are some constructs that they do not parse.
147+Supported input and output formats are listed below under [Options].
162148
163149If the input or output format is not specified explicitly, `pandoc`
164−will attempt to guess it from the extensions of
165−the input and output filenames. Thus, for example,
150+will attempt to guess it from the extensions of the filenames.
151+Thus, for example,
166152
167153 pandoc -o hello.tex hello.txt
168154
@@ -171,7 +157,10 @@ is specified (so that output goes to *stdout*), or if the output file's
171157extension is unknown, the output format will default to HTML.
172158If no input file is specified (so that input comes from *stdin*), or
173159if the input files' extensions are unknown, the input format will
174−be assumed to be Markdown unless explicitly specified.
160+be assumed to be Markdown.
161+
162+Character encoding
163+------------------
175164
176165Pandoc uses the UTF-8 character encoding for both input and output.
177166If your local character encoding is not UTF-8, you
@@ -189,30 +178,12 @@ will only be included if you use the `-s/--standalone` option.
189178Creating a PDF
190179--------------
191180
192−To produce a PDF, specify an output file with a `.pdf` extension.
193−By default, pandoc will use LaTeX to create the PDF:
181+To produce a PDF, specify an output file with a `.pdf` extension:
194182
195183 pandoc test.txt -o test.pdf
196184
197−Production of a PDF requires that a LaTeX engine be installed (see
198−`--pdf-engine`, below), and assumes that the following LaTeX packages
199−are available: [`amsfonts`], [`amsmath`], [`lm`], [`unicode-math`],
200−[`ifxetex`], [`ifluatex`], [`listings`] (if the
201−`--listings` option is used), [`fancyvrb`], [`longtable`],
202−[`booktabs`], [`graphicx`] and [`grffile`] (if the document
203−contains images), [`hyperref`], [`xcolor`] (with `colorlinks`), [`ulem`], [`geometry`] (with the
204−`geometry` variable set), [`setspace`] (with `linestretch`), and
205−[`babel`] (with `lang`). The use of `xelatex` or `lualatex` as
206−the LaTeX engine requires [`fontspec`]. `xelatex` uses
207−[`polyglossia`] (with `lang`), [`xecjk`], and [`bidi`] (with the
208−`dir` variable set). If the `mathspec` variable is set,
209−`xelatex` will use [`mathspec`] instead of [`unicode-math`].
210−The [`upquote`] and [`microtype`] packages are used if
211−available, and [`csquotes`] will be used for [typography]
212−if added to the template or included in any header file. The
213−[`natbib`], [`biblatex`], [`bibtex`], and [`biber`] packages can
214−optionally be used for [citation rendering]. These are included
215−with all recent versions of [TeX Live].
185+By default, pandoc will use LaTeX to create the PDF, which requires
186+that a LaTeX engine be installed (see `--pdf-engine` below).
216187
217188Alternatively, pandoc can use [ConTeXt], `pdfroff`, or any of the
218189following HTML/CSS-to-PDF-engines, to create a PDF: [`wkhtmltopdf`],
@@ -228,6 +199,29 @@ If `wkhtmltopdf` is used, then the variables `margin-left`,
228199`margin-right`, `margin-top`, `margin-bottom`, and `papersize`
229200will affect the output.
230201
202+To debug the PDF creation, it can be useful to look at the intermediate
203+representation: instead of `-o test.pdf`, use for example `-s -o test.tex`
204+to output the generated LaTeX. You can then test it with `pdflatex test.tex`.
205+
206+When using LaTeX, the following packages need to be available
207+(they are included with all recent versions of [TeX Live]):
208+[`amsfonts`], [`amsmath`], [`lm`], [`unicode-math`],
209+[`ifxetex`], [`ifluatex`], [`listings`] (if the
210+`--listings` option is used), [`fancyvrb`], [`longtable`],
211+[`booktabs`], [`graphicx`] and [`grffile`] (if the document
212+contains images), [`hyperref`], [`xcolor`] (with `colorlinks`), [`ulem`], [`geometry`] (with the
213+`geometry` variable set), [`setspace`] (with `linestretch`), and
214+[`babel`] (with `lang`). The use of `xelatex` or `lualatex` as
215+the LaTeX engine requires [`fontspec`]. `xelatex` uses
216+[`polyglossia`] (with `lang`), [`xecjk`], and [`bidi`] (with the
217+`dir` variable set). If the `mathspec` variable is set,
218+`xelatex` will use [`mathspec`] instead of [`unicode-math`].
219+The [`upquote`] and [`microtype`] packages are used if
220+available, and [`csquotes`] will be used for [typography]
221+if added to the template or included in any header file. The
222+[`natbib`], [`biblatex`], [`bibtex`], and [`biber`] packages can
223+optionally be used for [citation rendering].
224+
231225[`amsfonts`]: https://ctan.org/pkg/amsfonts
232226[`amsmath`]: https://ctan.org/pkg/amsmath
233227[`lm`]: https://ctan.org/pkg/lm
@@ -262,6 +256,20 @@ will affect the output.
262256[`weasyprint`]: http://weasyprint.org
263257[`prince`]: https://www.princexml.com/
264258
259+Reading from the Web
260+--------------------
261+
262+Instead of an input file, an absolute URI may be given. In this case
263+pandoc will fetch the content using HTTP:
264+
265+ pandoc -f html -t markdown http://www.fsf.org
266+
267+It is possible to supply a custom User-Agent string or other
268+header when requesting a document from a URL:
269+
270+ pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
271+ http://www.fsf.org
272+
265273Options
266274=======
267275
@@ -318,9 +326,8 @@ General options
318326 below). (`markdown_github` provides deprecated and less accurate
319327 support for Github-Flavored Markdown; please use `gfm` instead,
320328 unless you use extensions that do not work with `gfm`.) Note that
321− `odt`, `epub`, and `epub3` output will not be directed to
322− *stdout*; an output filename must be specified using the
323− `-o/--output` option. Extensions can be individually enabled or
329+ `odt`, `docx`, and `epub` output will not be directed to *stdout*
330+ unless forced with `-o -`. Extensions can be individually enabled or
324331 disabled by appending `+EXTENSION` or `-EXTENSION` to the format
325332 name. See [Extensions] below, for a list of extensions and their
326333 names. See `--list-output-formats` and `--list-extensions`, below.
@@ -389,7 +396,7 @@ General options
389396
390397`--list-extensions`[`=`*FORMAT*]
391398
392−: List supported Markdown extensions, one per line, preceded
399+: List supported extensions, one per line, preceded
393400 by a `+` or `-` indicating whether it is enabled by default
394401 in *FORMAT*. If *FORMAT* is not specified, defaults for
395402 pandoc's Markdown are given.
@@ -3305,45 +3312,6 @@ For the most part this should give the same output as `raw_html`,
33053312but it makes it easier to write pandoc filters to manipulate groups
33063313of inlines.
33073314
3308−#### Extension: `fenced_divs` ####
3309−
3310−Allow special fenced syntax for native `Div` blocks. A Div
3311−starts with a fence containing at least three consecutive
3312−colons plus some attributes. The attributes may optionally
3313−be followed by another string of consecutive colons.
3314−The attribute syntax is exactly as in fenced code blocks (see
3315−[Extension: `fenced_code_attributes`]). As with fenced
3316−code blocks, one can use either attributes in curly braces
3317−or a single unbraced word, which will be treated as a class
3318−name. The Div ends with another line containing a string of at
3319−least three consecutive colons. The fenced Div should be
3320−separated by blank lines from preceding and following blocks.
3321−
3322−Example:
3323−
3324− ::::: {#special .sidebar}
3325− Here is a paragraph.
3326−
3327− And another.
3328− :::::
3329−
3330−Fenced divs can be nested. Opening fences are distinguished
3331−because they *must* have attributes:
3332−
3333− ::: Warning ::::::
3334− This is a warning.
3335−
3336− ::: Danger
3337− This is a warning within a warning.
3338− :::
3339− ::::::::::::::::::
3340−
3341−Fences without attributes are always closing fences. Unlike
3342−with fenced code blocks, the number of colons in the closing
3343−fence need not match the number in the opening fence. However,
3344−it can be helpful for visual clarity to use fences of different
3345−lengths to distinguish nested divs from their parents.
3346−
33473315#### Extension: `raw_tex` ####
33483316
33493317In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
@@ -3605,13 +3573,59 @@ For example:
36053573 is to look at the image resolution and the dpi metadata embedded in
36063574 the image file.
36073575
3608−Spans
3609−-----
3576+Divs and Spans
3577+--------------
3578+
3579+Using the `native_divs` and `native_spans` extensions
3580+(see [above][Extension: `native_divs`]), HTML syntax can
3581+be used as part of markdown to create native `Div` and `Span`
3582+elements in the pandoc AST (as opposed to raw HTML).
3583+However, there is also nicer syntax available:
3584+
3585+#### Extension: `fenced_divs` ####
3586+
3587+Allow special fenced syntax for native `Div` blocks. A Div
3588+starts with a fence containing at least three consecutive
3589+colons plus some attributes. The attributes may optionally
3590+be followed by another string of consecutive colons.
3591+The attribute syntax is exactly as in fenced code blocks (see
3592+[Extension: `fenced_code_attributes`]). As with fenced
3593+code blocks, one can use either attributes in curly braces
3594+or a single unbraced word, which will be treated as a class
3595+name. The Div ends with another line containing a string of at
3596+least three consecutive colons. The fenced Div should be
3597+separated by blank lines from preceding and following blocks.
3598+
3599+Example:
3600+
3601+ ::::: {#special .sidebar}
3602+ Here is a paragraph.
3603+
3604+ And another.
3605+ :::::
3606+
3607+Fenced divs can be nested. Opening fences are distinguished
3608+because they *must* have attributes:
3609+
3610+ ::: Warning ::::::
3611+ This is a warning.
3612+
3613+ ::: Danger
3614+ This is a warning within a warning.
3615+ :::
3616+ ::::::::::::::::::
3617+
3618+Fences without attributes are always closing fences. Unlike
3619+with fenced code blocks, the number of colons in the closing
3620+fence need not match the number in the opening fence. However,
3621+it can be helpful for visual clarity to use fences of different
3622+lengths to distinguish nested divs from their parents.
3623+
36103624
36113625#### Extension: `bracketed_spans` ####
36123626
36133627A bracketed sequence of inlines, as one would use to begin
3614−a link, will be treated as a span with attributes if it is
3628+a link, will be treated as a `Span` with attributes if it is
36153629followed immediately by attributes:
36163630
36173631 [This is *some text*]{.class key="val"}