@@ -284,16 +284,9 @@ General options
284284 (`markdown_github` provides deprecated and less accurate support
285285 for Github-Flavored Markdown; please use `gfm` instead, unless you
286286 need to use extensions other than `smart`.)
287− If `+lhs` is appended to `markdown`, `rst`, `latex`, or
288− `html`, the input will be treated as literate Haskell source: see
289− [Literate Haskell support], below. Markdown
290− syntax extensions can be individually enabled or disabled by
291− appending `+EXTENSION` or `-EXTENSION` to the format name. So, for
292− example, `markdown_strict+footnotes+definition_lists` is strict
293− Markdown with footnotes and definition lists enabled, and
294− `markdown-pipe_tables+hard_line_breaks` is pandoc's Markdown
295− without pipe tables and with hard line breaks. See [Pandoc's
296− Markdown], below, for a list of extensions and
287+ Extensions can be individually enabled or disabled by
288+ appending `+EXTENSION` or `-EXTENSION` to the format name.
289+ See [Extensions] below, for a list of extensions and
297290 their names. See `--list-input-formats` and `--list-extensions`,
298291 below.
299292
@@ -327,13 +320,10 @@ General options
327320 unless you use extensions that do not work with `gfm`.) Note that
328321 `odt`, `epub`, and `epub3` output will not be directed to
329322 *stdout*; an output filename must be specified using the
330− `-o/--output` option. If `+lhs` is appended to `markdown`, `rst`,
331− `latex`, `beamer`, `html4`, or `html5`, the output will be
332− rendered as literate Haskell source: see [Literate Haskell
333− support], below. Markdown syntax extensions can be individually
334− enabled or disabled by appending `+EXTENSION` or `-EXTENSION` to
335− the format name, as described above under `-f`. See
336− `--list-output-formats` and `--list-extensions`, below.
323+ `-o/--output` option. Extensions can be individually enabled or
324+ disabled by appending `+EXTENSION` or `-EXTENSION` to the format
325+ name. See [Extensions] below, for a list of extensions and their
326+ names. See `--list-output-formats` and `--list-extensions`, below.
337327
338328`-o` *FILE*, `--output=`*FILE*
339329
@@ -1698,6 +1688,269 @@ will be treated as a comment and ignored.
16981688
16991689[pandoc-templates]: https://github.com/jgm/pandoc-templates
17001690
1691+Extensions
1692+==========
1693+
1694+The behavior of some of the readers and writers can be adjusted by
1695+enabling or disabling various extensions.
1696+
1697+An extension can be enabled by adding `+EXTENSION`
1698+to the format name and disabled by adding `-EXTENSION`. For example,
1699+`--from markdown_strict+footnotes` is strict Markdown with footnotes
1700+enabled, while `--from markdown-footnotes-pipe_tables` is pandoc's
1701+Markdown without footnotes or pipe tables.
1702+
1703+The markdown reader and writer make by far the most use of extensions.
1704+Extensions only used by them are therefore covered in the
1705+section [Pandoc's Markdown] below (See [Markdown variants] for
1706+`commonmark` and `gfm`.) In the following, extensions that also work
1707+for other formats are covered.
1708+
1709+Typography
1710+----------
1711+
1712+#### Extension: `smart` ####
1713+
1714+Interpret straight quotes as curly quotes, `---` as em-dashes,
1715+`--` as en-dashes, and `...` as ellipses. Nonbreaking spaces are
1716+inserted after certain abbreviations, such as "Mr."
1717+
1718+This extension can be enabled/disabled for the following formats:
1719+
1720+input formats
1721+: `markdown`, `commonmark`, `latex`, `mediawiki`, `org`, `rst`, `twiki`
1722+
1723+output formats
1724+: `markdown`, `latex`, `context`, `rst`
1725+
1726+enabled by default in
1727+: `markdown`, `latex`, `context` (both input and output)
1728+
1729+Note: If you are *writing* Markdown, then the `smart` extension
1730+has the reverse effect: what would have been curly quotes comes
1731+out straight.
1732+
1733+In LaTeX, `smart` means to use the standard TeX ligatures
1734+for quotation marks (` `` ` and ` '' ` for double quotes,
1735+`` ` `` and `` ' `` for single quotes) and dashes (`--` for
1736+en-dash and `---` for em-dash). If `smart` is disabled,
1737+then in reading LaTeX pandoc will parse these characters
1738+literally. In writing LaTeX, enabling `smart` tells pandoc
1739+to use the ligatures when possible; if `smart` is disabled
1740+pandoc will use unicode quotation mark and dash characters.
1741+
1742+Headers and sections
1743+--------------------
1744+
1745+#### Extension: `auto_identifiers` ####
1746+
1747+A header without an explicitly specified identifier will be
1748+automatically assigned a unique identifier based on the header text.
1749+
1750+This extension can be enabled/disabled for the following formats:
1751+
1752+input formats
1753+: `markdown`, `latex`, `rst`, `mediawiki`, `textile`
1754+
1755+output formats
1756+: `markdown`, `muse`
1757+
1758+enabled by default in
1759+: `markdown`, `muse`
1760+
1761+The algorithm used to derive the identifier from the header text is:
1762+
1763+ - Remove all formatting, links, etc.
1764+ - Remove all footnotes.
1765+ - Remove all punctuation, except underscores, hyphens, and periods.
1766+ - Replace all spaces and newlines with hyphens.
1767+ - Convert all alphabetic characters to lowercase.
1768+ - Remove everything up to the first letter (identifiers may
1769+ not begin with a number or punctuation mark).
1770+ - If nothing is left after this, use the identifier `section`.
1771+
1772+Thus, for example,
1773+
1774+ Header Identifier
1775+ ------------------------------- ----------------------------
1776+ `Header identifiers in HTML` `header-identifiers-in-html`
1777+ `*Dogs*?--in *my* house?` `dogs--in-my-house`
1778+ `[HTML], [S5], or [RTF]?` `html-s5-or-rtf`
1779+ `3. Applications` `applications`
1780+ `33` `section`
1781+
1782+These rules should, in most cases, allow one to determine the identifier
1783+from the header text. The exception is when several headers have the
1784+same text; in this case, the first will get an identifier as described
1785+above; the second will get the same identifier with `-1` appended; the
1786+third with `-2`; and so on.
1787+
1788+These identifiers are used to provide link targets in the table of
1789+contents generated by the `--toc|--table-of-contents` option. They
1790+also make it easy to provide links from one section of a document to
1791+another. A link to this section, for example, might look like this:
1792+
1793+ See the section on
1794+ [header identifiers](#header-identifiers-in-html-latex-and-context).
1795+
1796+Note, however, that this method of providing links to sections works
1797+only in HTML, LaTeX, and ConTeXt formats.
1798+
1799+If the `--section-divs` option is specified, then each section will
1800+be wrapped in a `div` (or a `section`, if `html5` was specified),
1801+and the identifier will be attached to the enclosing `<div>`
1802+(or `<section>`) tag rather than the header itself. This allows entire
1803+sections to be manipulated using JavaScript or treated differently in
1804+CSS.
1805+
1806+#### Extension: `ascii_identifiers` ####
1807+
1808+Causes the identifiers produced by `auto_identifiers` to be pure ASCII.
1809+Accents are stripped off of accented Latin letters, and non-Latin
1810+letters are omitted.
1811+
1812+Math Input
1813+----------
1814+
1815+The extensions [`tex_math_dollars`](#extension-tex_math_dollars),
1816+[`tex_math_single_backslash`](#extension-tex_math_single_backslash), and
1817+[`tex_math_double_backslash`](#extension-tex_math_double_backslash)
1818+are described in the section about Pandoc's Markdown.
1819+
1820+However, they can also be used with HTML input. This is handy for
1821+reading web pages formatted using MathJax, for example.
1822+
1823+Raw HTML/TeX
1824+------------
1825+
1826+The following extensions (especially how they affect Markdown
1827+input/output) are also described in more detail in their respective
1828+sections of [Pandoc's Markdown].
1829+
1830+#### [Extension: `raw_html`] {#raw_html}
1831+
1832+When converting from HTML, parse elements to raw HTML which are not
1833+representable in pandoc's AST.
1834+By default, this is disabled for HTML input.
1835+
1836+#### [Extension: `raw_tex`] {#raw_tex}
1837+
1838+Allows raw LaTeX, TeX, and ConTeXt to be included in a document.
1839+
1840+This extension can be enabled/disabled for the following formats
1841+(in addition to `markdown`):
1842+
1843+input formats
1844+: `latex`, `org`, `textile`
1845+
1846+output formats
1847+: `textile`
1848+
1849+#### [Extension: `native_divs`] {#native_divs}
1850+
1851+This extension is enabled by default for HTML input. This means that
1852+`div`s are parsed to pandoc native elements. (Alternatively, you
1853+can parse them to raw HTML using `-f html-native_divs+raw_html`.)
1854+
1855+When converting HTML to Markdown, for example, you may want to drop all
1856+`div`s and `span`s:
1857+
1858+ pandoc -f html-native_divs-native_spans -t markdown
1859+
1860+#### [Extension: `native_spans`] {#native_spans}
1861+
1862+Analogous to `native_divs` above.
1863+
1864+
1865+Literate Haskell support
1866+------------------------
1867+
1868+#### Extension: `literate_haskell` ####
1869+
1870+Treat the document as literate Haskell source.
1871+
1872+This extension can be enabled/disabled for the following formats:
1873+
1874+input formats
1875+: `markdown`, `rst`, `latex`
1876+
1877+output formats
1878+: `markdown`, `rst`, `latex`, `html`
1879+
1880+If you append `+lhs` (or `+literate_haskell`) to one of the formats
1881+above, pandoc will treat the document as literate Haskell source.
1882+This means that
1883+
1884+ - In Markdown input, "bird track" sections will be parsed as Haskell
1885+ code rather than block quotations. Text between `\begin{code}`
1886+ and `\end{code}` will also be treated as Haskell code. For
1887+ ATX-style headers the character '=' will be used instead of '#'.
1888+
1889+ - In Markdown output, code blocks with classes `haskell` and `literate`
1890+ will be rendered using bird tracks, and block quotations will be
1891+ indented one space, so they will not be treated as Haskell code.
1892+ In addition, headers will be rendered setext-style (with underlines)
1893+ rather than ATX-style (with '#' characters). (This is because ghc
1894+ treats '#' characters in column 1 as introducing line numbers.)
1895+
1896+ - In restructured text input, "bird track" sections will be parsed
1897+ as Haskell code.
1898+
1899+ - In restructured text output, code blocks with class `haskell` will
1900+ be rendered using bird tracks.
1901+
1902+ - In LaTeX input, text in `code` environments will be parsed as
1903+ Haskell code.
1904+
1905+ - In LaTeX output, code blocks with class `haskell` will be rendered
1906+ inside `code` environments.
1907+
1908+ - In HTML output, code blocks with class `haskell` will be rendered
1909+ with class `literatehaskell` and bird tracks.
1910+
1911+Examples:
1912+
1913+ pandoc -f markdown+lhs -t html
1914+
1915+reads literate Haskell source formatted with Markdown conventions and writes
1916+ordinary HTML (without bird tracks).
1917+
1918+ pandoc -f markdown+lhs -t html+lhs
1919+
1920+writes HTML with the Haskell code in bird tracks, so it can be copied
1921+and pasted as literate Haskell source.
1922+
1923+Note that GHC expects the bird tracks in the first column, so indentend literate
1924+code blocks (e.g. inside an itemized environment) will not be picked up by the
1925+Haskell compiler.
1926+
1927+Other extensions
1928+----------------
1929+
1930+#### Extension: `empty_paragraphs` ####
1931+
1932+Allows empty paragraphs. By default empty paragraphs are
1933+omitted.
1934+
1935+This extension can be enabled/disabled for the following formats:
1936+
1937+input formats
1938+: `docx`, `html`
1939+
1940+output formats
1941+: `markdown`, `docx`, `odt`, `opendocument`, `html`
1942+
1943+#### Extension: `amuse` ####
1944+
1945+In the `muse` input format, this enables Text::Amuse
1946+extensions to Emacs Muse markup.
1947+
1948+#### Extension: `citations` {#org-citations}
1949+
1950+Some aspects of [Pandoc's Markdown citation syntax](#citations) are also accepted
1951+in `org` input.
1952+
1953+
17011954Pandoc's Markdown
17021955=================
17031956
@@ -1705,11 +1958,9 @@ Pandoc understands an extended and slightly revised version of
17051958John Gruber's [Markdown] syntax. This document explains the syntax,
17061959noting differences from standard Markdown. Except where noted, these
17071960differences can be suppressed by using the `markdown_strict` format instead
1708−of `markdown`. An extensions can be enabled by adding `+EXTENSION`
1709−to the format name and disabled by adding `-EXTENSION`. For example,
1710−`markdown_strict+footnotes` is strict Markdown with footnotes
1711−enabled, while `markdown-footnotes-pipe_tables` is pandoc's
1712−Markdown without footnotes or pipe tables.
1961+of `markdown`. Extensions can be enabled or disabled to specify the
1962+behavior more granularly. They are described in the following. See also
1963+[Extensions] above, for extensions that work also on other formats.
17131964
17141965Philosophy
17151966----------
@@ -1801,6 +2052,8 @@ pandoc does require the space.
18012052
18022053### Header identifiers ###
18032054
2055+See also the [`auto_identifiers` extension](#extension-auto_identifiers) above.
2056+
18042057#### Extension: `header_attributes` ####
18052058
18062059Headers can be assigned attributes using this syntax at the end
@@ -1837,55 +2090,6 @@ is just the same as
18372090
18382091 # My header {.unnumbered}
18392092
1840−#### Extension: `auto_identifiers` ####
1841−
1842−A header without an explicitly specified identifier will be
1843−automatically assigned a unique identifier based on the header text.
1844−To derive the identifier from the header text,
1845−
1846− - Remove all formatting, links, etc.
1847− - Remove all footnotes.
1848− - Remove all punctuation, except underscores, hyphens, and periods.
1849− - Replace all spaces and newlines with hyphens.
1850− - Convert all alphabetic characters to lowercase.
1851− - Remove everything up to the first letter (identifiers may
1852− not begin with a number or punctuation mark).
1853− - If nothing is left after this, use the identifier `section`.
1854−
1855−Thus, for example,
1856−
1857− Header Identifier
1858− ------------------------------- ----------------------------
1859− `Header identifiers in HTML` `header-identifiers-in-html`
1860− `*Dogs*?--in *my* house?` `dogs--in-my-house`
1861− `[HTML], [S5], or [RTF]?` `html-s5-or-rtf`
1862− `3. Applications` `applications`
1863− `33` `section`
1864−
1865−These rules should, in most cases, allow one to determine the identifier
1866−from the header text. The exception is when several headers have the
1867−same text; in this case, the first will get an identifier as described
1868−above; the second will get the same identifier with `-1` appended; the
1869−third with `-2`; and so on.
1870−
1871−These identifiers are used to provide link targets in the table of
1872−contents generated by the `--toc|--table-of-contents` option. They
1873−also make it easy to provide links from one section of a document to
1874−another. A link to this section, for example, might look like this:
1875−
1876− See the section on
1877− [header identifiers](#header-identifiers-in-html-latex-and-context).
1878−
1879−Note, however, that this method of providing links to sections works
1880−only in HTML, LaTeX, and ConTeXt formats.
1881−
1882−If the `--section-divs` option is specified, then each section will
1883−be wrapped in a `div` (or a `section`, if `html5` was specified),
1884−and the identifier will be attached to the enclosing `<div>`
1885−(or `<section>`) tag rather than the header itself. This allows entire
1886−sections to be manipulated using JavaScript or treated differently in
1887−CSS.
1888−
18892093#### Extension: `implicit_header_references` ####
18902094
18912095Pandoc behaves as if reference links have been defined for each header.
@@ -3028,8 +3232,6 @@ HTML, Slidy, DZSlides, S5, EPUB
30283232 command-line options selected. Therefore see [Math rendering in HTML]
30293233 above.
30303234
3031−This extension can be used with both `markdown` and `html` input.
3032−
30333235[interpreted text role `:math:`]: http://docutils.sourceforge.net/docs/ref/rst/roles.html#math
30343236
30353237Raw HTML
@@ -3457,33 +3659,6 @@ they cannot contain multiple paragraphs). The syntax is as follows:
34573659
34583660Inline and regular footnotes may be mixed freely.
34593661
3460−Typography
3461−----------
3462−
3463−#### Extension: `smart` ####
3464−
3465−Interpret straight quotes as curly quotes, `---` as em-dashes,
3466−`--` as en-dashes, and `...` as ellipses. Nonbreaking spaces are
3467−inserted after certain abbreviations, such as "Mr." This
3468−option currently affects the input formats `markdown`,
3469−`commonmark`, `latex`, `mediawiki`, `org`, `rst`, and `twiki`,
3470−and the output formats `markdown`, `latex`, and `context`.
3471−It is enabled by default for `markdown`, `latex`, and `context`
3472−(in both input and output).
3473−
3474−Note: If you are *writing* Markdown, then the `smart` extension
3475−has the reverse effect: what would have been curly quotes comes
3476−out straight.
3477−
3478−In LaTeX, `smart` means to use the standard TeX ligatures
3479−for quotation marks (` `` ` and ` '' ` for double quotes,
3480−`` ` `` and `` ' `` for single quotes) and dashes (`--` for
3481−en-dash and `---` for em-dash). If `smart` is disabled,
3482−then in reading LaTeX pandoc will parse these characters
3483−literally. In writing LaTeX, enabling `smart` tells pandoc
3484−to use the ligatures when possible; if `smart` is disabled
3485−pandoc will use unicode quotation mark and dash characters.
3486−
34873662Citations
34883663---------
34893664
@@ -3746,8 +3921,6 @@ TeX math, and anything between `\[` and `\]` to be interpreted
37463921as display TeX math. Note: a drawback of this extension is that
37473922it precludes escaping `(` and `[`.
37483923
3749−This extension can be used with both `markdown` and `html` input.
3750−
37513924#### Extension: `tex_math_double_backslash` ####
37523925
37533926Causes anything between `\\(` and `\\)` to be interpreted as inline
@@ -3790,12 +3963,6 @@ simply skipped (as opposed to being parsed as paragraphs).
37903963Makes all absolute URIs into links, even when not surrounded by
37913964pointy braces `<...>`.
37923965
3793−#### Extension: `ascii_identifiers` ####
3794−
3795−Causes the identifiers produced by `auto_identifiers` to be pure ASCII.
3796−Accents are stripped off of accented Latin letters, and non-Latin
3797−letters are omitted.
3798−
37993966#### Extension: `mmd_link_attributes` ####
38003967
38013968Parses multimarkdown style key-value attributes on link
@@ -3839,12 +4006,6 @@ in several respects:
38394006 we must either disallow lazy wrapping or require a blank line between
38404007 list items.
38414008
3842−#### Extension: `empty_paragraphs` ####
3843−
3844−Allows empty paragraphs. By default empty paragraphs are
3845−omitted. This affects the `docx` reader and writer, the
3846−`opendocument` and `odt` writer, and all HTML-based readers and writers.
3847−
38484009Markdown variants
38494010-----------------
38504011
@@ -3878,34 +4039,21 @@ variants are supported:
38784039: `raw_html`, `shortcut_reference_links`,
38794040 `spaced_reference_links`.
38804041
3881−We also support `gfm` (GitHub-Flavored Markdown) as a set of
3882−extensions on `commonmark`:
4042+We also support `commonmark` and `gfm` (GitHub-Flavored Markdown,
4043+which is implemented as a set of extensions on `commonmark`).
4044+
4045+Note, however, that `commonmark` and `gfm` have limited support
4046+for extensions. Only those listed below (and `smart` and
4047+`raw_tex`) will work. The extensions can, however, all be
4048+individually disabled.
4049+Also, `raw_tex` only affects `gfm` output, not input.
38834050
4051+`gfm` (GitHub-Flavored Markdown)
38844052: `pipe_tables`, `raw_html`, `fenced_code_blocks`, `auto_identifiers`,
38854053 `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`,
38864054 `intraword_underscores`, `strikeout`, `hard_line_breaks`, `emoji`,
38874055 `shortcut_reference_links`, `angle_brackets_escapable`.
38884056
3889− These can all be individually disabled. Note, however, that
3890− `commonmark` and `gfm` have limited support for extensions:
3891− extensions other than those listed above (and `smart` and
3892− `raw_tex`) will have no effect on `commonmark` or `gfm`.
3893− And `raw_tex` only affects `gfm` output, not input.
3894−
3895−Extensions with formats other than Markdown
3896−-------------------------------------------
3897−
3898−Some of the extensions discussed above can be used with formats
3899−other than Markdown:
3900−
3901−* `auto_identifiers` can be used with `latex`, `rst`, `mediawiki`,
3902− and `textile` input (and is used by default).
3903−
3904−* `tex_math_dollars`, `tex_math_single_backslash`, and
3905− `tex_math_double_backslash` can be used with `html` input.
3906− (This is handy for reading web pages formatted using MathJax,
3907− for example.)
3908−
39094057Producing slide shows with pandoc
39104058=================================
39114059
@@ -4257,57 +4405,6 @@ with the `src` attribute. For example:
42574405 </source>
42584406 </audio>
42594407
4260−Literate Haskell support
4261−========================
4262−
4263−If you append `+lhs` (or `+literate_haskell`) to an appropriate input or output
4264−format (`markdown`, `markdown_strict`, `rst`, or `latex` for input or output;
4265−`beamer`, `html4` or `html5` for output only), pandoc will treat the document as
4266−literate Haskell source. This means that
4267−
4268− - In Markdown input, "bird track" sections will be parsed as Haskell
4269− code rather than block quotations. Text between `\begin{code}`
4270− and `\end{code}` will also be treated as Haskell code. For
4271− ATX-style headers the character '=' will be used instead of '#'.
4272−
4273− - In Markdown output, code blocks with classes `haskell` and `literate`
4274− will be rendered using bird tracks, and block quotations will be
4275− indented one space, so they will not be treated as Haskell code.
4276− In addition, headers will be rendered setext-style (with underlines)
4277− rather than ATX-style (with '#' characters). (This is because ghc
4278− treats '#' characters in column 1 as introducing line numbers.)
4279−
4280− - In restructured text input, "bird track" sections will be parsed
4281− as Haskell code.
4282−
4283− - In restructured text output, code blocks with class `haskell` will
4284− be rendered using bird tracks.
4285−
4286− - In LaTeX input, text in `code` environments will be parsed as
4287− Haskell code.
4288−
4289− - In LaTeX output, code blocks with class `haskell` will be rendered
4290− inside `code` environments.
4291−
4292− - In HTML output, code blocks with class `haskell` will be rendered
4293− with class `literatehaskell` and bird tracks.
4294−
4295−Examples:
4296−
4297− pandoc -f markdown+lhs -t html
4298−
4299−reads literate Haskell source formatted with Markdown conventions and writes
4300−ordinary HTML (without bird tracks).
4301−
4302− pandoc -f markdown+lhs -t html+lhs
4303−
4304−writes HTML with the Haskell code in bird tracks, so it can be copied
4305−and pasted as literate Haskell source.
4306−
4307−Note that GHC expects the bird tracks in the first column, so indentend literate
4308−code blocks (e.g. inside an itemized environment) will not be picked up by the
4309−Haskell compiler.
4310−
43114408Syntax highlighting
43124409===================
43134410