README · typeable/pandoc

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

1477

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

1479

1480

1481### Numbered example lists ###

1482

1483**Extension: `example_lists`**

1484

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

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

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

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

1489where the last stopped. So, for example:

1490

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

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

1493

1494 Explanation of examples.

1495

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

1497

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

1499document:

1500

1501 (@good) This is a good example.

1502

1503 As (@good) illustrates, ...

1504

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

1506or hyphens.

1507

1508

1509### Compact and loose lists ###

1510

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

1512cases" involving lists. Consider this source:

1513

1514 + First

1515 + Second:

1516 - Fee

1517 - Fie

1518 - Foe

1519

1520 + Third

1521

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

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

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

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

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

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

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

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

1530behavior is consistent with the official markdown syntax description,

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

1532

1533

1534### Ending a list ###

1535

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

1537

1538 - item one

1539 - item two

1540

1541 { my code block }

1542

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

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

1545a code block.

1546

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

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

1549any format:

1550

1551 - item one

1552 - item two

1553

1554

1555

1556 { my code block }

1557

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

1559of one big list:

1560

1561 1. one

1562 2. two

1563 3. three

1564

1565

1566

1567 1. uno

1568 2. dos

1569 3. tres

1570

1571Horizontal rules

1572----------------

1573

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

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

1577 * * * *

1579 ---------------

1582Tables

1583------

1584

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

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

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

1588

1589### Simple tables

1590

1591**Extension: `simple_tables`, `table_captions`**

1592

1593Simple tables look like this:

1594

1595 Right Left Center Default

1596 ------- ------ ---------- -------

1597 12 12 12 12

1598 123 123 123 123

1599 1 1 1 1

1600

1601 Table: Demonstration of simple table syntax.

1602

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

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

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

1606

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

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

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

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

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

1612 the column is centered.

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

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

1615

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

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

1618

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

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

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

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

1623before or after the table.

1624

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

1626to end the table. For example:

1627

1628 ------- ------ ---------- -------

1629 12 12 12 12

1630 123 123 123 123

1631 1 1 1 1

1632 ------- ------ ---------- -------

1633

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

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

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

1637

1638### Multiline tables

1639

1640**Extension: `multiline_tables`, `table_captions`**

1641

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

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

1644not supported). Here is an example:

1645

1646 -------------------------------------------------------------

1647 Centered Default Right Left

1648 Header Aligned Aligned Aligned

1649 ----------- ------- --------------- -------------------------

1650 First row 12.0 Example of a row that

1651 spans multiple lines.

1652

1653 Second row 5.0 Here's another one. Note

1654 the blank line between

1655 rows.

1656 -------------------------------------------------------------

1657

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

1659 multiple lines.

1660

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

1662

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

1664 (unless the headers are omitted).

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

1666 - The rows must be separated by blank lines.

1667

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

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

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

1671output, try widening it in the markdown source.

1672

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

1674

1675 ----------- ------- --------------- -------------------------

1676 First row 12.0 Example of a row that

1677 spans multiple lines.

1678

1679 Second row 5.0 Here's another one. Note

1680 the blank line between

1681 rows.

1682 ----------- ------- --------------- -------------------------

1683

1684 : Here's a multiline table without headers.

1685

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

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

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

1689

1690### Grid tables

1691

1692**Extension: `grid_tables`, `table_captions`**

1693

1694Grid tables look like this:

1695

1696 : Sample grid table.

1697

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

1699 | Fruit | Price | Advantages |

1700 +===============+===============+====================+

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

1702 | | | - bright color |

1703 +---------------+---------------+--------------------+

1704 | Oranges | $2.10 | - cures scurvy |

1705 | | | - tasty |

1706 +---------------+---------------+--------------------+

1707

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

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

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

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

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

1713

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

1715

1716### Pipe tables

1717

1718**Extension: `pipe_tables`, `table_captions`**

1719

1720Pipe tables look like this:

1721

1723 |------:|:-----|---------|:------:|

1724 | 12 | 12 | 12 | 12 |

1725 | 123 | 123 | 123 | 123 |

1726 | 1 | 1 | 1 | 1 |

1727

1728 : Demonstration of simple table syntax.

1729

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

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

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

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

1734it defines column alignments.

1735

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

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

1738legal (though ugly) pipe table:

1739

1740 fruit| price

1741 -----|-----:

1742 apple|2.05

1743 pear|1.37

1744 orange|3.09

1745

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

1747and lists, and cannot span multiple lines.

1748

1749 [the same as in PHP markdown extra]:

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

1751

1752Note: Pandoc also recognizes pipe tables of the following

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

1754

1755 | One | Two |

1756 |-----+-------|

1757 | my | table |

1758 | is | nice |

1759

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

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

1762you'll need to add colons as above.

1763

1764Title block

1765-----------

1766

1767**Extension: `pandoc_title_block`**

1768

1769If the file begins with a title block

1770

1771 % title

1772 % author(s) (separated by semicolons)

1773 % date

1774

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

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

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

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

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

1780

1781 %

1782 % Author

1783

1784 % My title

1785 %

1786 % June 15, 2006

1787

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

1789begin with leading space, thus:

1790

1791 % My title

1792 on multiple lines

1793

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

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

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

1797

1798 % Author One

1799 Author Two

1800

1801 % Author One; Author Two

1802

1803 % Author One;

1804 Author Two

1805

1806The date must fit on one line.

1807

1808All three metadata fields may contain standard inline formatting

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

1810

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

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

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

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

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

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

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

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

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

1820be used by itself as the HTML title.

1821

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

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

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

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

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

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

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

1829text. Thus,

1830

1831 % PANDOC(1)

1832

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

1834

1835 % PANDOC(1) Pandoc User Manuals

1836

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

1838

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

1840

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

1842

1843YAML metadata block

1844-------------------

1845

1846**Extension: `yaml_metadata_block`**

1847

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

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

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

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

1852line. (Note that, because of the way pandoc concatenates input files when

1853several are provided, you may also keep the metadata in a separate YAML file

1854and pass it to pandoc as an argument, along with your markdown files:

1855

1856 pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html

1857

1858Just be sure that the YAML file begins with `---` and ends with `---` or

1859`...`.)

1860

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

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

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

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

1865given a role by external processors.)

1866

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

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

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

1870

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

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

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

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

1875when the field contains blank lines:

1876

1877 ---

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

1879 author:

1880 - name: Author One

1881 affiliation: University of Somewhere

1882 - name: Author Two

1883 affiliation: University of Nowhere

1884 tags: [nothing, nothingness]

1885 abstract: |

1886 This is the abstract.

1887

1888 It consists of two paragraphs.

1889 ...

1890

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

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

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

1894

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

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

1897

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

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

1900custom template. For example:

1901

1902 $for(author)$

1903 $if(author.name)$

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

1905 $else$

1906 $author$

1907 $endif$

1908 $endfor$

1909

1910

1911Backslash escapes

1912-----------------

1913

1914**Extension: `all_symbols_escapable`**

1915

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

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

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

1919

1920 *\*hello\**

1921

1922one will get

1923

1924 <em>*hello*</em>

1925

1926instead of

1927

1928 <strong>hello</strong>

1929

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

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

1932

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

1934

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

1936will be used.)

1937

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

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

1940`\ `.

1941

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

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

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

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

1946two trailing spaces on a line.

1947

1948Backslash escapes do not work in verbatim contexts.

1949

1950Smart punctuation

1951-----------------

1952

1953**Extension**

1954

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

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

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

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

1959

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

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

1962

1963Inline formatting

1964-----------------

1965

1966### Emphasis ###

1967

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

1969

1970 This text is _emphasized with underscores_, and this

1971 is *emphasized with asterisks*.

1972

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

1974

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

1976

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

1978will not trigger emphasis:

1979

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

1981

1982**Extension: `intraword_underscores`**

1983

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

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

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

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

1988

1989 feas*ible*, not feas*able*.

1990

1991

1992### Strikeout ###

1993

1994**Extension: `strikeout`**

1995

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

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

1998

1999 This ~~is deleted text.~~

2000

2001

2002### Superscripts and subscripts ###

2003

2004**Extension: `superscript`, `subscript`**

2005

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

2007characters; subscripts may be written by surrounding the subscripted

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

2009

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

2011

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

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

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

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

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

2017

2018

2019### Verbatim ###

2020

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

2022

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

2024

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

2026

2027 Here is a literal backtick `` ` ``.

2028

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

2030backticks will be ignored.)

2031

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

2033of consecutive backticks (optionally followed by a space)

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

2035preceded by a space).

2036

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

2038work in verbatim contexts:

2039

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

2041

2042**Extension: `inline_code_attributes`**

2043

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

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

2046

2047 `<$>`{.haskell}

2048

2049### Small caps ###

2050

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

2052

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

2054

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

2056

2057Math

2058----

2059

2060**Extension: `tex_math_dollars`**

2061

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

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

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

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

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

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

2068

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

2070depends on the output format:

2071

2072Markdown, LaTeX, Org-Mode, ConTeXt

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

2074

2075reStructuredText

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

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

2078

2079AsciiDoc

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

2081

2082Texinfo

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

2084

2085groff man

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

2087

2088MediaWiki, DokuWiki

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

2090

2091Textile

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

2093

2094RTF, OpenDocument, ODT

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

2096 and will otherwise appear verbatim.

2097

2098Docbook

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

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

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

2102

2103Docx

2104 ~ It will be rendered using OMML math markup.

2105

2106FictionBook2

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

2108 using Google Charts or other compatible web service, downloaded

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

2110

2111HTML, Slidy, DZSlides, S5, EPUB

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

2113 command-line options selected:

2114

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

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

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

2118 styled differently from the surrounding text if needed.

2119

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

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

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

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

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

2125 verbatim between `$` characters.)

2126

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

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

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

2130 it.

2131

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

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

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

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

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

2137

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

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

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

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

2142 procedure is:

2143

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

2145 gladtex -d myfile-images myfile.htex

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

2147

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

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

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

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

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

2153

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

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

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

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

2158

2159Raw HTML

2160--------

2161

2162**Extension: `raw_html`**

2163

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

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

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

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

2168be disabled if desired.)

2169

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

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

2172formats.

2173

2174**Extension: `markdown_in_html_blocks`**

2175

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

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

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

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

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

2181

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

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

2184Thus, for example, Pandoc will turn

2185

2186 <table>

2187 <tr>

2188 <td>*one*</td>

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

2190 </tr>

2191 </table>

2192

2193into

2194

2195 <table>

2196 <tr>

2197 <td><em>one</em></td>

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

2199 </tr>

2200 </table>

2201

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

2203

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

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

2206

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

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

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

2210from being interpreted as markdown.

2211

2212Raw TeX

2213-------

2214

2215**Extension: `raw_tex`**

2216

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

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

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

2220LaTeX to include BibTeX citations:

2221

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

2223

2224Note that in LaTeX environments, like

2225

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

2227 Age & Frequency \\ \hline

2228 18--25 & 15 \\

2229 26--35 & 33 \\

2230 36--45 & 22 \\ \hline

2231 \end{tabular}

2232

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

2234LaTeX, not as markdown.

2235

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

2237and ConTeXt.

2238

2239LaTeX macros

2240------------

2241

2242**Extension: `latex_macros`**

2243

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

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

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

2247not just LaTeX:

2248

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

2250

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

2252

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

2254unchanged to the output.

2255

2256

2257Links

2258-----

2259

2260Markdown allows links to be specified in several ways.

2261

2262### Automatic links ###

2263

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

2265will become a link:

2266

2267 <http://google.com>

2268 <sam@green.eggs.ham>

2269

2270### Inline links ###

2271

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

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

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

2275

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

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

2278

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

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

2281

2282

2283### Reference links ###

2284

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

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

2287before or after the link).

2288

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

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

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

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

2293parentheses.

2294

2295Here are some examples:

2296

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

2298 [my label 2]: /foo

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

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

2301

2302The URL may optionally be surrounded by angle brackets:

2303

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

2305

2306The title may go on the next line:

2307

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

2309 "The free software foundation"

2310

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

2312

2313 Here is [my link][FOO]

2314

2315 [Foo]: /bar/baz

2316

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

2318empty, or omitted entirely:

2319

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

2321

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

2323

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

2325reference link definitions cannot occur in nested constructions

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

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

2328not in most other implementations:

2329

2330 > My block [quote].

2331 >

2332 > [quote]: /foo

2333

2334### Internal links

2335

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

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

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

2339For example:

2340

2341 See the [Introduction](#introduction).

2342

2343or

2344

2345 See the [Introduction].

2346

2347 [Introduction]: #introduction

2348

2349Internal links are currently supported for HTML formats (including

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

2351

2352Images

2353------

2354

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

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

2357

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

2359

2360 ![movie reel]

2361

2362 [movie reel]: movie.gif

2363

2364### Pictures with captions ###

2365

2366**Extension: `implicit_figures`**

2367

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

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

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

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

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

2373

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

2375

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

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

2378 itself, with no caption.

2379

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

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

2382nonbreaking space after the image:

2383

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

2385

2386

2387Footnotes

2388---------

2389

2390**Extension: `footnotes`**

2391

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

2393

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

2395

2396 [^1]: Here is the footnote.

2397

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

2399

2400 Subsequent paragraphs are indented to show that they

2401 belong to the previous footnote.

2402

2403 { some.code }

2404

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

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

2407 multi-paragraph list items.

2408

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

2410 isn't indented.

2411

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

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

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

2415will be numbered sequentially.

2416

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

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

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

2420

2421**Extension: `inline_notes`**

2422

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

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

2425

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

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

2428 note.]

2429

2430Inline and regular footnotes may be mixed freely.

2431

2432

2433Citations

2434---------

2435

2436**Extension: `citations`**

2437

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

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

2440

2441 pandoc --filter pandoc-citeproc myinput.txt

2442

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

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

2445The bibliography may have any of these formats:

2446

2447 Format File extension

2448 ------------ --------------

2449 MODS .mods

2450 BibLaTeX .bib

2451 BibTeX .bibtex

2452 RIS .ris

2453 EndNote .enl

2454 EndNote XML .xml

2455 ISI .wos

2456 MEDLINE .medline

2457 Copac .copac

2458 JSON citeproc .json

2459

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

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

2462

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

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

2465for example:

2466

2467 ---

2468 references:

2469 - id: fenner2012a

2470 title: One-click science marketing

2471 author:

2472 - family: Fenner

2473 given: Martin

2474 container-title: Nature Materials

2475 volume: 11

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

2477 DOI: 10.1038/nmat3283

2478 issue: 4

2479 publisher: Nature Publishing Group

2480 page: 261-263

2481 type: article-journal

2482 issued:

2483 year: 2012

2484 month: 3

2485 ...

2486

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

2488these from a MODS reference collection.)

2489

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

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

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

2493modifying CSL styles can be found at

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

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

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

2497

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

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

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

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

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

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

2504

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

2506

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

2508

2509 Blah blah [@smith04; @doe99].

2510

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

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

2513author is already mentioned in the text:

2514

2515 Smith says blah [-@smith04].

2516

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

2518

2519 @smith04 says blah.

2520

2521 @smith04 [p. 33] says blah.

2522

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

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

2525document with an appropriate header:

2526

2527 last paragraph...

2528

2529 # References

2530

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

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

2533section will not be numbered.

2534

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

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

2537field and put the citations there:

2538

2539 ---

2540 nocite: |

2541 @item1, @item2

2542 ...

2543

2544 @item3

2545

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

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

2548`item3`.

2549

2550Non-pandoc extensions

2551---------------------

2552

2553The following markdown syntax extensions are not enabled by default

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

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

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

2557

2558**Extension: `lists_without_preceding_blankline`**\

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

2560blank space.

2561

2562**Extension: `hard_line_breaks`**\

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

2564breaks instead of spaces.

2565

2566**Extension: `ignore_line_breaks`**\

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

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

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

2570but text is divided into lines for readability.

2571

2572**Extension: `tex_math_single_backslash`**\

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

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

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

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

2577

2578**Extension: `tex_math_double_backslash`**\

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

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

2581as display TeX math.

2582

2583**Extension: `markdown_attribute`**\

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

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

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

2587

2588**Extension: `mmd_title_block`**\

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

2590the document, for example:

2591

2592 Title: My title

2593 Author: John Doe

2594 Date: September 1, 2008

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

2596 a field spanning multiple lines.

2597

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

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

2600`mmd_title_block`.

2601

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

2603

2604**Extension: `abbreviations`**\

2605Parses PHP Markdown Extra abbreviation keys, like

2606

2607 *[HTML]: Hyper Text Markup Language

2608

2609Note that the pandoc document model does not support

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

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

2612

2613**Extension: `autolink_bare_uris`**\

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

2615pointy braces `<...>`.

2616

2617**Extension: `ascii_identifiers`**\

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

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

2620letters are omitted.

2621

2622**Extension: `link_attributes`**\

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

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

2625these, so they are presently just ignored.

2626

2627**Extension: `mmd_header_identifiers`**\

2628Parses multimarkdown style header identifiers (in square brackets,

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

2630

2631Markdown variants

2632-----------------

2633

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

2635variants are supported:

2636

2637`markdown_phpextra` (PHP Markdown Extra)

2638: `footnotes`, `pipe_tables`, `raw_html`, `markdown_attribute`,

2639 `fenced_code_blocks`, `definition_lists`, `intraword_underscores`,

2640 `header_attributes`, `abbreviations`.

2641

2642`markdown_github` (Github-flavored Markdown)

2643: `pipe_tables`, `raw_html`, `tex_math_single_backslash`,

2644 `fenced_code_blocks`, `auto_identifiers`,

2645 `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`,

2646 `intraword_underscores`, `strikeout`, `hard_line_breaks`

2647

2648`markdown_mmd` (MultiMarkdown)

2649: `pipe_tables` `raw_html`, `markdown_attribute`, `link_attributes`,

2650 `raw_tex`, `tex_math_double_backslash`, `intraword_underscores`,

2651 `mmd_title_block`, `footnotes`, `definition_lists`,

2652 `all_symbols_escapable`, `implicit_header_references`,

2653 `auto_identifiers`, `mmd_header_identifiers`

2654

2655`markdown_strict` (Markdown.pl)

2656: `raw_html`

2657

2658Extensions with formats other than markdown

2659-------------------------------------------

2660

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

2662other than markdown:

2663

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

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

2666

2667* `tex_math_dollars`, `tex_math_single_backslash`, and

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

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

2670 for example.)

2671

2672Producing slide shows with Pandoc

2673=================================

2674

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

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

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

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

2679

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

2681

2682 % Habits

2683 % John Doe

2684 % March 22, 2005

2685

2686 # In the morning

2687

2688 ## Getting up

2689

2690 - Turn off alarm

2691 - Get out of bed

2692

2693 ## Breakfast

2694

2695 - Eat eggs

2696 - Drink coffee

2697

2698 # In the evening

2699

2700 ## Dinner

2701

2702 - Eat spaghetti

2703 - Drink wine

2704

2705 ------------------

2706

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

2708

2709 ## Going to sleep

2710

2711 - Get in bed

2712 - Count sheep

2713

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

2715

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

2717

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

2719

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

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

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

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

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

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

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

2727the file by default.

2728

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

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

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

2732

2733To produce a PDF slide show using beamer, type

2734

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

2736

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

2738by printing it to a file from the browser.

2739

2740Structuring the slide show

2741--------------------------

2742

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

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

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

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

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

2748the `--slide-level` option.

2749

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

2751rules:

2752

2753 * A horizontal rule always starts a new slide.

2754

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

2756

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

2758 headers *within* a slide.

2759

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

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

2762 and help to break the slide show into sections.

2763

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

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

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

2767

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

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

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

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

2772sections, as in the example above.

2773

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

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

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

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

2778

2779Incremental lists

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

2781

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

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

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

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

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

2787

2788 > - Eat spaghetti

2789 > - Drink wine

2790

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

2792a single document.

2793

2794Inserting pauses

2795----------------

2796

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

2798three dots, separated by spaces:

2799

2800 # Slide with a pause

2801

2802 content before the pause

2803

2804 . . .

2805

2806 content after the pause

2807

2808Styling the slides

2809------------------

2810

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

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

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

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

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

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

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

2818

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

2820be modified there.

2821

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

2823for example:

2824

2825 -V theme=moon

2826

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

2828

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

2830using the `-V` option:

2831

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

2833

2834Note that header attributes will turn into slide attributes

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

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

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

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

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

2840bibliographies:

2841

2842 # References {.allowframebreaks}

2843

2844Speaker notes

2845-------------

2846

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

2848markdown document thus:

2849

2850 <div class="notes">

2851 This is my note.

2852

2853 - It can contain markdown

2854 - like this list

2855

2856 </div>

2857

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

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

2860will not appear on the slides themselves.

2861

2862EPUB Metadata

2863=============

2864

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

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

2867block. Here is an example:

2868

2869 ---

2870 title:

2871 - type: main

2872 text: My Book

2873 - type: subtitle

2874 text: An investigation of metadata

2875 creator:

2876 - role: author

2877 text: John Smith

2878 - role: editor

2879 text: Sarah Jones

2880 identifier:

2881 - scheme: DOI

2882 text: doi:10.234234.234/33

2883 publisher: My Press

2885 ...

2886

2887The following fields are recognized:

2888

2889`identifier`

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

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

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

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

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

2895`title`

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

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

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

2899`creator`

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

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

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

2903 pandoc will attempt to translate the human-readable versions

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

2905`contributor`

2906 ~ Same format as `creator`.

2907`date`

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

2909 Pandoc will attempt to convert other common date formats.

2910`language`

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

2912 language if nothing is specified.

2913`subject`

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

2915`description`

2916 ~ A string value.

2917`type`

2918 ~ A string value.

2919`format`

2920 ~ A string value.

2921`relation`

2922 ~ A string value.

2923`coverage`

2924 ~ A string value.

2925`rights`

2926 ~ A string value.

2927`cover-image`

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

2929`stylesheet`

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

2931

2932Literate Haskell support

2933========================

2934

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

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

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

2938literate Haskell source. This means that

2939

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

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

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

2943

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

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

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

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

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

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

2950

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

2952 as Haskell code.

2953

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

2955 be rendered using bird tracks.

2956

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

2958 Haskell code.

2959

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

2961 inside `code` environments.

2962

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

2964 with class `literatehaskell` and bird tracks.

2965

2966Examples:

2967

2968 pandoc -f markdown+lhs -t html

2969

2970reads literate Haskell source formatted with markdown conventions and writes

2971ordinary HTML (without bird tracks).

2972

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

2974

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

2976and pasted as literate Haskell source.

2977

2978Custom writers

2979==============

2980

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

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

2983

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

2985in place of the output format. For example:

2986

2987 pandoc -t data/sample.lua

2988

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

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

2991which you can modify according to your needs, do

2992

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

2994

2995Authors

2996=======

2997

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

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

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

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

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

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

3005Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

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

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

3009Rosenthal.

3010

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3029[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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