@@ -11,13 +11,16 @@ Description
11===========
11===========
13Pandoc is a [Haskell] library for converting from one markup format to
13Pandoc 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
14+another, and a command-line tool that uses this library.
15−[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored
16+Pandoc can read [Markdown], [CommonMark], [PHP Markdown Extra],
16−Markdown], [MultiMarkdown], and (subsets of) [Textile],
17+[GitHub-Flavored Markdown], [MultiMarkdown], and (subsets of) [Textile],
17[reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki
18[reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki
18markup], [TikiWiki markup], [Creole 1.0], [Haddock markup], [OPML],
19markup], [TikiWiki markup], [Creole 1.0], [Haddock markup], [OPML],
19[Emacs Org mode], [DocBook], [JATS], [Muse], [txt2tags], [Vimwiki],
20[Emacs Org mode], [DocBook], [JATS], [Muse], [txt2tags], [Vimwiki],
21+[EPUB], [ODT], and [Word docx].
20−[EPUB], [ODT], and [Word docx]; and it can write plain text, [Markdown],
23+Pandoc can write plain text, [Markdown],
21[CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown],
24[CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown],
22[MultiMarkdown], [reStructuredText], [XHTML], [HTML5], [LaTeX]
25[MultiMarkdown], [reStructuredText], [XHTML], [HTML5], [LaTeX]
23\(including [`beamer`] slide shows\), [ConTeXt], [RTF], [OPML],
26\(including [`beamer`] slide shows\), [ConTeXt], [RTF], [OPML],
@@ -30,21 +33,20 @@ Simple], [Muse], [PowerPoint] slide shows and [Slidy], [Slideous],
30[PDF] output on systems where LaTeX, ConTeXt, `pdfroff`,
33[PDF] output on systems where LaTeX, ConTeXt, `pdfroff`,
31`wkhtmltopdf`, `prince`, or `weasyprint` is installed.
34`wkhtmltopdf`, `prince`, or `weasyprint` is installed.
33−Pandoc's enhanced version of Markdown includes syntax for [footnotes],
36+Pandoc's enhanced version of Markdown includes syntax for [tables],
34−[tables], flexible [ordered lists], [definition lists], [fenced code
37+[definition lists], [metadata blocks], [`Div` blocks][Extension:
35−blocks], [superscripts and subscripts], [strikeout], [metadata blocks],
38+`fenced_divs`], [footnotes] and [citations], embedded
36−automatic tables of contents, embedded LaTeX [math], [citations], and
39+[LaTeX][Extension: `raw_tex`] (incl. [math]), [Markdown inside HTML
37−[Markdown inside HTML block elements][Extension:
40+block elements][Extension: `markdown_in_html_blocks`], and much more.
38−`markdown_in_html_blocks`]. (These enhancements, described further under
41+These enhancements, described further under [Pandoc's Markdown],
39−[Pandoc's Markdown], can be disabled using the `markdown_strict` input
42+can be disabled using the `markdown_strict` format.
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+Pandoc has a modular design: it consists of a set of readers, which parse
44−set of readers, which parse text in a given format and produce a native
45+text in a given format and produce a native representation of the document
45−representation of the document, and a set of writers, which convert
46+(like an _abstract syntax tree_ or AST), and a set of writers, which convert
46this native representation into a target format. Thus, adding an input
47this 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.
49Because pandoc's intermediate representation of a document is less
51Because pandoc's intermediate representation of a document is less
50expressive than many of the formats it converts between, one should
52expressive than many of the formats it converts between, one should
@@ -109,45 +111,32 @@ Markdown can be expected to be lossy.
109Using `pandoc`
111Using `pandoc`
110--------------
112--------------
112−If no *input-file* is specified, input is read from *stdin*.
114+If no *input-files* are 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+Output goes to *stdout* by default. For output to a file,
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:
116+use the `-o` option:
120 pandoc -o output.html input.txt
118 pandoc -o output.html input.txt
122−By default, pandoc produces a document fragment, not a standalone
120+By default, pandoc produces a document fragment. To produce a standalone
123−document with a proper header and footer. To produce a standalone
121+document (e.g. a valid HTML file including `<head>` and `<body>`),
124−document, use the `-s` or `--standalone` flag:
122+use the `-s` or `--standalone` flag:
126 pandoc -s -o output.html input.txt
124 pandoc -s -o output.html input.txt
128For more information on how standalone documents are produced, see
126For more information on how standalone documents are produced, see
129−[Templates], below.
127+[Templates] below.
131−Instead of a file, an absolute URI may be given. In this case
132−pandoc will fetch the content using HTTP:
134− pandoc -f html -t markdown http://www.fsf.org
136−It is possible to supply a custom User-Agent string or other
137−header when requesting a document from a URL:
139− pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
142If multiple input files are given, `pandoc` will concatenate them all (with
129If multiple input files are given, `pandoc` will concatenate them all (with
143−blank lines between them) before parsing. This feature is disabled for
130+blank lines between them) before parsing. (Use `--file-scope` to parse files
144− binary input formats such as `EPUB`, `odt`, and `docx`.
131+individually.)
146The format of the input and output can be specified explicitly using
136The format of the input and output can be specified explicitly using
147command-line options. The input format can be specified using the
137command-line options. The input format can be specified using the
148−`-r/--read` or `-f/--from` options, the output format using the
138+`-f/--from` option, the output format using the `-t/--to` option.
149−`-w/--write` or `-t/--to` options. Thus, to convert `hello.txt` from
150−Markdown to LaTeX, you could type:
139+Thus, to convert `hello.txt` from Markdown to LaTeX, you could type:
152 pandoc -f markdown -t latex hello.txt
141 pandoc -f markdown -t latex hello.txt
@@ -155,14 +144,11 @@ To convert `hello.html` from HTML to Markdown:
156 pandoc -f html -t markdown hello.html
145 pandoc -f html -t markdown hello.html
158−Supported output formats are listed below under the `-t/--to` option.
147+Supported input and output formats are listed below under [Options].
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.
163If the input or output format is not specified explicitly, `pandoc`
149If the input or output format is not specified explicitly, `pandoc`
164−will attempt to guess it from the extensions of
150+will attempt to guess it from the extensions of the filenames.
165−the input and output filenames. Thus, for example,
151+Thus, for example,
167 pandoc -o hello.tex hello.txt
153 pandoc -o hello.tex hello.txt
@@ -171,7 +157,10 @@ is specified (so that output goes to *stdout*), or if the output file's
171extension is unknown, the output format will default to HTML.
157extension is unknown, the output format will default to HTML.
172If no input file is specified (so that input comes from *stdin*), or
158If no input file is specified (so that input comes from *stdin*), or
173if the input files' extensions are unknown, the input format will
159if 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.
176Pandoc uses the UTF-8 character encoding for both input and output.
165Pandoc uses the UTF-8 character encoding for both input and output.
177If your local character encoding is not UTF-8, you
166If your local character encoding is not UTF-8, you
@@ -189,30 +178,12 @@ will only be included if you use the `-s/--standalone` option.
189Creating a PDF
178Creating a PDF
190--------------
179--------------
192−To produce a PDF, specify an output file with a `.pdf` extension.
181+To produce a PDF, specify an output file with a `.pdf` extension:
193−By default, pandoc will use LaTeX to create the PDF:
195 pandoc test.txt -o test.pdf
183 pandoc test.txt -o test.pdf
185+By default, pandoc will use LaTeX to create the PDF, which requires
197−Production of a PDF requires that a LaTeX engine be installed (see
186+that a LaTeX engine be installed (see `--pdf-engine` below).
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].
217Alternatively, pandoc can use [ConTeXt], `pdfroff`, or any of the
188Alternatively, pandoc can use [ConTeXt], `pdfroff`, or any of the
218following HTML/CSS-to-PDF-engines, to create a PDF: [`wkhtmltopdf`],
189following HTML/CSS-to-PDF-engines, to create a PDF: [`wkhtmltopdf`],
@@ -228,6 +199,29 @@ If `wkhtmltopdf` is used, then the variables `margin-left`,
228`margin-right`, `margin-top`, `margin-bottom`, and `papersize`
199`margin-right`, `margin-top`, `margin-bottom`, and `papersize`
229will affect the output.
200will affect the output.
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`.
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].
231[`amsfonts`]: https://ctan.org/pkg/amsfonts
225[`amsfonts`]: https://ctan.org/pkg/amsfonts
232[`amsmath`]: https://ctan.org/pkg/amsmath
226[`amsmath`]: https://ctan.org/pkg/amsmath
233[`lm`]: https://ctan.org/pkg/lm
227[`lm`]: https://ctan.org/pkg/lm
@@ -262,6 +256,20 @@ will affect the output.
262[`weasyprint`]: http://weasyprint.org
256[`weasyprint`]: http://weasyprint.org
263[`prince`]: https://www.princexml.com/
257[`prince`]: https://www.princexml.com/
262+Instead of an input file, an absolute URI may be given. In this case
263+pandoc will fetch the content using HTTP:
265+ pandoc -f html -t markdown http://www.fsf.org
267+It is possible to supply a custom User-Agent string or other
268+header when requesting a document from a URL:
270+ pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
@@ -318,9 +326,8 @@ General options
318 below). (`markdown_github` provides deprecated and less accurate
326 below). (`markdown_github` provides deprecated and less accurate
319 support for Github-Flavored Markdown; please use `gfm` instead,
327 support for Github-Flavored Markdown; please use `gfm` instead,
320 unless you use extensions that do not work with `gfm`.) Note that
328 unless you use extensions that do not work with `gfm`.) Note that
321− `odt`, `epub`, and `epub3` output will not be directed to
329+ `odt`, `docx`, and `epub` output will not be directed to *stdout*
322− *stdout*; an output filename must be specified using the
323− `-o/--output` option. Extensions can be individually enabled or
330+ unless forced with `-o -`. Extensions can be individually enabled or
324 disabled by appending `+EXTENSION` or `-EXTENSION` to the format
331 disabled by appending `+EXTENSION` or `-EXTENSION` to the format
325 name. See [Extensions] below, for a list of extensions and their
332 name. See [Extensions] below, for a list of extensions and their
326 names. See `--list-output-formats` and `--list-extensions`, below.
333 names. See `--list-output-formats` and `--list-extensions`, below.
@@ -389,7 +396,7 @@ General options
390`--list-extensions`[`=`*FORMAT*]
397`--list-extensions`[`=`*FORMAT*]
392−: List supported Markdown extensions, one per line, preceded
399+: List supported extensions, one per line, preceded
393 by a `+` or `-` indicating whether it is enabled by default
400 by a `+` or `-` indicating whether it is enabled by default
394 in *FORMAT*. If *FORMAT* is not specified, defaults for
401 in *FORMAT*. If *FORMAT* is not specified, defaults for
395 pandoc's Markdown are given.
402 pandoc's Markdown are given.
@@ -3305,45 +3312,6 @@ For the most part this should give the same output as `raw_html`,
3305but it makes it easier to write pandoc filters to manipulate groups
3312but it makes it easier to write pandoc filters to manipulate groups
3306of inlines.
3313of inlines.
3308−#### Extension: `fenced_divs` ####
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.
3324− ::::: {#special .sidebar}
3325− Here is a paragraph.
3330−Fenced divs can be nested. Opening fences are distinguished
3331−because they *must* have attributes:
3337− This is a warning within a warning.
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.
3347#### Extension: `raw_tex` ####
3315#### Extension: `raw_tex` ####
3349In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
3317In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
@@ -3605,13 +3573,59 @@ For example:
3605 is to look at the image resolution and the dpi metadata embedded in
3573 is to look at the image resolution and the dpi metadata embedded in
3606 the image file.
3574 the image file.
3608−Spans
3576+Divs and Spans
3609−-----
3577+--------------
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:
3585+#### Extension: `fenced_divs` ####
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.
3601+ ::::: {#special .sidebar}
3602+ Here is a paragraph.
3607+Fenced divs can be nested. Opening fences are distinguished
3608+because they *must* have attributes:
3614+ This is a warning within a warning.
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.
3611#### Extension: `bracketed_spans` ####
3625#### Extension: `bracketed_spans` ####
3613A bracketed sequence of inlines, as one would use to begin
3627A 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
3615followed immediately by attributes:
3629followed immediately by attributes:
3617 [This is *some text*]{.class key="val"}
3631 [This is *some text*]{.class key="val"}