@@ -1,14 +1,14 @@
1−% Pandoc User's Guide
2+title: Pandoc User's Guide
2−% John MacFarlane
3+author: John MacFarlane
3−% July 6, 2019
4+date: September 29, 2019
8`pandoc` [*options*] [*input-file*]...
9`pandoc` [*options*] [*input-file*]...
10−Description
11+# Description
13Pandoc is a [Haskell] library for converting from one markup format to
13Pandoc is a [Haskell] library for converting from one markup format to
14another, and a command-line tool that uses this library.
14another, and a command-line tool that uses this library.
@@ -40,8 +40,7 @@ model. While conversions from pandoc's Markdown to all formats aspire
40to be perfect, conversions from formats more expressive than pandoc's
40to be perfect, conversions from formats more expressive than pandoc's
41Markdown can be expected to be lossy.
41Markdown can be expected to be lossy.
43−Using pandoc
43+## Using pandoc
46If no *input-files* are specified, input is read from *stdin*.
45If no *input-files* are specified, input is read from *stdin*.
47Output goes to *stdout* by default. For output to a file,
46Output goes to *stdout* by default. For output to a file,
@@ -62,8 +61,7 @@ If multiple input files are given, `pandoc` will concatenate them all (with
62blank lines between them) before parsing. (Use `--file-scope` to parse files
61blank lines between them) before parsing. (Use `--file-scope` to parse files
63individually.)
62individually.)
65−Specifying formats
64+## Specifying formats
68The format of the input and output can be specified explicitly using
66The format of the input and output can be specified explicitly using
69command-line options. The input format can be specified using the
67command-line options. The input format can be specified using the
@@ -95,8 +93,7 @@ If no input file is specified (so that input comes from *stdin*), or
95if the input files' extensions are unknown, the input format will
93if the input files' extensions are unknown, the input format will
96be assumed to be Markdown.
94be assumed to be Markdown.
98−Character encoding
96+## Character encoding
101Pandoc uses the UTF-8 character encoding for both input and output.
98Pandoc uses the UTF-8 character encoding for both input and output.
102If your local character encoding is not UTF-8, you
99If your local character encoding is not UTF-8, you
@@ -111,8 +108,7 @@ will only be included if you use the `-s/--standalone` option.
112[`iconv`]: http://www.gnu.org/software/libiconv/
109[`iconv`]: http://www.gnu.org/software/libiconv/
114−Creating a PDF
111+## Creating a PDF
117To produce a PDF, specify an output file with a `.pdf` extension:
113To produce a PDF, specify an output file with a `.pdf` extension:
@@ -206,8 +202,7 @@ footnotes in tables).
209−Reading from the Web
205+## Reading from the Web
212Instead of an input file, an absolute URI may be given. In this case
207Instead of an input file, an absolute URI may be given. In this case
213pandoc will fetch the content using HTTP:
208pandoc will fetch the content using HTTP:
@@ -220,11 +215,9 @@ header when requesting a document from a URL:
220 pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
215 pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" \
221 http://www.fsf.org
216 http://www.fsf.org
226−General options {.options}
220+## General options {.options}
229`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
222`-f` *FORMAT*, `-r` *FORMAT*, `--from=`*FORMAT*, `--read=`*FORMAT*
@@ -476,8 +469,7 @@ General options {.options}
476[PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint
469[PowerPoint]: https://en.wikipedia.org/wiki/Microsoft_PowerPoint
477[Vimwiki]: https://vimwiki.github.io
470[Vimwiki]: https://vimwiki.github.io
479−Reader options {.options}
472+## Reader options {.options}
482`--shift-heading-level-by=`*NUMBER*
474`--shift-heading-level-by=`*NUMBER*
@@ -680,8 +672,7 @@ Reader options {.options}
680[perl]: https://metacpan.org/pod/Pandoc::Filter
672[perl]: https://metacpan.org/pod/Pandoc::Filter
681[JavaScript/node.js]: https://github.com/mvhenderson/pandoc-filter-node
673[JavaScript/node.js]: https://github.com/mvhenderson/pandoc-filter-node
683−General writer options {.options}
675+## General writer options {.options}
684−----------------------
686`-s`, `--standalone`
677`-s`, `--standalone`
@@ -884,8 +875,7 @@ General writer options {.options}
884 downloaded). If you're behind a proxy, you also need to set
875 downloaded). If you're behind a proxy, you also need to set
885 the environment variable `http_proxy` to `http://...`.
876 the environment variable `http_proxy` to `http://...`.
887−Options affecting specific writers {.options}
878+## Options affecting specific writers {.options}
888−----------------------------------
890`--self-contained`
880`--self-contained`
@@ -1255,8 +1245,7 @@ Options affecting specific writers {.options}
1255[Encoding issue with the listings package]:
1245[Encoding issue with the listings package]:
1256 https://en.wikibooks.org/wiki/LaTeX/Source_Code_Listings#Encoding_issue
1246 https://en.wikibooks.org/wiki/LaTeX/Source_Code_Listings#Encoding_issue
1258−Citation rendering {.options}
1248+## Citation rendering {.options}
1261`--bibliography=`*FILE*
1250`--bibliography=`*FILE*
@@ -1295,8 +1284,7 @@ Citation rendering {.options}
1295 with the `pandoc-citeproc` filter or with PDF output. It is intended for
1284 with the `pandoc-citeproc` filter or with PDF output. It is intended for
1296 use in producing a LaTeX file that can be processed with [`bibtex`] or [`biber`].
1285 use in producing a LaTeX file that can be processed with [`bibtex`] or [`biber`].
1298−Math rendering in HTML {.options}
1287+## Math rendering in HTML {.options}
1299−----------------------
1301The default is to render TeX math as far as possible using Unicode characters.
1289The default is to render TeX math as far as possible using Unicode characters.
1302Formulas are put inside a `span` with `class="math"`, so that they may be styled
1290Formulas are put inside a `span` with `class="math"`, so that they may be styled
@@ -1356,8 +1344,7 @@ of the following options.
1356[KaTeX]: https://github.com/Khan/KaTeX
1344[KaTeX]: https://github.com/Khan/KaTeX
1357[GladTeX]: http://humenda.github.io/GladTeX/
1345[GladTeX]: http://humenda.github.io/GladTeX/
1359−Options for wrapper scripts {.options}
1347+## Options for wrapper scripts {.options}
1360−---------------------------
1362`--dump-args`
1349`--dump-args`
@@ -1381,8 +1368,7 @@ Options for wrapper scripts {.options}
1382 pandoc -o foo.html -s
1369 pandoc -o foo.html -s
1384−Exit codes
1371+# Exit codes
1387If pandoc completes successfully, it will return exit code 0.
1373If pandoc completes successfully, it will return exit code 0.
1388Nonzero exit codes have the following meanings:
1374Nonzero exit codes have the following meanings:
@@ -1411,8 +1397,7 @@ Nonzero exit codes have the following meanings:
1411 97 PandocCouldNotFindDataFileError
1397 97 PandocCouldNotFindDataFileError
1412 99 PandocResourceNotFound
1398 99 PandocResourceNotFound
1414−Templates
1400+# Templates
1417When the `-s/--standalone` option is used, pandoc uses a template to
1402When the `-s/--standalone` option is used, pandoc uses a template to
1418add header and footer material that is needed for a self-standing
1403add header and footer material that is needed for a self-standing
@@ -1451,8 +1436,7 @@ changes after each pandoc release.
1452 [pandoc-templates]: https://github.com/jgm/pandoc-templates
1437 [pandoc-templates]: https://github.com/jgm/pandoc-templates
1454−Template syntax
1439+## Template syntax
1457To mark variables and control structures in the template, either
1441To mark variables and control structures in the template, either
1458`$`...`$` or `${`...`}` may be used as delimiters. The styles
1442`$`...`$` or `${`...`}` may be used as delimiters. The styles
@@ -1701,8 +1685,7 @@ $endfor$
1704−Metadata variables
1688+## Metadata variables
1707`title`, `author`, `date`
1690`title`, `author`, `date`
1708: allow identification of basic aspects of the document. Included
1691: allow identification of basic aspects of the document. Included
@@ -1767,8 +1750,7 @@ will include `title`, `author` and `description` as standard document
1767properties and `subtitle` as a custom property when converting to docx,
1750properties and `subtitle` as a custom property when converting to docx,
1768ODT or pptx.
1751ODT or pptx.
1770−Language variables
1753+## Language variables
1774: identifies the main language of the document using IETF language
1756: identifies the main language of the document using IETF language
@@ -1810,8 +1792,7 @@ Language variables
1810[Unicode Bidirectional Algorithm]: http://www.w3.org/International/articles/inline-bidi-markup/uba-basics
1792[Unicode Bidirectional Algorithm]: http://www.w3.org/International/articles/inline-bidi-markup/uba-basics
1811[Language subtag lookup]: https://r12a.github.io/app-subtags/
1793[Language subtag lookup]: https://r12a.github.io/app-subtags/
1813−Variables for HTML slides
1795+## Variables for HTML slides
1814−-------------------------
1816These affect HTML output when [producing slide shows with pandoc].
1797These affect HTML output when [producing slide shows with pandoc].
@@ -1833,8 +1814,7 @@ To turn off boolean flags that default to true in reveal.js, use `0`.
1834[reveal.js configuration options]: https://github.com/hakimel/reveal.js#configuration
1815[reveal.js configuration options]: https://github.com/hakimel/reveal.js#configuration
1836−Variables for Beamer slides
1817+## Variables for Beamer slides
1837−---------------------------
1839These variables change the appearance of PDF slides using [`beamer`].
1819These variables change the appearance of PDF slides using [`beamer`].
@@ -1871,8 +1851,7 @@ These variables change the appearance of PDF slides using [`beamer`].
1871`titlegraphic`
1851`titlegraphic`
1872: image for title slide
1852: image for title slide
1874−Variables for PowerPoint slide shows
1854+## Variables for PowerPoint slide shows
1875−--------------------------------------
1877These variables control the visual aspects of a slide show that are not easily
1856These variables control the visual aspects of a slide show that are not easily
1878controled via templates.
1857controled via templates.
@@ -1880,8 +1859,7 @@ controled via templates.
1880`monofont`
1859`monofont`
1881: font to use for code.
1860: font to use for code.
1883−Variables for LaTeX
1862+## Variables for LaTeX
1886Pandoc uses these variables when [creating a PDF] with a LaTeX engine.
1864Pandoc uses these variables when [creating a PDF] with a LaTeX engine.
@@ -2064,8 +2042,7 @@ These variables function when using BibLaTeX for [citation rendering].
2064[`memoir`]: https://ctan.org/pkg/memoir
2042[`memoir`]: https://ctan.org/pkg/memoir
2065[`report`]: https://ctan.org/pkg/report
2043[`report`]: https://ctan.org/pkg/report
2067−Variables for ConTeXt
2045+## Variables for ConTeXt
2068−---------------------
2070Pandoc uses these variables when [creating a PDF] with ConTeXt.
2047Pandoc uses these variables when [creating a PDF] with ConTeXt.
@@ -2157,8 +2134,7 @@ Pandoc uses these variables when [creating a PDF] with ConTeXt.
2157[`setupinterlinespace`]: https://wiki.contextgarden.net/Command/setupinterlinespace
2134[`setupinterlinespace`]: https://wiki.contextgarden.net/Command/setupinterlinespace
2158[`setuppagenumbering`]: https://wiki.contextgarden.net/Command/setuppagenumbering
2135[`setuppagenumbering`]: https://wiki.contextgarden.net/Command/setuppagenumbering
2160−Variables for `wkhtmltopdf`
2137+## Variables for `wkhtmltopdf`
2161−---------------------------
2163Pandoc uses these variables when [creating a PDF] with [`wkhtmltopdf`].
2139Pandoc uses these variables when [creating a PDF] with [`wkhtmltopdf`].
2164The `--css` option also affects the output.
2140The `--css` option also affects the output.
@@ -2172,8 +2148,7 @@ The `--css` option also affects the output.
2172`papersize`
2148`papersize`
2173: sets the PDF paper size
2149: sets the PDF paper size
2175−Variables for man pages
2151+## Variables for man pages
2176−-----------------------
2178`adjusting`
2153`adjusting`
2179: adjusts text to left (`l`), right (`r`), center (`c`),
2154: adjusts text to left (`l`), right (`r`), center (`c`),
@@ -2191,8 +2166,7 @@ Variables for man pages
2191`section`
2166`section`
2192: section number in man pages
2167: section number in man pages
2194−Variables for ms
2169+## Variables for ms
2197`fontfamily`
2171`fontfamily`
2198: font family (e.g. `T` or `P`)
2172: font family (e.g. `T` or `P`)
@@ -2206,8 +2180,7 @@ Variables for ms
2206`pointsize`
2180`pointsize`
2207: point size (e.g. `10p`)
2181: point size (e.g. `10p`)
2209−Structural variables
2183+## Structural variables
2210−--------------------
2212Pandoc sets these variables automatically in response to [options] or
2185Pandoc sets these variables automatically in response to [options] or
2213document contents; users can also modify them. These vary depending
2186document contents; users can also modify them. These vary depending
@@ -2275,8 +2248,7 @@ on the output format, and include the following:
2276[pandoc-templates]: https://github.com/jgm/pandoc-templates
2249[pandoc-templates]: https://github.com/jgm/pandoc-templates
2278−Extensions
2251+# Extensions
2281The behavior of some of the readers and writers can be adjusted by
2253The behavior of some of the readers and writers can be adjusted by
2282enabling or disabling various extensions.
2254enabling or disabling various extensions.
@@ -2297,8 +2269,7 @@ Note that markdown extensions added to the `ipynb` format
2297affect Markdown cells in Jupyter notebooks (as do command-line
2269affect Markdown cells in Jupyter notebooks (as do command-line
2298options like `--atx-headers`).
2270options like `--atx-headers`).
2300−Typography
2272+## Typography
2303#### Extension: `smart` ####
2274#### Extension: `smart` ####
@@ -2330,8 +2301,7 @@ literally. In writing LaTeX, enabling `smart` tells pandoc
2330to use the ligatures when possible; if `smart` is disabled
2301to use the ligatures when possible; if `smart` is disabled
2331pandoc will use unicode quotation mark and dash characters.
2302pandoc will use unicode quotation mark and dash characters.
2333−Headings and sections
2304+## Headings and sections
2334−---------------------
2336#### Extension: `auto_identifiers` ####
2306#### Extension: `auto_identifiers` ####
@@ -2413,8 +2383,7 @@ GitHub's method. Spaces are converted to dashes (`-`),
2413uppercase characters to lowercase characters, and punctuation
2383uppercase characters to lowercase characters, and punctuation
2414characters other than `-` and `_` are removed.
2384characters other than `-` and `_` are removed.
2416−Math Input
2386+## Math Input
2419The extensions [`tex_math_dollars`](#extension-tex_math_dollars),
2388The extensions [`tex_math_dollars`](#extension-tex_math_dollars),
2420[`tex_math_single_backslash`](#extension-tex_math_single_backslash), and
2389[`tex_math_single_backslash`](#extension-tex_math_single_backslash), and
@@ -2424,8 +2393,7 @@ are described in the section about Pandoc's Markdown.
2424However, they can also be used with HTML input. This is handy for
2393However, they can also be used with HTML input. This is handy for
2425reading web pages formatted using MathJax, for example.
2394reading web pages formatted using MathJax, for example.
2427−Raw HTML/TeX
2396+## Raw HTML/TeX
2430The following extensions (especially how they affect Markdown
2398The following extensions (especially how they affect Markdown
2431input/output) are also described in more detail in their respective
2399input/output) are also described in more detail in their respective
@@ -2475,8 +2443,7 @@ When converting HTML to Markdown, for example, you may want to drop all
2475Analogous to `native_divs` above.
2443Analogous to `native_divs` above.
2478−Literate Haskell support
2446+## Literate Haskell support
2479−------------------------
2481#### Extension: `literate_haskell` ####
2448#### Extension: `literate_haskell` ####
@@ -2537,8 +2504,7 @@ Note that GHC expects the bird tracks in the first column, so indented
2537literate code blocks (e.g. inside an itemized environment) will not be
2504literate code blocks (e.g. inside an itemized environment) will not be
2538picked up by the Haskell compiler.
2505picked up by the Haskell compiler.
2540−Other extensions
2507+## Other extensions
2543#### Extension: `empty_paragraphs` ####
2509#### Extension: `empty_paragraphs` ####
@@ -2593,8 +2559,7 @@ Natural tables allow more fine-grained global customization but come
2593at a performance penalty compared to extreme tables.
2559at a performance penalty compared to extreme tables.
2596−Pandoc's Markdown
2562+# Pandoc's Markdown
2599Pandoc understands an extended and slightly revised version of
2564Pandoc understands an extended and slightly revised version of
2600John Gruber's [Markdown] syntax. This document explains the syntax,
2565John Gruber's [Markdown] syntax. This document explains the syntax,
@@ -2604,8 +2569,7 @@ of `markdown`. Extensions can be enabled or disabled to specify the
2604behavior more granularly. They are described in the following. See also
2569behavior more granularly. They are described in the following. See also
2605[Extensions] above, for extensions that work also on other formats.
2570[Extensions] above, for extensions that work also on other formats.
2607−Philosophy
2572+## Philosophy
2610Markdown is designed to be easy to write, and, even more importantly,
2574Markdown is designed to be easy to write, and, even more importantly,
2611easy to read:
2575easy to read:
@@ -2626,8 +2590,7 @@ it discourages it, and provides other, non-HTMLish ways of representing
2626important document elements like definition lists, tables, mathematics, and
2590important document elements like definition lists, tables, mathematics, and
2627footnotes.
2591footnotes.
2629−Paragraphs
2593+## Paragraphs
2632A paragraph is one or more lines of text followed by one or more blank lines.
2595A paragraph is one or more lines of text followed by one or more blank lines.
2633Newlines are treated as spaces, so you can reflow your paragraphs as you like.
2596Newlines are treated as spaces, so you can reflow your paragraphs as you like.
@@ -2640,8 +2603,7 @@ Note: in multiline and grid table cells, this is the only way
2640to create a hard line break, since trailing spaces in the cells
2603to create a hard line break, since trailing spaces in the cells
2641are ignored.
2604are ignored.
2643−Headings
2606+## Headings
2646There are two kinds of headings: Setext and ATX.
2608There are two kinds of headings: Setext and ATX.
@@ -2772,8 +2734,7 @@ link will point to `bar`, not to `#foo`:
2773 See [foo]
2735 See [foo]
2775−Block quotations
2737+## Block quotations
2778Markdown uses email conventions for quoting blocks of text.
2739Markdown uses email conventions for quoting blocks of text.
2779A block quotation is one or more paragraphs or other block elements
2740A block quotation is one or more paragraphs or other block elements
@@ -2823,8 +2784,7 @@ not produce a nested block quote in pandoc:
2823 >> Nested.
2784 >> Nested.
2826−Verbatim (code) blocks
2787+## Verbatim (code) blocks
2827−----------------------
2829### Indented code blocks ###
2789### Indented code blocks ###
@@ -2930,8 +2890,7 @@ To set the highlighting style, use `--highlight-style`.
2930For more information on highlighting, see [Syntax highlighting],
2890For more information on highlighting, see [Syntax highlighting],
2933−Line blocks
2893+## Line blocks
2936#### Extension: `line_blocks` ####
2895#### Extension: `line_blocks` ####
@@ -2959,8 +2918,7 @@ line must begin with a space.
2960This syntax is borrowed from [reStructuredText].
2919This syntax is borrowed from [reStructuredText].
2965### Bullet lists ###
2923### Bullet lists ###
@@ -3291,8 +3249,7 @@ of one big list:
3294−Horizontal rules
3252+## Horizontal rules
3297A line containing a row of three or more `*`, `-`, or `_` characters
3254A line containing a row of three or more `*`, `-`, or `_` characters
3298(optionally separated by spaces) produces a horizontal rule:
3255(optionally separated by spaces) produces a horizontal rule:
@@ -3302,8 +3259,7 @@ A line containing a row of three or more `*`, `-`, or `_` characters
3302 ---------------
3259 ---------------
3305−Tables
3262+## Tables
3308Four kinds of tables may be used. The first three kinds presuppose the use of
3264Four kinds of tables may be used. The first three kinds presuppose the use of
3309a fixed-width font, such as Courier. The fourth kind can be used with
3265a fixed-width font, such as Courier. The fourth kind can be used with
@@ -3517,8 +3473,7 @@ you'll need to add colons as above.
3518[PHP Markdown Extra tables]: https://michelf.ca/projects/php-markdown/extra/#table
3474[PHP Markdown Extra tables]: https://michelf.ca/projects/php-markdown/extra/#table
3520−Metadata blocks
3476+## Metadata blocks
3523#### Extension: `pandoc_title_block` ####
3478#### Extension: `pandoc_title_block` ####
@@ -3694,8 +3649,7 @@ will be interpreted as markdown. For example:
3694 \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
3649 \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
3697−Backslash escapes
3652+## Backslash escapes
3700#### Extension: `all_symbols_escapable` ####
3654#### Extension: `all_symbols_escapable` ####
@@ -3733,8 +3687,7 @@ two trailing spaces on a line.
3734Backslash escapes do not work in verbatim contexts.
3688Backslash escapes do not work in verbatim contexts.
3736−Inline formatting
3690+## Inline formatting
3739### Emphasis ###
3692### Emphasis ###
@@ -3836,8 +3789,7 @@ For compatibility with other Markdown flavors, CSS is also supported:
3836This will work in all output formats that support small caps.
3789This will work in all output formats that support small caps.
3842#### Extension: `tex_math_dollars` ####
3794#### Extension: `tex_math_dollars` ####
@@ -3912,8 +3864,7 @@ HTML, Slidy, DZSlides, S5, EPUB
3913[interpreted text role `:math:`]: http://docutils.sourceforge.net/docs/ref/rst/roles.html#math
3865[interpreted text role `:math:`]: http://docutils.sourceforge.net/docs/ref/rst/roles.html#math
3915−Raw HTML
3867+## Raw HTML
3918#### Extension: `raw_html` ####
3869#### Extension: `raw_html` ####
@@ -4059,8 +4010,7 @@ example, to use a raw attribute with a backtick code block,
4060The raw attribute cannot be combined with regular attributes.
4011The raw attribute cannot be combined with regular attributes.
4062−LaTeX macros
4013+## LaTeX macros
4065#### Extension: `latex_macros` ####
4015#### Extension: `latex_macros` ####
@@ -4084,8 +4034,7 @@ you are targeting LaTeX or PDF.
4084Whether or not `latex_macros` is enabled, the macro definitions
4034Whether or not `latex_macros` is enabled, the macro definitions
4085will still be passed through as raw LaTeX.
4035will still be passed through as raw LaTeX.
4090Markdown allows links to be specified in several ways.
4039Markdown allows links to be specified in several ways.
@@ -4193,8 +4142,7 @@ or
4193Internal links are currently supported for HTML formats (including
4142Internal links are currently supported for HTML formats (including
4194HTML slide shows and EPUB), LaTeX, and ConTeXt.
4143HTML slide shows and EPUB), LaTeX, and ConTeXt.
4196−Images
4145+## Images
4199A link immediately preceded by a `!` will be treated as an image.
4147A link immediately preceded by a `!` will be treated as an image.
4200The link text will be used as the image's alt text:
4148The link text will be used as the image's alt text:
@@ -4274,8 +4222,7 @@ For example:
4274 is to look at the image resolution and the dpi metadata embedded in
4222 is to look at the image resolution and the dpi metadata embedded in
4275 the image file.
4223 the image file.
4277−Divs and Spans
4225+## Divs and Spans
4280Using the `native_divs` and `native_spans` extensions
4227Using the `native_divs` and `native_spans` extensions
4281(see [above][Extension: `native_divs`]), HTML syntax can
4228(see [above][Extension: `native_divs`]), HTML syntax can
@@ -4331,8 +4278,7 @@ followed immediately by attributes:
4332 [This is *some text*]{.class key="val"}
4279 [This is *some text*]{.class key="val"}
4334−Footnotes
4281+## Footnotes
4337#### Extension: `footnotes` ####
4283#### Extension: `footnotes` ####
@@ -4378,8 +4324,7 @@ they cannot contain multiple paragraphs). The syntax is as follows:
4379Inline and regular footnotes may be mixed freely.
4325Inline and regular footnotes may be mixed freely.
4381−Citations
4327+## Citations
4384#### Extension: `citations` ####
4329#### Extension: `citations` ####
@@ -4591,8 +4536,7 @@ For more information, see the [pandoc-citeproc man page].
4591[CSL locale files]: https://github.com/citation-style-language/locales
4536[CSL locale files]: https://github.com/citation-style-language/locales
4592[pandoc-citeproc man page]: https://github.com/jgm/pandoc-citeproc/blob/master/man/pandoc-citeproc.1.md
4537[pandoc-citeproc man page]: https://github.com/jgm/pandoc-citeproc/blob/master/man/pandoc-citeproc.1.md
4594−Non-pandoc extensions
4539+## Non-pandoc extensions
4595−---------------------
4597The following Markdown syntax extensions are not enabled by default
4541The following Markdown syntax extensions are not enabled by default
4598in pandoc, but may be enabled by adding `+EXTENSION` to the format
4542in pandoc, but may be enabled by adding `+EXTENSION` to the format
@@ -4754,8 +4698,7 @@ for regular emphasis, add extra blank space around headings.
4755 [Project Gutenberg]: https://www.gutenberg.org
4699 [Project Gutenberg]: https://www.gutenberg.org
4757−Markdown variants
4701+## Markdown variants
4760In addition to pandoc's extended Markdown, the following Markdown
4703In addition to pandoc's extended Markdown, the following Markdown
4761variants are supported:
4704variants are supported:
@@ -4806,8 +4749,7 @@ only affects `gfm` output, not input.
4806 `lists_without_preceding_blankline`.
4749 `lists_without_preceding_blankline`.
4809−Producing slide shows with pandoc
4752+# Producing slide shows with pandoc
4810−=================================
4812You can use pandoc to produce an HTML + JavaScript slide presentation
4754You can use pandoc to produce an HTML + JavaScript slide presentation
4813that can be viewed via a web browser. There are five ways to do this,
4755that can be viewed via a web browser. There are five ways to do this,
@@ -4879,8 +4821,7 @@ To produce a Powerpoint slide show, type
4880 pandoc habits.txt -o habits.pptx
4822 pandoc habits.txt -o habits.pptx
4882−Structuring the slide show
4824+## Structuring the slide show
4883−--------------------------
4885By default, the *slide level* is the highest heading level in
4826By default, the *slide level* is the highest heading level in
4886the hierarchy that is followed immediately by content, and not another
4827the hierarchy that is followed immediately by content, and not another
@@ -4921,8 +4862,7 @@ layout will be produced, with level-1 headings building horizontally
4921and level-2 headings building vertically. It is not recommended that
4862and level-2 headings building vertically. It is not recommended that
4922you use deeper nesting of section levels with reveal.js.
4863you use deeper nesting of section levels with reveal.js.
4924−Incremental lists
4865+## Incremental lists
4927By default, these writers produce lists that display "all at once."
4867By default, these writers produce lists that display "all at once."
4928If you want your lists to display incrementally (one item at a time),
4868If you want your lists to display incrementally (one item at a time),
@@ -4963,8 +4903,7 @@ in a single document.
4963Note: Neither the `-i/--incremental` option nor any of the
4903Note: Neither the `-i/--incremental` option nor any of the
4964methods described here currently works for PowerPoint output.
4904methods described here currently works for PowerPoint output.
4966−Inserting pauses
4906+## Inserting pauses
4969You can add "pauses" within a slide by including a paragraph containing
4908You can add "pauses" within a slide by including a paragraph containing
4970three dots, separated by spaces:
4909three dots, separated by spaces:
@@ -4979,8 +4918,7 @@ three dots, separated by spaces:
4980Note: this feature is not yet implemented for PowerPoint output.
4919Note: this feature is not yet implemented for PowerPoint output.
4982−Styling the slides
4921+## Styling the slides
4985You can change the style of HTML slides by putting customized CSS files
4923You can change the style of HTML slides by putting customized CSS files
4986in `$DATADIR/s5/default` (for S5), `$DATADIR/slidy` (for Slidy),
4924in `$DATADIR/s5/default` (for S5), `$DATADIR/slidy` (for Slidy),
@@ -5015,8 +4953,7 @@ bibliographies:
5016 # References {.allowframebreaks}
4954 # References {.allowframebreaks}
5018−Speaker notes
4956+## Speaker notes
5021Speaker notes are supported in reveal.js and PowerPoint (pptx)
4958Speaker notes are supported in reveal.js and PowerPoint (pptx)
5022output. You can add notes to your Markdown document thus:
4959output. You can add notes to your Markdown document thus:
@@ -5037,8 +4974,7 @@ in handouts and presenter view.
5037Notes are not yet supported for other slide formats, but the notes
4974Notes are not yet supported for other slide formats, but the notes
5038will not appear on the slides themselves.
4975will not appear on the slides themselves.
5040−Columns
4977+## Columns
5043To put material in side by side columns, you can use a native
4979To put material in side by side columns, you can use a native
5044div container with class `columns`, containing two or more div
4980div container with class `columns`, containing two or more div
@@ -5053,8 +4989,7 @@ containers with class `column` and a `width` attribute:
5054 ::::::::::::::
4990 ::::::::::::::
5056−Frame attributes in beamer
4992+## Frame attributes in beamer
5057−--------------------------
5059Sometimes it is necessary to add the LaTeX `[fragile]` option to
4994Sometimes it is necessary to add the LaTeX `[fragile]` option to
5060a frame in beamer (for example, when using the `minted` environment).
4995a frame in beamer (for example, when using the `minted` environment).
@@ -5068,8 +5003,7 @@ the [Beamer User's Guide] may also be used: `allowdisplaybreaks`,
5068`allowframebreaks`, `b`, `c`, `t`, `environment`, `label`, `plain`,
5003`allowframebreaks`, `b`, `c`, `t`, `environment`, `label`, `plain`,
5069`shrink`, `standout`, `noframenumbering`.
5004`shrink`, `standout`, `noframenumbering`.
5071−Background in reveal.js and beamer
5006+## Background in reveal.js and beamer
5072−----------------------------------
5074Background images can be added to self-contained reveal.js slideshows and
5008Background images can be added to self-contained reveal.js slideshows and
5075to beamer slideshows.
5009to beamer slideshows.
@@ -5116,11 +5050,9 @@ Slide 1 has background_image.png as its background.
5116Slide 2 has a special image for its background, even though the heading has no content.
5050Slide 2 has a special image for its background, even though the heading has no content.
5119−Creating EPUBs with pandoc
5053+# Creating EPUBs with pandoc
5120−==========================
5122−EPUB Metadata
5055+## EPUB Metadata
5125EPUB metadata may be specified using the `--epub-metadata` option, but
5057EPUB metadata may be specified using the `--epub-metadata` option, but
5126if the source document is Markdown, it is better to use a [YAML metadata
5058if the source document is Markdown, it is better to use a [YAML metadata
@@ -5222,8 +5154,7 @@ The following fields are recognized:
5222[MARC relators]: http://loc.gov/marc/relators/relaterm.html
5154[MARC relators]: http://loc.gov/marc/relators/relaterm.html
5223[`spine` element]: http://idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem
5155[`spine` element]: http://idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem
5225−The `epub:type` attribute
5157+## The `epub:type` attribute
5226−-------------------------
5228For `epub3` output, you can mark up the heading that corresponds to an EPUB
5159For `epub3` output, you can mark up the heading that corresponds to an EPUB
5229chapter using the [`epub:type` attribute][epub-type]. For example, to set
5160chapter using the [`epub:type` attribute][epub-type]. For example, to set
@@ -5269,8 +5200,7 @@ index backmatter
5270[epub-type]: http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-epub-type-attribute
5201[epub-type]: http://www.idpf.org/epub/31/spec/epub-contentdocs.html#sec-epub-type-attribute
5272−Linked media
5203+## Linked media
5275By default, pandoc will download media referenced from any `<img>`, `<audio>`,
5205By default, pandoc will download media referenced from any `<img>`, `<audio>`,
5276`<video>` or `<source>` element present in the generated EPUB,
5206`<video>` or `<source>` element present in the generated EPUB,
@@ -5285,8 +5215,7 @@ with the `src` attribute. For example:
5285 </source>
5215 </source>
5286 </audio>
5216 </audio>
5288−Creating Jupyter notebooks with pandoc
5218+# Creating Jupyter notebooks with pandoc
5289−======================================
5291When creating a [Jupyter notebook], pandoc will try to infer the
5220When creating a [Jupyter notebook], pandoc will try to infer the
5292notebook structure. Code blocks with the class `code` will be
5221notebook structure. Code blocks with the class `code` will be
@@ -5411,8 +5340,7 @@ soft line breaks in Markdown cells; `--atx-headers` will
5411cause ATX-style headings to be used; and `--preserve-tabs` will
5340cause ATX-style headings to be used; and `--preserve-tabs` will
5412prevent tabs from being turned to spaces.
5341prevent tabs from being turned to spaces.
5414−Syntax highlighting
5343+# Syntax highlighting
5417Pandoc will automatically highlight syntax in [fenced code blocks] that
5345Pandoc will automatically highlight syntax in [fenced code blocks] that
5418are marked with a language name. The Haskell library [skylighting] is
5346are marked with a language name. The Haskell library [skylighting] is
@@ -5448,13 +5376,11 @@ To disable highlighting, use the `--no-highlight` option.
5449[skylighting]: https://github.com/jgm/skylighting
5377[skylighting]: https://github.com/jgm/skylighting
5451−Custom Styles
5379+# Custom Styles
5454Custom styles can be used in the docx and ICML formats.
5381Custom styles can be used in the docx and ICML formats.
5456−Output
5383+## Output
5459By default, pandoc's docx and ICML output applies a predefined set of styles
5385By default, pandoc's docx and ICML output applies a predefined set of styles
5460for blocks such as paragraphs and block quotes, and uses largely default
5386for blocks such as paragraphs and block quotes, and uses largely default
@@ -5501,8 +5427,7 @@ custom styles to work.
5502[pandoc filters]: http://pandoc.org/filters.html
5428[pandoc filters]: http://pandoc.org/filters.html
5507The docx reader, by default, only reads those styles that it can
5432The docx reader, by default, only reads those styles that it can
5508convert into pandoc elements, either by direct conversion or
5433convert into pandoc elements, either by direct conversion or
@@ -5549,8 +5474,7 @@ With these custom styles, you can use your input document as a
5549reference-doc while creating docx output (see below), and maintain the
5474reference-doc while creating docx output (see below), and maintain the
5550same styles in your input and output files.
5475same styles in your input and output files.
5552−Custom writers
5477+# Custom writers
5555Pandoc can be extended with custom writers written in [lua]. (Pandoc
5479Pandoc can be extended with custom writers written in [lua]. (Pandoc
5556includes a lua interpreter, so lua need not be installed separately.)
5480includes a lua interpreter, so lua need not be installed separately.)
@@ -5568,8 +5492,7 @@ which you can modify according to your needs, do
5569[lua]: http://www.lua.org
5493[lua]: http://www.lua.org
5571−A note on security
5495+# A note on security
5574If you use pandoc to convert user-contributed content in a web
5497If you use pandoc to convert user-contributed content in a web
5575application, here are some things to keep in mind:
5498application, here are some things to keep in mind:
@@ -5601,8 +5524,7 @@ application, here are some things to keep in mind:
5601 headings, spans, and code blocks. To be safe, you should
5524 headings, spans, and code blocks. To be safe, you should
5602 run all the generated HTML through an HTML sanitizer.
5525 run all the generated HTML through an HTML sanitizer.
5604−Authors
5527+# Authors
5607Copyright 2006--2019 John MacFarlane (jgm@berkeley.edu). Released
5529Copyright 2006--2019 John MacFarlane (jgm@berkeley.edu). Released
5608under the [GPL], version 2 or greater. This software carries no
5530under the [GPL], version 2 or greater. This software carries no