README · typeable/pandoc

1468[^3]: I have also been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html).

1469

1470[PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/

1471

1472

1473### Numbered example lists ###

1474

1475**Extension: `example_lists`**

1476

1477The special list marker `@` can be used for sequentially numbered

1478examples. The first list item with a `@` marker will be numbered '1',

1479the next '2', and so on, throughout the document. The numbered examples

1480need not occur in a single list; each new list using `@` will take up

1481where the last stopped. So, for example:

1482

1483 (@) My first example will be numbered (1).

1484 (@) My second example will be numbered (2).

1485

1486 Explanation of examples.

1487

1488 (@) My third example will be numbered (3).

1489

1490Numbered examples can be labeled and referred to elsewhere in the

1491document:

1492

1493 (@good) This is a good example.

1494

1495 As (@good) illustrates, ...

1496

1497The label can be any string of alphanumeric characters, underscores,

1498or hyphens.

1499

1500

1501### Compact and loose lists ###

1502

1503Pandoc behaves differently from `Markdown.pl` on some "edge

1504cases" involving lists. Consider this source:

1505

1506 + First

1507 + Second:

1508 - Fee

1509 - Fie

1510 - Foe

1511

1512 + Third

1513

1514Pandoc transforms this into a "compact list" (with no `<p>` tags around

1515"First", "Second", or "Third"), while markdown puts `<p>` tags around

1516"Second" and "Third" (but not "First"), because of the blank space

1517around "Third". Pandoc follows a simple rule: if the text is followed by

1518a blank line, it is treated as a paragraph. Since "Second" is followed

1519by a list, and not a blank line, it isn't treated as a paragraph. The

1520fact that the list is followed by a blank line is irrelevant. (Note:

1521Pandoc works this way even when the `markdown_strict` format is specified. This

1522behavior is consistent with the official markdown syntax description,

1523even though it is different from that of `Markdown.pl`.)

1524

1525

1526### Ending a list ###

1527

1528What if you want to put an indented code block after a list?

1529

1530 - item one

1531 - item two

1532

1533 { my code block }

1534

1535Trouble! Here pandoc (like other markdown implementations) will treat

1536`{ my code block }` as the second paragraph of item two, and not as

1537a code block.

1538

1539To "cut off" the list after item two, you can insert some non-indented

1540content, like an HTML comment, which won't produce visible output in

1541any format:

1542

1543 - item one

1544 - item two

1545

1546

1547

1548 { my code block }

1549

1550You can use the same trick if you want two consecutive lists instead

1551of one big list:

1552

1553 1. one

1554 2. two

1555 3. three

1556

1557

1558

1559 1. uno

1560 2. dos

1561 3. tres

1562

1563Horizontal rules

1564----------------

1565

1566A line containing a row of three or more `*`, `-`, or `_` characters

1567(optionally separated by spaces) produces a horizontal rule:

1569 * * * *

1571 ---------------

1574Tables

1575------

1576

1577Four kinds of tables may be used. The first three kinds presuppose the use of

1578a fixed-width font, such as Courier. The fourth kind can be used with

1579proportionally spaced fonts, as it does not require lining up columns.

1580

1581### Simple tables

1582

1583**Extension: `simple_tables`, `table_captions`**

1584

1585Simple tables look like this:

1586

1587 Right Left Center Default

1588 ------- ------ ---------- -------

1589 12 12 12 12

1590 123 123 123 123

1591 1 1 1 1

1592

1593 Table: Demonstration of simple table syntax.

1594

1595The headers and table rows must each fit on one line. Column

1596alignments are determined by the position of the header text relative

1597to the dashed line below it:[^4]

1598

1599 - If the dashed line is flush with the header text on the right side

1600 but extends beyond it on the left, the column is right-aligned.

1601 - If the dashed line is flush with the header text on the left side

1602 but extends beyond it on the right, the column is left-aligned.

1603 - If the dashed line extends beyond the header text on both sides,

1604 the column is centered.

1605 - If the dashed line is flush with the header text on both sides,

1606 the default alignment is used (in most cases, this will be left).

1607

1608[^4]: This scheme is due to Michel Fortin, who proposed it on the

1609 [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html).

1610

1611The table must end with a blank line, or a line of dashes followed by

1612a blank line. A caption may optionally be provided (as illustrated in

1613the example above). A caption is a paragraph beginning with the string

1614`Table:` (or just `:`), which will be stripped off. It may appear either

1615before or after the table.

1616

1617The column headers may be omitted, provided a dashed line is used

1618to end the table. For example:

1619

1620 ------- ------ ---------- -------

1621 12 12 12 12

1622 123 123 123 123

1623 1 1 1 1

1624 ------- ------ ---------- -------

1625

1626When headers are omitted, column alignments are determined on the basis

1627of the first line of the table body. So, in the tables above, the columns

1628would be right, left, center, and right aligned, respectively.

1629

1630### Multiline tables

1631

1632**Extension: `multiline_tables`, `table_captions`**

1633

1634Multiline tables allow headers and table rows to span multiple lines

1635of text (but cells that span multiple columns or rows of the table are

1636not supported). Here is an example:

1637

1638 -------------------------------------------------------------

1639 Centered Default Right Left

1640 Header Aligned Aligned Aligned

1641 ----------- ------- --------------- -------------------------

1642 First row 12.0 Example of a row that

1643 spans multiple lines.

1644

1645 Second row 5.0 Here's another one. Note

1646 the blank line between

1647 rows.

1648 -------------------------------------------------------------

1649

1650 Table: Here's the caption. It, too, may span

1651 multiple lines.

1652

1653These work like simple tables, but with the following differences:

1654

1655 - They must begin with a row of dashes, before the header text

1656 (unless the headers are omitted).

1657 - They must end with a row of dashes, then a blank line.

1658 - The rows must be separated by blank lines.

1659

1660In multiline tables, the table parser pays attention to the widths of

1661the columns, and the writers try to reproduce these relative widths in

1662the output. So, if you find that one of the columns is too narrow in the

1663output, try widening it in the markdown source.

1664

1665Headers may be omitted in multiline tables as well as simple tables:

1666

1667 ----------- ------- --------------- -------------------------

1668 First row 12.0 Example of a row that

1669 spans multiple lines.

1670

1671 Second row 5.0 Here's another one. Note

1672 the blank line between

1673 rows.

1674 ----------- ------- --------------- -------------------------

1675

1676 : Here's a multiline table without headers.

1677

1678It is possible for a multiline table to have just one row, but the row

1679should be followed by a blank line (and then the row of dashes that ends

1680the table), or the table may be interpreted as a simple table.

1681

1682### Grid tables

1683

1684**Extension: `grid_tables`, `table_captions`**

1685

1686Grid tables look like this:

1687

1688 : Sample grid table.

1689

1690 +---------------+---------------+--------------------+

1691 | Fruit | Price | Advantages |

1692 +===============+===============+====================+

1693 | Bananas | $1.34 | - built-in wrapper |

1694 | | | - bright color |

1695 +---------------+---------------+--------------------+

1696 | Oranges | $2.10 | - cures scurvy |

1697 | | | - tasty |

1698 +---------------+---------------+--------------------+

1699

1700The row of `=`s separates the header from the table body, and can be

1701omitted for a headerless table. The cells of grid tables may contain

1702arbitrary block elements (multiple paragraphs, code blocks, lists,

1703etc.). Alignments are not supported, nor are cells that span multiple

1704columns or rows. Grid tables can be created easily using [Emacs table mode].

1705

1706 [Emacs table mode]: http://table.sourceforge.net/

1707

1708### Pipe tables

1709

1710**Extension: `pipe_tables`, `table_captions`**

1711

1712Pipe tables look like this:

1713

1715 |------:|:-----|---------|:------:|

1716 | 12 | 12 | 12 | 12 |

1717 | 123 | 123 | 123 | 123 |

1718 | 1 | 1 | 1 | 1 |

1719

1720 : Demonstration of simple table syntax.

1721

1722The syntax is [the same as in PHP markdown extra]. The beginning and

1723ending pipe characters are optional, but pipes are required between all

1724columns. The colons indicate column alignment as shown. The header

1725can be omitted, but the horizontal line must still be included, as

1726it defines column alignments.

1727

1728Since the pipes indicate column boundaries, columns need not be vertically

1729aligned, as they are in the above example. So, this is a perfectly

1730legal (though ugly) pipe table:

1731

1732 fruit| price

1733 -----|-----:

1734 apple|2.05

1735 pear|1.37

1736 orange|3.09

1737

1738The cells of pipe tables cannot contain block elements like paragraphs

1739and lists, and cannot span multiple lines.

1740

1741 [the same as in PHP markdown extra]:

1742 http://michelf.ca/projects/php-markdown/extra/#table

1743

1744Note: Pandoc also recognizes pipe tables of the following

1745form, as can produced by Emacs' orgtbl-mode:

1746

1747 | One | Two |

1748 |-----+-------|

1749 | my | table |

1750 | is | nice |

1751

1752The difference is that `+` is used instead of `|`. Other orgtbl features

1753are not supported. In particular, to get non-default column alignment,

1754you'll need to add colons as above.

1755

1756Title block

1757-----------

1758

1759**Extension: `pandoc_title_block`**

1760

1761If the file begins with a title block

1762

1763 % title

1764 % author(s) (separated by semicolons)

1765 % date

1766

1767it will be parsed as bibliographic information, not regular text. (It

1768will be used, for example, in the title of standalone LaTeX or HTML

1769output.) The block may contain just a title, a title and an author,

1770or all three elements. If you want to include an author but no

1771title, or a title and a date but no author, you need a blank line:

1772

1773 %

1774 % Author

1775

1776 % My title

1777 %

1778 % June 15, 2006

1779

1780The title may occupy multiple lines, but continuation lines must

1781begin with leading space, thus:

1782

1783 % My title

1784 on multiple lines

1785

1786If a document has multiple authors, the authors may be put on

1787separate lines with leading space, or separated by semicolons, or

1788both. So, all of the following are equivalent:

1789

1790 % Author One

1791 Author Two

1792

1793 % Author One; Author Two

1794

1795 % Author One;

1796 Author Two

1797

1798The date must fit on one line.

1799

1800All three metadata fields may contain standard inline formatting

1801(italics, links, footnotes, etc.).

1802

1803Title blocks will always be parsed, but they will affect the output only

1804when the `--standalone` (`-s`) option is chosen. In HTML output, titles

1805will appear twice: once in the document head -- this is the title that

1806will appear at the top of the window in a browser -- and once at the

1807beginning of the document body. The title in the document head can have

1808an optional prefix attached (`--title-prefix` or `-T` option). The title

1809in the body appears as an H1 element with class "title", so it can be

1810suppressed or reformatted with CSS. If a title prefix is specified with

1811`-T` and no title block appears in the document, the title prefix will

1812be used by itself as the HTML title.

1813

1814The man page writer extracts a title, man page section number, and

1815other header and footer information from the title line. The title

1816is assumed to be the first word on the title line, which may optionally

1817end with a (single-digit) section number in parentheses. (There should

1818be no space between the title and the parentheses.) Anything after

1819this is assumed to be additional footer and header text. A single pipe

1820character (`|`) should be used to separate the footer text from the header

1821text. Thus,

1822

1823 % PANDOC(1)

1824

1825will yield a man page with the title `PANDOC` and section 1.

1826

1827 % PANDOC(1) Pandoc User Manuals

1828

1829will also have "Pandoc User Manuals" in the footer.

1830

1831 % PANDOC(1) Pandoc User Manuals | Version 4.0

1832

1833will also have "Version 4.0" in the header.

1834

1835YAML metadata block

1836-------------------

1837

1838**Extension: `yaml_metadata_block`**

1839

1840A YAML metadata block is a valid YAML object, delimited by a line of three

1841hyphens (`---`) at the top and a line of three hyphens (`---`) or three dots

1842(`...`) at the bottom. A YAML metadata block may occur anywhere in the

1843document, but if it is not at the beginning, it must be preceded by a blank

1844line.

1845

1846Metadata will be taken from the fields of the YAML object and added to any

1847existing document metadata. Metadata can contain lists and objects (nested

1848arbitrarily), but all string scalars will be interpreted as markdown. Fields

1849with names ending in an underscore will be ignored by pandoc. (They may be

1850given a role by external processors.)

1851

1852A document may contain multiple metadata blocks. The metadata fields will

1853be combined through a *left-biased union*: if two metadata blocks attempt

1854to set the same field, the value from the first block will be taken.

1855

1856Note that YAML escaping rules must be followed. Thus, for example,

1857if a title contains a colon, it must be quoted. The pipe character

1858(`|`) can be used to begin an indented block that will be interpreted

1859literally, without need for escaping. This form is necessary

1860when the field contains blank lines:

1861

1862 ---

1863 title: 'This is the title: it contains a colon'

1864 author:

1865 - name: Author One

1866 affiliation: University of Somewhere

1867 - name: Author Two

1868 affiliation: University of Nowhere

1869 tags: [nothing, nothingness]

1870 abstract: |

1871 This is the abstract.

1872

1873 It consists of two paragraphs.

1874 ...

1875

1876Template variables will be set automatically from the metadata. Thus, for

1877example, in writing HTML, the variable `abstract` will be set to the HTML

1878equivalent of the markdown in the `abstract` field:

1879

1880 <p>This is the abstract.</p>

1881 <p>It consists of two paragraphs.</p>

1882

1883Note: The `author` variable in the default templates expects a simple list or

1884string. To use the structured authors in the example, you would need a

1885custom template. For example:

1886

1887 $for(author)$

1888 $if(author.name)$

1889 $author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$

1890 $else$

1891 $author$

1892 $endif$

1893 $endfor$

1894

1895

1896Backslash escapes

1897-----------------

1898

1899**Extension: `all_symbols_escapable`**

1900

1901Except inside a code block or inline code, any punctuation or space

1902character preceded by a backslash will be treated literally, even if it

1903would normally indicate formatting. Thus, for example, if one writes

1904

1905 *\*hello\**

1906

1907one will get

1908

1909 <em>*hello*</em>

1910

1911instead of

1912

1913 <strong>hello</strong>

1914

1915This rule is easier to remember than standard markdown's rule,

1916which allows only the following characters to be backslash-escaped:

1917

1918 \`*_{}[]()>#+-.!

1919

1920(However, if the `markdown_strict` format is used, the standard markdown rule

1921will be used.)

1922

1923A backslash-escaped space is parsed as a nonbreaking space. It will

1924appear in TeX output as `~` and in HTML and XML as `\ ` or

1925`\ `.

1926

1927A backslash-escaped newline (i.e. a backslash occurring at the end of

1928a line) is parsed as a hard line break. It will appear in TeX output as

1929`\\` and in HTML as `<br />`. This is a nice alternative to

1930markdown's "invisible" way of indicating hard line breaks using

1931two trailing spaces on a line.

1932

1933Backslash escapes do not work in verbatim contexts.

1934

1935Smart punctuation

1936-----------------

1937

1938**Extension**

1939

1940If the `--smart` option is specified, pandoc will produce typographically

1941correct output, converting straight quotes to curly quotes, `---` to

1942em-dashes, `--` to en-dashes, and `...` to ellipses. Nonbreaking spaces

1943are inserted after certain abbreviations, such as "Mr."

1944

1945Note: if your LaTeX template uses the `csquotes` package, pandoc will

1946detect automatically this and use `\enquote{...}` for quoted text.

1947

1948Inline formatting

1949-----------------

1950

1951### Emphasis ###

1952

1953To *emphasize* some text, surround it with `*`s or `_`, like this:

1954

1955 This text is _emphasized with underscores_, and this

1956 is *emphasized with asterisks*.

1957

1958Double `*` or `_` produces **strong emphasis**:

1959

1960 This is **strong emphasis** and __with underscores__.

1961

1962A `*` or `_` character surrounded by spaces, or backslash-escaped,

1963will not trigger emphasis:

1964

1965 This is * not emphasized *, and \*neither is this\*.

1966

1967**Extension: `intraword_underscores`**

1968

1969Because `_` is sometimes used inside words and identifiers,

1970pandoc does not interpret a `_` surrounded by alphanumeric

1971characters as an emphasis marker. If you want to emphasize

1972just part of a word, use `*`:

1973

1974 feas*ible*, not feas*able*.

1975

1976

1977### Strikeout ###

1978

1979**Extension: `strikeout`**

1980

1981To strikeout a section of text with a horizontal line, begin and end it

1982with `~~`. Thus, for example,

1983

1984 This ~~is deleted text.~~

1985

1986

1987### Superscripts and subscripts ###

1988

1989**Extension: `superscript`, `subscript`**

1990

1991Superscripts may be written by surrounding the superscripted text by `^`

1992characters; subscripts may be written by surrounding the subscripted

1993text by `~` characters. Thus, for example,

1994

1995 H~2~O is a liquid. 2^10^ is 1024.

1996

1997If the superscripted or subscripted text contains spaces, these spaces

1998must be escaped with backslashes. (This is to prevent accidental

1999superscripting and subscripting through the ordinary use of `~` and `^`.)

2000Thus, if you want the letter P with 'a cat' in subscripts, use

2001`P~a\ cat~`, not `P~a cat~`.

2002

2003

2004### Verbatim ###

2005

2006To make a short span of text verbatim, put it inside backticks:

2007

2008 What is the difference between `>>=` and `>>`?

2009

2010If the verbatim text includes a backtick, use double backticks:

2011

2012 Here is a literal backtick `` ` ``.

2013

2014(The spaces after the opening backticks and before the closing

2015backticks will be ignored.)

2016

2017The general rule is that a verbatim span starts with a string

2018of consecutive backticks (optionally followed by a space)

2019and ends with a string of the same number of backticks (optionally

2020preceded by a space).

2021

2022Note that backslash-escapes (and other markdown constructs) do not

2023work in verbatim contexts:

2024

2025 This is a backslash followed by an asterisk: `\*`.

2026

2027**Extension: `inline_code_attributes`**

2028

2029Attributes can be attached to verbatim text, just as with

2030[fenced code blocks](#fenced-code-blocks):

2031

2032 `<$>`{.haskell}

2033

2034### Small caps ###

2035

2036To write small caps, you can use an HTML span tag:

2037

2038 <span style="font-variant:small-caps;">Small caps</span>

2039

2040This will work in all output formats that support small caps.

2041

2042Math

2043----

2044

2045**Extension: `tex_math_dollars`**

2046

2047Anything between two `$` characters will be treated as TeX math. The

2048opening `$` must have a character immediately to its right, while the

2049closing `$` must have a character immediately to its left. Thus,

2050`$20,000 and $30,000` won't parse as math. If for some reason

2051you need to enclose text in literal `$` characters, backslash-escape

2052them and they won't be treated as math delimiters.

2053

2054TeX math will be printed in all output formats. How it is rendered

2055depends on the output format:

2056

2057Markdown, LaTeX, Org-Mode, ConTeXt

2058 ~ It will appear verbatim between `$` characters.

2059

2060reStructuredText

2061 ~ It will be rendered using an interpreted text role `:math:`, as described

2062 [here](http://www.american.edu/econ/itex2mml/mathhack.rst).

2063

2064AsciiDoc

2065 ~ It will be rendered as `latexmath:[...]`.

2066

2067Texinfo

2068 ~ It will be rendered inside a `@math` command.

2069

2070groff man

2071 ~ It will be rendered verbatim without `$`'s.

2072

2073MediaWiki

2074 ~ It will be rendered inside `<math>` tags.

2075

2076Textile

2077 ~ It will be rendered inside `<span class="math">` tags.

2078

2079RTF, OpenDocument, ODT

2080 ~ It will be rendered, if possible, using unicode characters,

2081 and will otherwise appear verbatim.

2082

2083Docbook

2084 ~ If the `--mathml` flag is used, it will be rendered using mathml

2085 in an `inlineequation` or `informalequation` tag. Otherwise it

2086 will be rendered, if possible, using unicode characters.

2087

2088Docx

2089 ~ It will be rendered using OMML math markup.

2090

2091FictionBook2

2092 ~ If the `--webtex` option is used, formulas are rendered as images

2093 using Google Charts or other compatible web service, downloaded

2094 and embedded in the e-book. Otherwise, they will appear verbatim.

2095

2096HTML, Slidy, DZSlides, S5, EPUB

2097 ~ The way math is rendered in HTML will depend on the

2098 command-line options selected:

2099

2100 1. The default is to render TeX math as far as possible using unicode

2101 characters, as with RTF, DocBook, and OpenDocument output. Formulas

2102 are put inside a `span` with `class="math"`, so that they may be

2103 styled differently from the surrounding text if needed.

2104

2105 2. If the `--latexmathml` option is used, TeX math will be displayed

2106 between `$` or `$$` characters and put in `<span>` tags with class `LaTeX`.

2107 The [LaTeXMathML] script will be used to render it as formulas.

2108 (This trick does not work in all browsers, but it works in Firefox.

2109 In browsers that do not support LaTeXMathML, TeX math will appear

2110 verbatim between `$` characters.)

2111

2112 3. If the `--jsmath` option is used, TeX math will be put inside

2113 `<span>` tags (for inline math) or `<div>` tags (for display math)

2114 with class `math`. The [jsMath] script will be used to render

2115 it.

2116

2117 4. If the `--mimetex` option is used, the [mimeTeX] CGI script will

2118 be called to generate images for each TeX formula. This should

2119 work in all browsers. The `--mimetex` option takes an optional URL

2120 as argument. If no URL is specified, it will be assumed that the

2121 mimeTeX CGI script is at `/cgi-bin/mimetex.cgi`.

2122

2123 5. If the `--gladtex` option is used, TeX formulas will be enclosed

2124 in `<eq>` tags in the HTML output. The resulting `htex` file may then

2125 be processed by [gladTeX], which will produce image files for each

2126 formula and an `html` file with links to these images. So, the

2127 procedure is:

2128

2129 pandoc -s --gladtex myfile.txt -o myfile.htex

2130 gladtex -d myfile-images myfile.htex

2131 # produces myfile.html and images in myfile-images

2132

2133 6. If the `--webtex` option is used, TeX formulas will be converted

2134 to `<img>` tags that link to an external script that converts

2135 formulas to images. The formula will be URL-encoded and concatenated

2136 with the URL provided. If no URL is specified, the Google Chart

2137 API will be used (`http://chart.apis.google.com/chart?cht=tx&chl=`).

2138

2139 7. If the `--mathjax` option is used, TeX math will be displayed

2140 between `$...$` (for inline math) or `\[...\]` (for display

2141 math) and put in `<span>` tags with class `math`.

2142 The [MathJax] script will be used to render it as formulas.

2143

2144Raw HTML

2145--------

2146

2147**Extension: `raw_html`**

2148

2149Markdown allows you to insert raw HTML (or DocBook) anywhere in a document

2150(except verbatim contexts, where `<`, `>`, and `&` are interpreted

2151literally). (Technically this is not an extension, since standard

2152markdown allows it, but it has been made an extension so that it can

2153be disabled if desired.)

2154

2155The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,

2156DZSlides, EPUB, Markdown, and Textile output, and suppressed in other

2157formats.

2158

2159**Extension: `markdown_in_html_blocks`**

2160

2161Standard markdown allows you to include HTML "blocks": blocks

2162of HTML between balanced tags that are separated from the surrounding text

2163with blank lines, and start and end at the left margin. Within

2164these blocks, everything is interpreted as HTML, not markdown;

2165so (for example), `*` does not signify emphasis.

2166

2167Pandoc behaves this way when the `markdown_strict` format is used; but

2168by default, pandoc interprets material between HTML block tags as markdown.

2169Thus, for example, Pandoc will turn

2170

2171 <table>

2172 <tr>

2173 <td>*one*</td>

2174 <td>[a link](http://google.com)</td>

2175 </tr>

2176 </table>

2177

2178into

2179

2180 <table>

2181 <tr>

2182 <td><em>one</em></td>

2183 <td><a href="http://google.com">a link</a></td>

2184 </tr>

2185 </table>

2186

2187whereas `Markdown.pl` will preserve it as is.

2188

2189There is one exception to this rule: text between `<script>` and

2190`<style>` tags is not interpreted as markdown.

2191

2192This departure from standard markdown should make it easier to mix

2193markdown with HTML block elements. For example, one can surround

2194a block of markdown text with `<div>` tags without preventing it

2195from being interpreted as markdown.

2196

2197Raw TeX

2198-------

2199

2200**Extension: `raw_tex`**

2201

2202In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be

2203included in a document. Inline TeX commands will be preserved and passed

2204unchanged to the LaTeX and ConTeXt writers. Thus, for example, you can use

2205LaTeX to include BibTeX citations:

2206

2207 This result was proved in \cite{jones.1967}.

2208

2209Note that in LaTeX environments, like

2210

2211 \begin{tabular}{|l|l|}\hline

2212 Age & Frequency \\ \hline

2213 18--25 & 15 \\

2214 26--35 & 33 \\

2215 36--45 & 22 \\ \hline

2216 \end{tabular}

2217

2218the material between the begin and end tags will be interpreted as raw

2219LaTeX, not as markdown.

2220

2221Inline LaTeX is ignored in output formats other than Markdown, LaTeX,

2222and ConTeXt.

2223

2224LaTeX macros

2225------------

2226

2227**Extension: `latex_macros`**

2228

2229For output formats other than LaTeX, pandoc will parse LaTeX `\newcommand` and

2230`\renewcommand` definitions and apply the resulting macros to all LaTeX

2231math. So, for example, the following will work in all output formats,

2232not just LaTeX:

2233

2234 \newcommand{\tuple}[1]{\langle #1 \rangle}

2235

2236 $\tuple{a, b, c}$

2237

2238In LaTeX output, the `\newcommand` definition will simply be passed

2239unchanged to the output.

2240

2241

2242Links

2243-----

2244

2245Markdown allows links to be specified in several ways.

2246

2247### Automatic links ###

2248

2249If you enclose a URL or email address in pointy brackets, it

2250will become a link:

2251

2252 <http://google.com>

2253 <sam@green.eggs.ham>

2254

2255### Inline links ###

2256

2257An inline link consists of the link text in square brackets,

2258followed by the URL in parentheses. (Optionally, the URL can

2259be followed by a link title, in quotes.)

2260

2261 This is an [inline link](/url), and here's [one with

2262 a title](http://fsf.org "click here for a good time!").

2263

2264There can be no space between the bracketed part and the parenthesized part.

2265The link text can contain formatting (such as emphasis), but the title cannot.

2266

2267

2268### Reference links ###

2269

2270An *explicit* reference link has two parts, the link itself and the link

2271definition, which may occur elsewhere in the document (either

2272before or after the link).

2273

2274The link consists of link text in square brackets, followed by a label in

2275square brackets. (There can be space between the two.) The link definition

2276consists of the bracketed label, followed by a colon and a space, followed by

2277the URL, and optionally (after a space) a link title either in quotes or in

2278parentheses.

2279

2280Here are some examples:

2281

2282 [my label 1]: /foo/bar.html "My title, optional"

2283 [my label 2]: /foo

2284 [my label 3]: http://fsf.org (The free software foundation)

2285 [my label 4]: /bar#special 'A title in single quotes'

2286

2287The URL may optionally be surrounded by angle brackets:

2288

2289 [my label 5]: <http://foo.bar.baz>

2290

2291The title may go on the next line:

2292

2293 [my label 3]: http://fsf.org

2294 "The free software foundation"

2295

2296Note that link labels are not case sensitive. So, this will work:

2297

2298 Here is [my link][FOO]

2299

2300 [Foo]: /bar/baz

2301

2302In an *implicit* reference link, the second pair of brackets is

2303empty, or omitted entirely:

2304

2305 See [my website][], or [my website].

2306

2307 [my website]: http://foo.bar.baz

2308

2309Note: In `Markdown.pl` and most other markdown implementations,

2310reference link definitions cannot occur in nested constructions

2311such as list items or block quotes. Pandoc lifts this arbitrary

2312seeming restriction. So the following is fine in pandoc, though

2313not in most other implementations:

2314

2315 > My block [quote].

2316 >

2317 > [quote]: /foo

2318

2319### Internal links

2320

2321To link to another section of the same document, use the automatically

2322generated identifier (see [Header identifiers in HTML, LaTeX, and

2323ConTeXt](#header-identifiers-in-html-latex-and-context), below).

2324For example:

2325

2326 See the [Introduction](#introduction).

2327

2328or

2329

2330 See the [Introduction].

2331

2332 [Introduction]: #introduction

2333

2334Internal links are currently supported for HTML formats (including

2335HTML slide shows and EPUB), LaTeX, and ConTeXt.

2336

2337Images

2338------

2339

2340A link immediately preceded by a `!` will be treated as an image.

2341The link text will be used as the image's alt text:

2342

2343 ![la lune](lalune.jpg "Voyage to the moon")

2344

2345 ![movie reel]

2346

2347 [movie reel]: movie.gif

2348

2349### Pictures with captions ###

2350

2351**Extension: `implicit_figures`**

2352

2353An image occurring by itself in a paragraph will be rendered as

2354a figure with a caption.[^5] (In LaTeX, a figure environment will be

2355used; in HTML, the image will be placed in a `div` with class

2356`figure`, together with a caption in a `p` with class `caption`.)

2357The image's alt text will be used as the caption.

2358

2359 ![This is the caption](/url/of/image.png)

2360

2361[^5]: This feature is not yet implemented for RTF, OpenDocument, or

2362 ODT. In those formats, you'll just get an image in a paragraph by

2363 itself, with no caption.

2364

2365If you just want a regular inline image, just make sure it is not

2366the only thing in the paragraph. One way to do this is to insert a

2367nonbreaking space after the image:

2368

2369 ![This image won't be a figure](/url/of/image.png)\

2370

2371

2372Footnotes

2373---------

2374

2375**Extension: `footnotes`**

2376

2377Pandoc's markdown allows footnotes, using the following syntax:

2378

2379 Here is a footnote reference,[^1] and another.[^longnote]

2380

2381 [^1]: Here is the footnote.

2382

2383 [^longnote]: Here's one with multiple blocks.

2384

2385 Subsequent paragraphs are indented to show that they

2386 belong to the previous footnote.

2387

2388 { some.code }

2389

2390 The whole paragraph can be indented, or just the first

2391 line. In this way, multi-paragraph footnotes work like

2392 multi-paragraph list items.

2393

2394 This paragraph won't be part of the note, because it

2395 isn't indented.

2396

2397The identifiers in footnote references may not contain spaces, tabs,

2398or newlines. These identifiers are used only to correlate the

2399footnote reference with the note itself; in the output, footnotes

2400will be numbered sequentially.

2401

2402The footnotes themselves need not be placed at the end of the

2403document. They may appear anywhere except inside other block elements

2404(lists, block quotes, tables, etc.).

2405

2406**Extension: `inline_notes`**

2407

2408Inline footnotes are also allowed (though, unlike regular notes,

2409they cannot contain multiple paragraphs). The syntax is as follows:

2410

2411 Here is an inline note.^[Inlines notes are easier to write, since

2412 you don't have to pick an identifier and move down to type the

2413 note.]

2414

2415Inline and regular footnotes may be mixed freely.

2416

2417

2418Citations

2419---------

2420

2421**Extension: `citations`**

2422

2423Using an external filter, `pandoc-citeproc`, pandoc can automatically generate

2424citations and a bibliography in a number of styles. Basic usage is

2425

2426 pandoc --filter pandoc-citeproc myinput.txt

2427

2428In order to use this feature, you will need to specify a bibliography file

2429using the `bibliography` metadata field in a YAML metadata section.

2430The bibliography may have any of these formats:

2431

2432 Format File extension

2433 ------------ --------------

2434 MODS .mods

2435 BibLaTeX .bib

2436 BibTeX .bibtex

2437 RIS .ris

2438 EndNote .enl

2439 EndNote XML .xml

2440 ISI .wos

2441 MEDLINE .medline

2442 Copac .copac

2443 JSON citeproc .json

2444

2445Note that `.bib` can generally be used with both BibTeX and BibLaTeX

2446files, but you can use `.bibtex` to force BibTeX.

2447

2448Alternatively you can use a `references` field in the document's YAML

2449metadata. This should include an array of YAML-encoded references,

2450for example:

2451

2452 ---

2453 references:

2454 - id: fenner2012a

2455 title: One-click science marketing

2456 author:

2457 - family: Fenner

2458 given: Martin

2459 container-title: Nature Materials

2460 volume: 11

2461 URL: 'http://dx.doi.org/10.1038/nmat3283'

2462 DOI: 10.1038/nmat3283

2463 issue: 4

2464 publisher: Nature Publishing Group

2465 page: 261-263

2466 type: article-journal

2467 issued:

2468 year: 2012

2469 month: 3

2470 ...

2471

2472(The program `mods2yaml`, which comes with `pandoc-citeproc`, can help produce

2473these from a MODS reference collection.)

2474

2475By default, `pandoc-citeproc` will use a Chicago author-date format for

2476citations and references. To use another style, you will need to specify

2477a [CSL] 1.0 style file in the `csl` metadata field. A primer on creating and

2478modifying CSL styles can be found at

2479<http://citationstyles.org/downloads/primer.html>. A repository of CSL styles

2480can be found at <https://github.com/citation-style-language/styles>. See also

2481<http://zotero.org/styles> for easy browsing.

2482

2483Citations go inside square brackets and are separated by semicolons.

2484Each citation must have a key, composed of '@' + the citation

2485identifier from the database, and may optionally have a prefix,

2486a locator, and a suffix. The citation key must begin with a letter

2487or `_`, and may contain alphanumerics, `_`, and internal punctuation

2488characters (`:.#$%&-+?<>~/`). Here are some examples:

2489

2490 Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].

2491

2492 Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].

2493

2494 Blah blah [@smith04; @doe99].

2495

2496A minus sign (`-`) before the `@` will suppress mention of

2497the author in the citation. This can be useful when the

2498author is already mentioned in the text:

2499

2500 Smith says blah [-@smith04].

2501

2502You can also write an in-text citation, as follows:

2503

2504 @smith04 says blah.

2505

2506 @smith04 [p. 33] says blah.

2507

2508If the style calls for a list of works cited, it will be placed

2509at the end of the document. Normally, you will want to end your

2510document with an appropriate header:

2511

2512 last paragraph...

2513

2514 # References

2515

2516The bibliography will be inserted after this header. Note that

2517the `unnumbered` class will be added to this header, so that the

2518section will not be numbered.

2519

2520If you want to include items in the bibliography without actually

2521citing them in the body text, you can define a dummy `nocite` metadata

2522field and put the citations there:

2523

2524 ---

2525 nocite: |

2526 @item1, @item2

2527 ...

2528

2529 @item3

2530

2531In this example, the document will contain a citation for `item3`

2532only, but the bibliography will contain entries for `item1`, `item2`, and

2533`item3`.

2534

2535Non-pandoc extensions

2536---------------------

2537

2538The following markdown syntax extensions are not enabled by default

2539in pandoc, but may be enabled by adding `+EXTENSION` to the format

2540name, where `EXTENSION` is the name of the extension. Thus, for

2541example, `markdown+hard_line_breaks` is markdown with hard line breaks.

2542

2543**Extension: `lists_without_preceding_blankline`**\

2544Allow a list to occur right after a paragraph, with no intervening

2545blank space.

2546

2547**Extension: `hard_line_breaks`**\

2548Causes all newlines within a paragraph to be interpreted as hard line

2549breaks instead of spaces.

2550

2551**Extension: `ignore_line_breaks`**\

2552Causes newlines within a paragraph to be ignored, rather than being

2553treated as spaces or as hard line breaks. This option is intended for

2554use with East Asian languages where spaces are not used between words,

2555but text is divided into lines for readability.

2556

2557**Extension: `tex_math_single_backslash`**\

2558Causes anything between `$` and `$` to be interpreted as inline

2559TeX math, and anything between `\[` and `\]` to be interpreted

2560as display TeX math. Note: a drawback of this extension is that

2561it precludes escaping `(` and `[`.

2562

2563**Extension: `tex_math_double_backslash`**\

2564Causes anything between `\$` and `\$` to be interpreted as inline

2565TeX math, and anything between `\\[` and `\\]` to be interpreted

2566as display TeX math.

2567

2568**Extension: `markdown_attribute`**\

2569By default, pandoc interprets material inside block-level tags as markdown.

2570This extension changes the behavior so that markdown is only parsed

2571inside block-level tags if the tags have the attribute `markdown=1`.

2572

2573**Extension: `mmd_title_block`**\

2574Enables a [MultiMarkdown] style title block at the top of

2575the document, for example:

2576

2577 Title: My title

2578 Author: John Doe

2579 Date: September 1, 2008

2580 Comment: This is a sample mmd title block, with

2581 a field spanning multiple lines.

2582

2583See the MultiMarkdown documentation for details. If `pandoc_title_block` or

2584`yaml_metadata_block` is enabled, it will take precedence over

2585`mmd_title_block`.

2586

2587 [MultiMarkdown]: http://fletcherpenney.net/multimarkdown/

2588

2589**Extension: `abbreviations`**\

2590Parses PHP Markdown Extra abbreviation keys, like

2591

2592 *[HTML]: Hyper Text Markup Language

2593

2594Note that the pandoc document model does not support

2595abbreviations, so if this extension is enabled, abbreviation keys are

2596simply skipped (as opposed to being parsed as paragraphs).

2597

2598**Extension: `autolink_bare_uris`**\

2599Makes all absolute URIs into links, even when not surrounded by

2600pointy braces `<...>`.

2601

2602**Extension: `ascii_identifiers`**\

2603Causes the identifiers produced by `auto_identifiers` to be pure ASCII.

2604Accents are stripped off of accented latin letters, and non-latin

2605letters are omitted.

2606

2607**Extension: `link_attributes`**\

2608Parses multimarkdown style key-value attributes on link and image references.

2609Note that pandoc's internal document model provides nowhere to put

2610these, so they are presently just ignored.

2611

2612**Extension: `mmd_header_identifiers`**\

2613Parses multimarkdown style header identifiers (in square brackets,

2614after the header but before any trailing `#`s in an ATX header).

2615

2616Markdown variants

2617-----------------

2618

2619In addition to pandoc's extended markdown, the following markdown

2620variants are supported:

2621

2622`markdown_phpextra` (PHP Markdown Extra)

2623: `footnotes`, `pipe_tables`, `raw_html`, `markdown_attribute`,

2624 `fenced_code_blocks`, `definition_lists`, `intraword_underscores`,

2625 `header_attributes`, `abbreviations`.

2626

2627`markdown_github` (Github-flavored Markdown)

2628: `pipe_tables`, `raw_html`, `tex_math_single_backslash`,

2629 `fenced_code_blocks`, `fenced_code_attributes`, `auto_identifiers`,

2630 `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`,

2631 `intraword_underscores`, `strikeout`, `hard_line_breaks`

2632

2633`markdown_mmd` (MultiMarkdown)

2634: `pipe_tables` `raw_html`, `markdown_attribute`, `link_attributes`,

2635 `raw_tex`, `tex_math_double_backslash`, `intraword_underscores`,

2636 `mmd_title_block`, `footnotes`, `definition_lists`,

2637 `all_symbols_escapable`, `implicit_header_references`,

2638 `auto_identifiers`, `mmd_header_identifiers`

2639

2640`markdown_strict` (Markdown.pl)

2641: `raw_html`

2642

2643Extensions with formats other than markdown

2644-------------------------------------------

2645

2646Some of the extensions discussed above can be used with formats

2647other than markdown:

2648

2649* `auto_identifiers` can be used with `latex`, `rst`, `mediawiki`,

2650 and `textile` input (and is used by default).

2651

2652* `tex_math_dollars`, `tex_math_single_backslash`, and

2653 `tex_math_double_backslash` can be used with `html` input.

2654 (This is handy for reading web pages formatted using MathJax,

2655 for example.)

2656

2657Producing slide shows with Pandoc

2658=================================

2659

2660You can use Pandoc to produce an HTML + javascript slide presentation

2661that can be viewed via a web browser. There are five ways to do this,

2662using [S5], [DZSlides], [Slidy], [Slideous], or [reveal.js].

2663You can also produce a PDF slide show using LaTeX [beamer].

2664

2665Here's the markdown source for a simple slide show, `habits.txt`:

2666

2667 % Habits

2668 % John Doe

2669 % March 22, 2005

2670

2671 # In the morning

2672

2673 ## Getting up

2674

2675 - Turn off alarm

2676 - Get out of bed

2677

2678 ## Breakfast

2679

2680 - Eat eggs

2681 - Drink coffee

2682

2683 # In the evening

2684

2685 ## Dinner

2686

2687 - Eat spaghetti

2688 - Drink wine

2689

2690 ------------------

2691

2692 ![picture of spaghetti](images/spaghetti.jpg)

2693

2694 ## Going to sleep

2695

2696 - Get in bed

2697 - Count sheep

2698

2699To produce an HTML/javascript slide show, simply type

2700

2701 pandoc -t FORMAT -s habits.txt -o habits.html

2702

2703where `FORMAT` is either `s5`, `slidy`, `slideous`, `dzslides`, or `revealjs`.

2704

2705For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with the

2706`-s/--standalone` option embeds a link to javascripts and CSS files, which are

2707assumed to be available at the relative path `s5/default` (for S5), `slideous`

2708(for Slideous), `reveal.js` (for reveal.js), or at the Slidy website at

2709`w3.org` (for Slidy). (These paths can be changed by setting the `slidy-url`,

2710`slideous-url`, `revealjs-url`, or `s5-url` variables; see `--variable`,

2711above.) For DZSlides, the (relatively short) javascript and css are included in

2712the file by default.

2713

2714With all HTML slide formats, the `--self-contained` option can be used to

2715produce a single file that contains all of the data necessary to display the

2716slide show, including linked scripts, stylesheets, images, and videos.

2717

2718To produce a PDF slide show using beamer, type

2719

2720 pandoc -t beamer habits.txt -o habits.pdf

2721

2722Note that a reveal.js slide show can also be converted to a PDF

2723by printing it to a file from the browser.

2724

2725Structuring the slide show

2726--------------------------

2727

2728By default, the *slide level* is the highest header level in

2729the hierarchy that is followed immediately by content, and not another

2730header, somewhere in the document. In the example above, level 1 headers

2731are always followed by level 2 headers, which are followed by content,

2732so 2 is the slide level. This default can be overridden using

2733the `--slide-level` option.

2734

2735The document is carved up into slides according to the following

2736rules:

2737

2738 * A horizontal rule always starts a new slide.

2739

2740 * A header at the slide level always starts a new slide.

2741

2742 * Headers *below* the slide level in the hierarchy create

2743 headers *within* a slide.

2744

2745 * Headers *above* the slide level in the hierarchy create

2746 "title slides," which just contain the section title

2747 and help to break the slide show into sections.

2748

2749 * A title page is constructed automatically from the document's title

2750 block, if present. (In the case of beamer, this can be disabled

2751 by commenting out some lines in the default template.)

2752

2753These rules are designed to support many different styles of slide show. If

2754you don't care about structuring your slides into sections and subsections,

2755you can just use level 1 headers for all each slide. (In that case, level 1

2756will be the slide level.) But you can also structure the slide show into

2757sections, as in the example above.

2758

2759Note: in reveal.js slide shows, if slide level is 2, a two-dimensional

2760layout will be produced, with level 1 headers building horizontally

2761and level 2 headers building vertically. It is not recommended that

2762you use deeper nesting of section levels with reveal.js.

2763

2764Incremental lists

2765-----------------

2766

2767By default, these writers produces lists that display "all at once."

2768If you want your lists to display incrementally (one item at a time),

2769use the `-i` option. If you want a particular list to depart from the

2770default (that is, to display incrementally without the `-i` option and

2771all at once with the `-i` option), put it in a block quote:

2772

2773 > - Eat spaghetti

2774 > - Drink wine

2775

2776In this way incremental and nonincremental lists can be mixed in

2777a single document.

2778

2779Inserting pauses

2780----------------

2781

2782You can add "pauses" within a slide by including a paragraph containing

2783three dots, separated by spaces:

2784

2785 # Slide with a pause

2786

2787 content before the pause

2788

2789 . . .

2790

2791 content after the pause

2792

2793Styling the slides

2794------------------

2795

2796You can change the style of HTML slides by putting customized CSS files

2797in `$DATADIR/s5/default` (for S5), `$DATADIR/slidy` (for Slidy),

2798or `$DATADIR/slideous` (for Slideous),

2799where `$DATADIR` is the user data directory (see `--data-dir`, above).

2800The originals may be found in pandoc's system data directory (generally

2801`$CABALDIR/pandoc-VERSION/s5/default`). Pandoc will look there for any

2802files it does not find in the user data directory.

2803

2804For dzslides, the CSS is included in the HTML file itself, and may

2805be modified there.

2806

2807For reveal.js, themes can be used by setting the `theme` variable,

2808for example:

2809

2810 -V theme=moon

2811

2812Or you can specify a custom stylesheet using the `--css` option.

2813

2814To style beamer slides, you can specify a beamer "theme" or "colortheme"

2815using the `-V` option:

2816

2817 pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf

2818

2819Note that header attributes will turn into slide attributes

2820(on a `<div>` or `<section>`) in HTML slide formats, allowing you

2821to style individual slides. In Beamer, the only header attribute

2822that affects slides is the `allowframebreaks` class, which sets the

2823`allowframebreaks` option, causing multiple slides to be created

2824if the content overfills the frame. This is recommended especially for

2825bibliographies:

2826

2827 # References {.allowframebreaks}

2828

2829Speaker notes

2830-------------

2831

2832reveal.js has good support for speaker notes. You can add notes to your

2833markdown document thus:

2834

2835 <div class="notes">

2836 This is my note.

2837

2838 - It can contain markdown

2839 - like this list

2840

2841 </div>

2842

2843To show the notes window, press `s` while viewing the presentation.

2844Notes are not yet supported for other slide formats, but the notes

2845will not appear on the slides themselves.

2846

2847EPUB Metadata

2848=============

2849

2850EPUB metadata may be specified using the `--epub-metadata` option, but

2851if the source document is markdown, it is better to use a YAML metadata

2852block. Here is an example:

2853

2854 ---

2855 title:

2856 - type: main

2857 text: My Book

2858 - type: subtitle

2859 text: An investigation of metadata

2860 creator:

2861 - role: author

2862 text: John Smith

2863 - role: editor

2864 text: Sarah Jones

2865 identifier:

2866 - scheme: DOI

2867 text: doi:10.234234.234/33

2868 publisher: My Press

2870 ...

2871

2872The following fields are recognized:

2873

2874`identifier`

2875 ~ Either a string value or an object with fields `text` and

2876 `scheme`. Valid values for `scheme` are `ISBN-10`,

2877 `GTIN-13`, `UPC`, `ISMN-10`, `DOI`, `LCCN`, `GTIN-14`,

2878 `ISBN-13`, `Legal deposit number`, `URN`, `OCLC`,

2879 `ISMN-13`, `ISBN-A`, `JP`, `OLCC`.

2880`title`

2881 ~ Either a string value, or an object with fields `file-as` and

2882 `type`, or a list of such objects. Valid values for `type` are

2883 `main`, `subtitle`, `short`, `collection`, `edition`, `extended`.

2884`creator`

2885 ~ Either a string value, or an object with fields `role`, `file-as`,

2886 and `text`, or a list of such objects. Valid values for `role` are

2887 [marc relators](http://www.loc.gov/marc/relators/relaterm.html), but

2888 pandoc will attempt to translate the human-readable versions

2889 (like "author" and "editor") to the appropriate marc relators.

2890`contributor`

2891 ~ Same format as `creator`.

2892`date`

2893 ~ A string value in `YYYY-MM-DD` format. (Only the year is necessary.)

2894 Pandoc will attempt to convert other common date formats.

2895`language`

2896 ~ A string value in [RFC5646] format. Pandoc will default to the local

2897 language if nothing is specified.

2898`subject`

2899 ~ A string value or a list of such values.

2900`description`

2901 ~ A string value.

2902`type`

2903 ~ A string value.

2904`format`

2905 ~ A string value.

2906`relation`

2907 ~ A string value.

2908`coverage`

2909 ~ A string value.

2910`rights`

2911 ~ A string value.

2912`cover-image`

2913 ~ A string value (path to cover image).

2914`stylesheet`

2915 ~ A string value (path to CSS stylesheet).

2916

2917Literate Haskell support

2918========================

2919

2920If you append `+lhs` (or `+literate_haskell`) to an appropriate input or output

2921format (`markdown`, `markdown_strict`, `rst`, or `latex` for input or output;

2922`beamer`, `html` or `html5` for output only), pandoc will treat the document as

2923literate Haskell source. This means that

2924

2925 - In markdown input, "bird track" sections will be parsed as Haskell

2926 code rather than block quotations. Text between `\begin{code}`

2927 and `\end{code}` will also be treated as Haskell code.

2928

2929 - In markdown output, code blocks with classes `haskell` and `literate`

2930 will be rendered using bird tracks, and block quotations will be

2931 indented one space, so they will not be treated as Haskell code.

2932 In addition, headers will be rendered setext-style (with underlines)

2933 rather than atx-style (with '#' characters). (This is because ghc

2934 treats '#' characters in column 1 as introducing line numbers.)

2935

2936 - In restructured text input, "bird track" sections will be parsed

2937 as Haskell code.

2938

2939 - In restructured text output, code blocks with class `haskell` will

2940 be rendered using bird tracks.

2941

2942 - In LaTeX input, text in `code` environments will be parsed as

2943 Haskell code.

2944

2945 - In LaTeX output, code blocks with class `haskell` will be rendered

2946 inside `code` environments.

2947

2948 - In HTML output, code blocks with class `haskell` will be rendered

2949 with class `literatehaskell` and bird tracks.

2950

2951Examples:

2952

2953 pandoc -f markdown+lhs -t html

2954

2955reads literate Haskell source formatted with markdown conventions and writes

2956ordinary HTML (without bird tracks).

2957

2958 pandoc -f markdown+lhs -t html+lhs

2959

2960writes HTML with the Haskell code in bird tracks, so it can be copied

2961and pasted as literate Haskell source.

2962

2963Custom writers

2964==============

2965

2966Pandoc can be extended with custom writers written in [lua]. (Pandoc

2967includes a lua interpreter, so lua need not be installed separately.)

2968

2969To use a custom writer, simply specify the path to the lua script

2970in place of the output format. For example:

2971

2972 pandoc -t data/sample.lua

2973

2974Creating a custom writer requires writing a lua function for each

2975possible element in a pandoc document. To get a documented example

2976which you can modify according to your needs, do

2977

2978 pandoc --print-default-data-file sample.lua

2979

2980Authors

2981=======

2982

2984[GPL], version 2 or greater. This software carries no warranty of

2985any kind. (See COPYRIGHT for full copyright and warranty notices.)

2986Other contributors include Recai Oktaş, Paulo Tanimoto, Peter Wang,

2987Andrea Rossato, Eric Kow, infinity0x, Luke Plant, shreevatsa.public,

2988Puneeth Chaganti, Paul Rivier, rodja.trappe, Bradley Kuhn, thsutton,

2989Nathan Gass, Jonathan Daugherty, Jérémy Bobbio, Justin Bogner, qerub,

2990Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

2991Latter, Ralf Stephan, Eric Seidel, B. Scott Michel, Gavin Beatty,

2992Sergey Astanin, Arlo O'Keeffe, Denis Laxalde, Brent Yorgey, David Lazar,

2993Jamie F. Olson, Matthew Pickering, Albert Krewinkel, mb21, Jesse

2994Rosenthal.

2995

2996[markdown]: http://daringfireball.net/projects/markdown/

2997[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html

2998[S5]: http://meyerweb.com/eric/tools/s5/

2999[Slidy]: http://www.w3.org/Talks/Tools/Slidy/

3000[Slideous]: http://goessner.net/articles/slideous/

3001[HTML]: http://www.w3.org/TR/html40/

3002[HTML 5]: http://www.w3.org/TR/html5/

3003[XHTML]: http://www.w3.org/TR/xhtml1/

3004[LaTeX]: http://www.latex-project.org/

3005[beamer]: http://www.tex.ac.uk/CTAN/macros/latex/contrib/beamer

3006[ConTeXt]: http://www.pragma-ade.nl/

3007[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format

3008[DocBook]: http://www.docbook.org/

3009[OPML]: http://dev.opml.org/spec2.html

3010[OpenDocument]: http://opendocument.xml.org/

3011[ODT]: http://en.wikipedia.org/wiki/OpenDocument

3012[Textile]: http://redcloth.org/textile

3013[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting

3014[Haddock markup]: http://www.haskell.org/haddock/doc/html/ch03s08.html

3015[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html

3016[Haskell]: http://www.haskell.org/

3017[GNU Texinfo]: http://www.gnu.org/software/texinfo/

3018[Emacs Org-Mode]: http://orgmode.org

3019[AsciiDoc]: http://www.methods.co.nz/asciidoc/

3020[EPUB]: http://www.idpf.org/

3021[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"

3022[DZSlides]: http://paulrouget.com/dzslides/

3023[ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime

3024[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx

3025[PDF]: http://www.adobe.com/pdf/

3026[reveal.js]: http://lab.hakim.se/reveal-js/

3027[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1

3028[lua]: http://www.lua.org

3029[marc relators]: http://www.loc.gov/marc/relators/relaterm.html

3030[RFC5646]: http://tools.ietf.org/html/rfc5646

3031[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf