README · typeable/pandoc

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

1470

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

1472

1473

1474### Numbered example lists ###

1475

1476**Extension: `example_lists`**

1477

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

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

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

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

1482where the last stopped. So, for example:

1483

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

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

1486

1487 Explanation of examples.

1488

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

1490

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

1492document:

1493

1494 (@good) This is a good example.

1495

1496 As (@good) illustrates, ...

1497

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

1499or hyphens.

1500

1501

1502### Compact and loose lists ###

1503

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

1505cases" involving lists. Consider this source:

1506

1507 + First

1508 + Second:

1509 - Fee

1510 - Fie

1511 - Foe

1512

1513 + Third

1514

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

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

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

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

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

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

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

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

1523behavior is consistent with the official markdown syntax description,

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

1525

1526

1527### Ending a list ###

1528

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

1530

1531 - item one

1532 - item two

1533

1534 { my code block }

1535

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

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

1538a code block.

1539

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

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

1542any format:

1543

1544 - item one

1545 - item two

1546

1547

1548

1549 { my code block }

1550

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

1552of one big list:

1553

1554 1. one

1555 2. two

1556 3. three

1557

1558

1559

1560 1. uno

1561 2. dos

1562 3. tres

1563

1564Horizontal rules

1565----------------

1566

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

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

1570 * * * *

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

1575Tables

1576------

1577

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

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

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

1581

1582### Simple tables

1583

1584**Extension: `simple_tables`, `table_captions`**

1585

1586Simple tables look like this:

1587

1588 Right Left Center Default

1589 ------- ------ ---------- -------

1590 12 12 12 12

1591 123 123 123 123

1592 1 1 1 1

1593

1594 Table: Demonstration of simple table syntax.

1595

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

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

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

1599

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

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

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

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

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

1605 the column is centered.

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

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

1608

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

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

1611

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

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

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

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

1616before or after the table.

1617

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

1619to end the table. For example:

1620

1621 ------- ------ ---------- -------

1622 12 12 12 12

1623 123 123 123 123

1624 1 1 1 1

1625 ------- ------ ---------- -------

1626

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

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

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

1630

1631### Multiline tables

1632

1633**Extension: `multiline_tables`, `table_captions`**

1634

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

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

1637not supported). Here is an example:

1638

1639 -------------------------------------------------------------

1640 Centered Default Right Left

1641 Header Aligned Aligned Aligned

1642 ----------- ------- --------------- -------------------------

1643 First row 12.0 Example of a row that

1644 spans multiple lines.

1645

1646 Second row 5.0 Here's another one. Note

1647 the blank line between

1648 rows.

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

1650

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

1652 multiple lines.

1653

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

1655

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

1657 (unless the headers are omitted).

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

1659 - The rows must be separated by blank lines.

1660

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

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

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

1664output, try widening it in the markdown source.

1665

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

1667

1668 ----------- ------- --------------- -------------------------

1669 First row 12.0 Example of a row that

1670 spans multiple lines.

1671

1672 Second row 5.0 Here's another one. Note

1673 the blank line between

1674 rows.

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

1676

1677 : Here's a multiline table without headers.

1678

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

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

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

1682

1683### Grid tables

1684

1685**Extension: `grid_tables`, `table_captions`**

1686

1687Grid tables look like this:

1688

1689 : Sample grid table.

1690

1691 +---------------+---------------+--------------------+

1692 | Fruit | Price | Advantages |

1693 +===============+===============+====================+

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

1695 | | | - bright color |

1696 +---------------+---------------+--------------------+

1697 | Oranges | $2.10 | - cures scurvy |

1698 | | | - tasty |

1699 +---------------+---------------+--------------------+

1700

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

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

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

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

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

1706

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

1708

1709### Pipe tables

1710

1711**Extension: `pipe_tables`, `table_captions`**

1712

1713Pipe tables look like this:

1714

1716 |------:|:-----|---------|:------:|

1717 | 12 | 12 | 12 | 12 |

1718 | 123 | 123 | 123 | 123 |

1719 | 1 | 1 | 1 | 1 |

1720

1721 : Demonstration of simple table syntax.

1722

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

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

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

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

1727it defines column alignments.

1728

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

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

1731legal (though ugly) pipe table:

1732

1733 fruit| price

1734 -----|-----:

1735 apple|2.05

1736 pear|1.37

1737 orange|3.09

1738

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

1740and lists, and cannot span multiple lines.

1741

1742 [the same as in PHP markdown extra]:

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

1744

1745Note: Pandoc also recognizes pipe tables of the following

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

1747

1748 | One | Two |

1749 |-----+-------|

1750 | my | table |

1751 | is | nice |

1752

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

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

1755you'll need to add colons as above.

1756

1757Title block

1758-----------

1759

1760**Extension: `pandoc_title_block`**

1761

1762If the file begins with a title block

1763

1764 % title

1765 % author(s) (separated by semicolons)

1766 % date

1767

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

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

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

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

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

1773

1774 %

1775 % Author

1776

1777 % My title

1778 %

1779 % June 15, 2006

1780

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

1782begin with leading space, thus:

1783

1784 % My title

1785 on multiple lines

1786

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

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

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

1790

1791 % Author One

1792 Author Two

1793

1794 % Author One; Author Two

1795

1796 % Author One;

1797 Author Two

1798

1799The date must fit on one line.

1800

1801All three metadata fields may contain standard inline formatting

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

1803

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

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

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

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

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

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

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

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

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

1813be used by itself as the HTML title.

1814

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

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

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

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

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

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

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

1822text. Thus,

1823

1824 % PANDOC(1)

1825

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

1827

1828 % PANDOC(1) Pandoc User Manuals

1829

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

1831

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

1833

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

1835

1836YAML metadata block

1837-------------------

1838

1839**Extension: `yaml_metadata_block`**

1840

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

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

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

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

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

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

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

1848

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

1850

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

1852`...`.)

1853

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

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

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

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

1858given a role by external processors.)

1859

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

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

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

1863

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

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

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

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

1868when the field contains blank lines:

1869

1870 ---

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

1872 author:

1873 - name: Author One

1874 affiliation: University of Somewhere

1875 - name: Author Two

1876 affiliation: University of Nowhere

1877 tags: [nothing, nothingness]

1878 abstract: |

1879 This is the abstract.

1880

1881 It consists of two paragraphs.

1882 ...

1883

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

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

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

1887

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

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

1890

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

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

1893custom template. For example:

1894

1895 $for(author)$

1896 $if(author.name)$

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

1898 $else$

1899 $author$

1900 $endif$

1901 $endfor$

1902

1903

1904Backslash escapes

1905-----------------

1906

1907**Extension: `all_symbols_escapable`**

1908

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

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

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

1912

1913 *\*hello\**

1914

1915one will get

1916

1917 <em>*hello*</em>

1918

1919instead of

1920

1921 <strong>hello</strong>

1922

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

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

1925

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

1927

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

1929will be used.)

1930

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

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

1933`\ `.

1934

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

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

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

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

1939two trailing spaces on a line.

1940

1941Backslash escapes do not work in verbatim contexts.

1942

1943Smart punctuation

1944-----------------

1945

1946**Extension**

1947

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

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

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

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

1952

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

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

1955

1956Inline formatting

1957-----------------

1958

1959### Emphasis ###

1960

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

1962

1963 This text is _emphasized with underscores_, and this

1964 is *emphasized with asterisks*.

1965

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

1967

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

1969

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

1971will not trigger emphasis:

1972

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

1974

1975**Extension: `intraword_underscores`**

1976

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

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

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

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

1981

1982 feas*ible*, not feas*able*.

1983

1984

1985### Strikeout ###

1986

1987**Extension: `strikeout`**

1988

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

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

1991

1992 This ~~is deleted text.~~

1993

1994

1995### Superscripts and subscripts ###

1996

1997**Extension: `superscript`, `subscript`**

1998

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

2000characters; subscripts may be written by surrounding the subscripted

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

2002

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

2004

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

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

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

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

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

2010

2011

2012### Verbatim ###

2013

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

2015

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

2017

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

2019

2020 Here is a literal backtick `` ` ``.

2021

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

2023backticks will be ignored.)

2024

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

2026of consecutive backticks (optionally followed by a space)

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

2028preceded by a space).

2029

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

2031work in verbatim contexts:

2032

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

2034

2035**Extension: `inline_code_attributes`**

2036

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

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

2039

2040 `<$>`{.haskell}

2041

2042### Small caps ###

2043

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

2045

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

2047

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

2049

2050Math

2051----

2052

2053**Extension: `tex_math_dollars`**

2054

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

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

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

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

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

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

2061

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

2063depends on the output format:

2064

2065Markdown, LaTeX, Org-Mode, ConTeXt

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

2067

2068reStructuredText

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

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

2071

2072AsciiDoc

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

2074

2075Texinfo

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

2077

2078groff man

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

2080

2081MediaWiki, DokuWiki

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

2083

2084Textile

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

2086

2087RTF, OpenDocument, ODT

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

2089 and will otherwise appear verbatim.

2090

2091Docbook

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

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

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

2095

2096Docx

2097 ~ It will be rendered using OMML math markup.

2098

2099FictionBook2

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

2101 using Google Charts or other compatible web service, downloaded

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

2103

2104HTML, Slidy, DZSlides, S5, EPUB

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

2106 command-line options selected:

2107

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

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

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

2111 styled differently from the surrounding text if needed.

2112

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

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

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

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

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

2118 verbatim between `$` characters.)

2119

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

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

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

2123 it.

2124

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

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

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

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

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

2130

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

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

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

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

2135 procedure is:

2136

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

2138 gladtex -d myfile-images myfile.htex

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

2140

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

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

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

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

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

2146

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

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

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

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

2151

2152Raw HTML

2153--------

2154

2155**Extension: `raw_html`**

2156

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

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

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

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

2161be disabled if desired.)

2162

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

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

2165formats.

2166

2167**Extension: `markdown_in_html_blocks`**

2168

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

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

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

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

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

2174

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

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

2177Thus, for example, Pandoc will turn

2178

2179 <table>

2180 <tr>

2181 <td>*one*</td>

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

2183 </tr>

2184 </table>

2185

2186into

2187

2188 <table>

2189 <tr>

2190 <td><em>one</em></td>

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

2192 </tr>

2193 </table>

2194

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

2196

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

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

2199

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

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

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

2203from being interpreted as markdown.

2204

2205Raw TeX

2206-------

2207

2208**Extension: `raw_tex`**

2209

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

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

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

2213LaTeX to include BibTeX citations:

2214

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

2216

2217Note that in LaTeX environments, like

2218

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

2220 Age & Frequency \\ \hline

2221 18--25 & 15 \\

2222 26--35 & 33 \\

2223 36--45 & 22 \\ \hline

2224 \end{tabular}

2225

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

2227LaTeX, not as markdown.

2228

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

2230and ConTeXt.

2231

2232LaTeX macros

2233------------

2234

2235**Extension: `latex_macros`**

2236

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

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

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

2240not just LaTeX:

2241

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

2243

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

2245

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

2247unchanged to the output.

2248

2249

2250Links

2251-----

2252

2253Markdown allows links to be specified in several ways.

2254

2255### Automatic links ###

2256

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

2258will become a link:

2259

2260 <http://google.com>

2261 <sam@green.eggs.ham>

2262

2263### Inline links ###

2264

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

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

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

2268

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

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

2271

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

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

2274

2275

2276### Reference links ###

2277

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

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

2280before or after the link).

2281

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

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

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

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

2286parentheses.

2287

2288Here are some examples:

2289

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

2291 [my label 2]: /foo

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

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

2294

2295The URL may optionally be surrounded by angle brackets:

2296

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

2298

2299The title may go on the next line:

2300

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

2302 "The free software foundation"

2303

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

2305

2306 Here is [my link][FOO]

2307

2308 [Foo]: /bar/baz

2309

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

2311empty, or omitted entirely:

2312

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

2314

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

2316

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

2318reference link definitions cannot occur in nested constructions

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

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

2321not in most other implementations:

2322

2323 > My block [quote].

2324 >

2325 > [quote]: /foo

2326

2327### Internal links

2328

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

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

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

2332For example:

2333

2334 See the [Introduction](#introduction).

2335

2336or

2337

2338 See the [Introduction].

2339

2340 [Introduction]: #introduction

2341

2342Internal links are currently supported for HTML formats (including

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

2344

2345Images

2346------

2347

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

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

2350

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

2352

2353 ![movie reel]

2354

2355 [movie reel]: movie.gif

2356

2357### Pictures with captions ###

2358

2359**Extension: `implicit_figures`**

2360

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

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

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

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

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

2366

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

2368

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

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

2371 itself, with no caption.

2372

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

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

2375nonbreaking space after the image:

2376

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

2378

2379

2380Footnotes

2381---------

2382

2383**Extension: `footnotes`**

2384

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

2386

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

2388

2389 [^1]: Here is the footnote.

2390

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

2392

2393 Subsequent paragraphs are indented to show that they

2394 belong to the previous footnote.

2395

2396 { some.code }

2397

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

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

2400 multi-paragraph list items.

2401

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

2403 isn't indented.

2404

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

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

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

2408will be numbered sequentially.

2409

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

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

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

2413

2414**Extension: `inline_notes`**

2415

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

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

2418

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

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

2421 note.]

2422

2423Inline and regular footnotes may be mixed freely.

2424

2425

2426Citations

2427---------

2428

2429**Extension: `citations`**

2430

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

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

2433

2434 pandoc --filter pandoc-citeproc myinput.txt

2435

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

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

2438The bibliography may have any of these formats:

2439

2440 Format File extension

2441 ------------ --------------

2442 MODS .mods

2443 BibLaTeX .bib

2444 BibTeX .bibtex

2445 RIS .ris

2446 EndNote .enl

2447 EndNote XML .xml

2448 ISI .wos

2449 MEDLINE .medline

2450 Copac .copac

2451 JSON citeproc .json

2452

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

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

2455

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

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

2458for example:

2459

2460 ---

2461 references:

2462 - id: fenner2012a

2463 title: One-click science marketing

2464 author:

2465 - family: Fenner

2466 given: Martin

2467 container-title: Nature Materials

2468 volume: 11

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

2470 DOI: 10.1038/nmat3283

2471 issue: 4

2472 publisher: Nature Publishing Group

2473 page: 261-263

2474 type: article-journal

2475 issued:

2476 year: 2012

2477 month: 3

2478 ...

2479

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

2481these from a MODS reference collection.)

2482

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

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

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

2486modifying CSL styles can be found at

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

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

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

2490

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

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

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

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

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

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

2497

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

2499

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

2501

2502 Blah blah [@smith04; @doe99].

2503

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

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

2506author is already mentioned in the text:

2507

2508 Smith says blah [-@smith04].

2509

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

2511

2512 @smith04 says blah.

2513

2514 @smith04 [p. 33] says blah.

2515

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

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

2518document with an appropriate header:

2519

2520 last paragraph...

2521

2522 # References

2523

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

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

2526section will not be numbered.

2527

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

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

2530field and put the citations there:

2531

2532 ---

2533 nocite: |

2534 @item1, @item2

2535 ...

2536

2537 @item3

2538

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

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

2541`item3`.

2542

2543Non-pandoc extensions

2544---------------------

2545

2546The following markdown syntax extensions are not enabled by default

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

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

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

2550

2551**Extension: `lists_without_preceding_blankline`**\

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

2553blank space.

2554

2555**Extension: `hard_line_breaks`**\

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

2557breaks instead of spaces.

2558

2559**Extension: `ignore_line_breaks`**\

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

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

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

2563but text is divided into lines for readability.

2564

2565**Extension: `tex_math_single_backslash`**\

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

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

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

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

2570

2571**Extension: `tex_math_double_backslash`**\

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

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

2574as display TeX math.

2575

2576**Extension: `markdown_attribute`**\

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

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

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

2580

2581**Extension: `mmd_title_block`**\

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

2583the document, for example:

2584

2585 Title: My title

2586 Author: John Doe

2587 Date: September 1, 2008

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

2589 a field spanning multiple lines.

2590

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

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

2593`mmd_title_block`.

2594

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

2596

2597**Extension: `abbreviations`**\

2598Parses PHP Markdown Extra abbreviation keys, like

2599

2600 *[HTML]: Hyper Text Markup Language

2601

2602Note that the pandoc document model does not support

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

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

2605

2606**Extension: `autolink_bare_uris`**\

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

2608pointy braces `<...>`.

2609

2610**Extension: `ascii_identifiers`**\

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

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

2613letters are omitted.

2614

2615**Extension: `link_attributes`**\

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

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

2618these, so they are presently just ignored.

2619

2620**Extension: `mmd_header_identifiers`**\

2621Parses multimarkdown style header identifiers (in square brackets,

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

2623

2624Markdown variants

2625-----------------

2626

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

2628variants are supported:

2629

2630`markdown_phpextra` (PHP Markdown Extra)

2631: `footnotes`, `pipe_tables`, `raw_html`, `markdown_attribute`,

2632 `fenced_code_blocks`, `definition_lists`, `intraword_underscores`,

2633 `header_attributes`, `abbreviations`.

2634

2635`markdown_github` (Github-flavored Markdown)

2636: `pipe_tables`, `raw_html`, `tex_math_single_backslash`,

2637 `fenced_code_blocks`, `fenced_code_attributes`, `auto_identifiers`,

2638 `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`,

2639 `intraword_underscores`, `strikeout`, `hard_line_breaks`

2640

2641`markdown_mmd` (MultiMarkdown)

2642: `pipe_tables` `raw_html`, `markdown_attribute`, `link_attributes`,

2643 `raw_tex`, `tex_math_double_backslash`, `intraword_underscores`,

2644 `mmd_title_block`, `footnotes`, `definition_lists`,

2645 `all_symbols_escapable`, `implicit_header_references`,

2646 `auto_identifiers`, `mmd_header_identifiers`

2647

2648`markdown_strict` (Markdown.pl)

2649: `raw_html`

2650

2651Extensions with formats other than markdown

2652-------------------------------------------

2653

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

2655other than markdown:

2656

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

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

2659

2660* `tex_math_dollars`, `tex_math_single_backslash`, and

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

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

2663 for example.)

2664

2665Producing slide shows with Pandoc

2666=================================

2667

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

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

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

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

2672

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

2674

2675 % Habits

2676 % John Doe

2677 % March 22, 2005

2678

2679 # In the morning

2680

2681 ## Getting up

2682

2683 - Turn off alarm

2684 - Get out of bed

2685

2686 ## Breakfast

2687

2688 - Eat eggs

2689 - Drink coffee

2690

2691 # In the evening

2692

2693 ## Dinner

2694

2695 - Eat spaghetti

2696 - Drink wine

2697

2698 ------------------

2699

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

2701

2702 ## Going to sleep

2703

2704 - Get in bed

2705 - Count sheep

2706

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

2708

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

2710

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

2712

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

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

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

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

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

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

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

2720the file by default.

2721

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

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

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

2725

2726To produce a PDF slide show using beamer, type

2727

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

2729

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

2731by printing it to a file from the browser.

2732

2733Structuring the slide show

2734--------------------------

2735

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

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

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

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

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

2741the `--slide-level` option.

2742

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

2744rules:

2745

2746 * A horizontal rule always starts a new slide.

2747

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

2749

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

2751 headers *within* a slide.

2752

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

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

2755 and help to break the slide show into sections.

2756

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

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

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

2760

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

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

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

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

2765sections, as in the example above.

2766

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

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

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

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

2771

2772Incremental lists

2773-----------------

2774

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

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

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

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

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

2780

2781 > - Eat spaghetti

2782 > - Drink wine

2783

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

2785a single document.

2786

2787Inserting pauses

2788----------------

2789

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

2791three dots, separated by spaces:

2792

2793 # Slide with a pause

2794

2795 content before the pause

2796

2797 . . .

2798

2799 content after the pause

2800

2801Styling the slides

2802------------------

2803

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

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

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

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

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

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

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

2811

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

2813be modified there.

2814

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

2816for example:

2817

2818 -V theme=moon

2819

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

2821

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

2823using the `-V` option:

2824

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

2826

2827Note that header attributes will turn into slide attributes

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

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

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

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

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

2833bibliographies:

2834

2835 # References {.allowframebreaks}

2836

2837Speaker notes

2838-------------

2839

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

2841markdown document thus:

2842

2843 <div class="notes">

2844 This is my note.

2845

2846 - It can contain markdown

2847 - like this list

2848

2849 </div>

2850

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

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

2853will not appear on the slides themselves.

2854

2855EPUB Metadata

2856=============

2857

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

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

2860block. Here is an example:

2861

2862 ---

2863 title:

2864 - type: main

2865 text: My Book

2866 - type: subtitle

2867 text: An investigation of metadata

2868 creator:

2869 - role: author

2870 text: John Smith

2871 - role: editor

2872 text: Sarah Jones

2873 identifier:

2874 - scheme: DOI

2875 text: doi:10.234234.234/33

2876 publisher: My Press

2878 ...

2879

2880The following fields are recognized:

2881

2882`identifier`

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

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

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

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

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

2888`title`

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

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

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

2892`creator`

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

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

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

2896 pandoc will attempt to translate the human-readable versions

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

2898`contributor`

2899 ~ Same format as `creator`.

2900`date`

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

2902 Pandoc will attempt to convert other common date formats.

2903`language`

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

2905 language if nothing is specified.

2906`subject`

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

2908`description`

2909 ~ A string value.

2910`type`

2911 ~ A string value.

2912`format`

2913 ~ A string value.

2914`relation`

2915 ~ A string value.

2916`coverage`

2917 ~ A string value.

2918`rights`

2919 ~ A string value.

2920`cover-image`

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

2922`stylesheet`

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

2924

2925Literate Haskell support

2926========================

2927

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

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

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

2931literate Haskell source. This means that

2932

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

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

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

2936

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

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

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

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

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

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

2943

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

2945 as Haskell code.

2946

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

2948 be rendered using bird tracks.

2949

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

2951 Haskell code.

2952

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

2954 inside `code` environments.

2955

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

2957 with class `literatehaskell` and bird tracks.

2958

2959Examples:

2960

2961 pandoc -f markdown+lhs -t html

2962

2963reads literate Haskell source formatted with markdown conventions and writes

2964ordinary HTML (without bird tracks).

2965

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

2967

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

2969and pasted as literate Haskell source.

2970

2971Custom writers

2972==============

2973

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

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

2976

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

2978in place of the output format. For example:

2979

2980 pandoc -t data/sample.lua

2981

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

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

2984which you can modify according to your needs, do

2985

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

2987

2988Authors

2989=======

2990

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

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

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

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

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

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

2998Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

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

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

3002Rosenthal.

3003

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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