README · typeable/pandoc

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

1397

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

1399

1400

1401### Numbered example lists ###

1402

1403**Extension: `example_lists`**

1404

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

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

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

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

1409where the last stopped. So, for example:

1410

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

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

1413

1414 Explanation of examples.

1415

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

1417

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

1419document:

1420

1421 (@good) This is a good example.

1422

1423 As (@good) illustrates, ...

1424

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

1426or hyphens.

1427

1428

1429### Compact and loose lists ###

1430

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

1432cases" involving lists. Consider this source:

1433

1434 + First

1435 + Second:

1436 - Fee

1437 - Fie

1438 - Foe

1439

1440 + Third

1441

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

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

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

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

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

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

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

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

1450behavior is consistent with the official markdown syntax description,

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

1452

1453

1454### Ending a list ###

1455

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

1457

1458 - item one

1459 - item two

1460

1461 { my code block }

1462

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

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

1465a code block.

1466

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

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

1469any format:

1470

1471 - item one

1472 - item two

1473

1474

1475

1476 { my code block }

1477

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

1479of one big list:

1480

1481 1. one

1482 2. two

1483 3. three

1484

1485

1486

1487 1. uno

1488 2. dos

1489 3. tres

1490

1491Horizontal rules

1492----------------

1493

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

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

1497 * * * *

1499 ---------------

1502Tables

1503------

1504

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

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

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

1508

1509### Simple tables

1510

1511**Extension: `simple_tables`, `table_captions`**

1512

1513Simple tables look like this:

1514

1515 Right Left Center Default

1516 ------- ------ ---------- -------

1517 12 12 12 12

1518 123 123 123 123

1519 1 1 1 1

1520

1521 Table: Demonstration of simple table syntax.

1522

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

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

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

1526

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

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

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

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

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

1532 the column is centered.

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

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

1535

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

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

1538

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

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

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

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

1543before or after the table.

1544

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

1546to end the table. For example:

1547

1548 ------- ------ ---------- -------

1549 12 12 12 12

1550 123 123 123 123

1551 1 1 1 1

1552 ------- ------ ---------- -------

1553

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

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

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

1557

1558### Multiline tables

1559

1560**Extension: `multiline_tables`, `table_captions`**

1561

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

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

1564not supported). Here is an example:

1565

1566 -------------------------------------------------------------

1567 Centered Default Right Left

1568 Header Aligned Aligned Aligned

1569 ----------- ------- --------------- -------------------------

1570 First row 12.0 Example of a row that

1571 spans multiple lines.

1572

1573 Second row 5.0 Here's another one. Note

1574 the blank line between

1575 rows.

1576 -------------------------------------------------------------

1577

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

1579 multiple lines.

1580

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

1582

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

1584 (unless the headers are omitted).

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

1586 - The rows must be separated by blank lines.

1587

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

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

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

1591output, try widening it in the markdown source.

1592

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

1594

1595 ----------- ------- --------------- -------------------------

1596 First row 12.0 Example of a row that

1597 spans multiple lines.

1598

1599 Second row 5.0 Here's another one. Note

1600 the blank line between

1601 rows.

1602 ----------- ------- --------------- -------------------------

1603

1604 : Here's a multiline table without headers.

1605

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

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

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

1609

1610### Grid tables

1611

1612**Extension: `grid_tables`, `table_captions`**

1613

1614Grid tables look like this:

1615

1616 : Sample grid table.

1617

1618 +---------------+---------------+--------------------+

1619 | Fruit | Price | Advantages |

1620 +===============+===============+====================+

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

1622 | | | - bright color |

1623 +---------------+---------------+--------------------+

1624 | Oranges | $2.10 | - cures scurvy |

1625 | | | - tasty |

1626 +---------------+---------------+--------------------+

1627

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

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

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

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

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

1633

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

1635

1636### Pipe tables

1637

1638**Extension: `pipe_tables`, `table_captions`**

1639

1640Pipe tables look like this:

1641

1643 |------:|:-----|---------|:------:|

1644 | 12 | 12 | 12 | 12 |

1645 | 123 | 123 | 123 | 123 |

1646 | 1 | 1 | 1 | 1 |

1647

1648 : Demonstration of simple table syntax.

1649

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

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

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

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

1654it defines column alignments.

1655

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

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

1658legal (though ugly) pipe table:

1659

1660 fruit| price

1661 -----|-----:

1662 apple|2.05

1663 pear|1.37

1664 orange|3.09

1665

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

1667and lists, and cannot span multiple lines.

1668

1669 [the same as in PHP markdown extra]:

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

1671

1672Note: Pandoc also recognizes pipe tables of the following

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

1674

1675 | One | Two |

1676 |-----+-------|

1677 | my | table |

1678 | is | nice |

1679

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

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

1682you'll need to add colons as above.

1683

1684Title block

1685-----------

1686

1687**Extension: `pandoc_title_block`**

1688

1689If the file begins with a title block

1690

1691 % title

1692 % author(s) (separated by semicolons)

1693 % date

1694

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

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

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

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

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

1700

1701 %

1702 % Author

1703

1704 % My title

1705 %

1706 % June 15, 2006

1707

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

1709begin with leading space, thus:

1710

1711 % My title

1712 on multiple lines

1713

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

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

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

1717

1718 % Author One

1719 Author Two

1720

1721 % Author One; Author Two

1722

1723 % Author One;

1724 Author Two

1725

1726The date must fit on one line.

1727

1728All three metadata fields may contain standard inline formatting

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

1730

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

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

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

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

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

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

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

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

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

1740be used by itself as the HTML title.

1741

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

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

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

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

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

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

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

1749text. Thus,

1750

1751 % PANDOC(1)

1752

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

1754

1755 % PANDOC(1) Pandoc User Manuals

1756

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

1758

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

1760

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

1762

1763

1764Backslash escapes

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

1766

1767**Extension: `all_symbols_escapable`**

1768

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

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

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

1772

1773 *\*hello\**

1774

1775one will get

1776

1777 <em>*hello*</em>

1778

1779instead of

1780

1781 <strong>hello</strong>

1782

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

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

1785

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

1787

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

1789will be used.)

1790

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

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

1793`\ `.

1794

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

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

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

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

1799two trailing spaces on a line.

1800

1801Backslash escapes do not work in verbatim contexts.

1802

1803Smart punctuation

1804-----------------

1805

1806**Extension**

1807

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

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

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

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

1812

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

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

1815

1816Inline formatting

1817-----------------

1818

1819### Emphasis ###

1820

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

1822

1823 This text is _emphasized with underscores_, and this

1824 is *emphasized with asterisks*.

1825

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

1827

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

1829

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

1831will not trigger emphasis:

1832

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

1834

1835**Extension: `intraword_underscores`**

1836

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

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

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

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

1841

1842 feas*ible*, not feas*able*.

1843

1844

1845### Strikeout ###

1846

1847**Extension: `strikeout`**

1848

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

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

1851

1852 This ~~is deleted text.~~

1853

1854

1855### Superscripts and subscripts ###

1856

1857**Extension: `superscript`, `subscript`**

1858

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

1860characters; subscripts may be written by surrounding the subscripted

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

1862

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

1864

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

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

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

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

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

1870

1871

1872### Verbatim ###

1873

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

1875

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

1877

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

1879

1880 Here is a literal backtick `` ` ``.

1881

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

1883backticks will be ignored.)

1884

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

1886of consecutive backticks (optionally followed by a space)

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

1888preceded by a space).

1889

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

1891work in verbatim contexts:

1892

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

1894

1895**Extension: `inline_code_attributes`**

1896

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

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

1899

1900 `<$>`{.haskell}

1901

1902Math

1903----

1904

1905**Extension: `tex_math_dollars`**

1906

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

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

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

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

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

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

1913

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

1915depends on the output format:

1916

1917Markdown, LaTeX, Org-Mode, ConTeXt

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

1919

1920reStructuredText

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

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

1923

1924AsciiDoc

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

1926

1927Texinfo

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

1929

1930groff man

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

1932

1933MediaWiki

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

1935

1936Textile

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

1938

1939RTF, OpenDocument, ODT

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

1941 and will otherwise appear verbatim.

1942

1943Docbook

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

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

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

1947

1948Docx

1949 ~ It will be rendered using OMML math markup.

1950

1951FictionBook2

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

1953 using Google Charts or other compatible web service, downloaded

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

1955

1956HTML, Slidy, DZSlides, S5, EPUB

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

1958 command-line options selected:

1959

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

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

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

1963 styled differently from the surrounding text if needed.

1964

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

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

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

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

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

1970 verbatim between `$` characters.)

1971

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

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

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

1975 it.

1976

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

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

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

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

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

1982

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

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

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

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

1987 procedure is:

1988

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

1990 gladtex -d myfile-images myfile.htex

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

1992

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

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

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

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

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

1998

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

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

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

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

2003

2004Raw HTML

2005--------

2006

2007**Extension: `raw_html`**

2008

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

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

2011literally). (Techncially this is not an extension, since standard

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

2013be disabled if desired.)

2014

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

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

2017formats.

2018

2019**Extension: `markdown_in_html_blocks`**

2020

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

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

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

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

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

2026

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

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

2029Thus, for example, Pandoc will turn

2030

2031 <table>

2032 <tr>

2033 <td>*one*</td>

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

2035 </tr>

2036 </table>

2037

2038into

2039

2040 <table>

2041 <tr>

2042 <td><em>one</em></td>

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

2044 </tr>

2045 </table>

2046

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

2048

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

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

2051

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

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

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

2055from being interpreted as markdown.

2056

2057Raw TeX

2058-------

2059

2060**Extension: `raw_tex`**

2061

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

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

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

2065LaTeX to include BibTeX citations:

2066

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

2068

2069Note that in LaTeX environments, like

2070

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

2072 Age & Frequency \\ \hline

2073 18--25 & 15 \\

2074 26--35 & 33 \\

2075 36--45 & 22 \\ \hline

2076 \end{tabular}

2077

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

2079LaTeX, not as markdown.

2080

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

2082and ConTeXt.

2083

2084LaTeX macros

2085------------

2086

2087**Extension: `latex_macros`**

2088

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

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

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

2092not just LaTeX:

2093

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

2095

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

2097

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

2099unchanged to the output.

2100

2101

2102Links

2103-----

2104

2105Markdown allows links to be specified in several ways.

2106

2107### Automatic links ###

2108

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

2110will become a link:

2111

2112 <http://google.com>

2113 <sam@green.eggs.ham>

2114

2115### Inline links ###

2116

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

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

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

2120

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

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

2123

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

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

2126

2127

2128### Reference links ###

2129

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

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

2132before or after the link).

2133

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

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

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

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

2138parentheses.

2139

2140Here are some examples:

2141

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

2143 [my label 2]: /foo

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

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

2146

2147The URL may optionally be surrounded by angle brackets:

2148

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

2150

2151The title may go on the next line:

2152

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

2154 "The free software foundation"

2155

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

2157

2158 Here is [my link][FOO]

2159

2160 [Foo]: /bar/baz

2161

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

2163empty, or omitted entirely:

2164

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

2166

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

2168

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

2170reference link definitions cannot occur in nested constructions

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

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

2173not in most other implementations:

2174

2175 > My block [quote].

2176 >

2177 > [quote]: /foo

2178

2179### Internal links

2180

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

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

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

2184For example:

2185

2186 See the [Introduction](#introduction).

2187

2188or

2189

2190 See the [Introduction].

2191

2192 [Introduction]: #introduction

2193

2194Internal links are currently supported for HTML formats (including

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

2196

2197Images

2198------

2199

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

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

2202

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

2204

2205 ![movie reel]

2206

2207 [movie reel]: movie.gif

2208

2209### Pictures with captions ###

2210

2211**Extension: `implicit_figures`**

2212

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

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

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

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

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

2218

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

2220

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

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

2223 itself, with no caption.

2224

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

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

2227nonbreaking space after the image:

2228

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

2230

2231

2232Footnotes

2233---------

2234

2235**Extension: `footnotes`**

2236

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

2238

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

2240

2241 [^1]: Here is the footnote.

2242

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

2244

2245 Subsequent paragraphs are indented to show that they

2246 belong to the previous footnote.

2247

2248 { some.code }

2249

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

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

2252 multi-paragraph list items.

2253

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

2255 isn't indented.

2256

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

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

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

2260will be numbered sequentially.

2261

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

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

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

2265

2266**Extension: `inline_notes`**

2267

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

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

2270

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

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

2273 note.]

2274

2275Inline and regular footnotes may be mixed freely.

2276

2277

2278Citations

2279---------

2280

2281**Extension: `citations`**

2282

2283Pandoc can automatically generate citations and a bibliography in a number of

2284styles (using Andrea Rossato's `hs-citeproc`). In order to use this feature,

2285you will need a bibliographic database in one of the following formats:

2286

2287 Format File extension

2288 ------------ --------------

2289 MODS .mods

2290 BibLaTeX .bib

2291 BibTeX .bibtex

2292 RIS .ris

2293 EndNote .enl

2294 EndNote XML .xml

2295 ISI .wos

2296 MEDLINE .medline

2297 Copac .copac

2298 JSON citeproc .json

2299

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

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

2302

2303You will need to specify the bibliography file using the `--bibliography`

2304command-line option (which may be repeated if you have several

2305bibliographies).

2306

2307By default, pandoc will use a Chicago author-date format for citations

2308and references. To use another style, you will need to use the

2309`--csl` option to specify a [CSL] 1.0 style file. A primer on

2310creating and modifying CSL styles can be found at

2311<http://citationstyles.org/downloads/primer.html>.

2312A repository of CSL styles can be found at

2313<https://github.com/citation-style-language/styles>.

2314See also <http://zotero.org/styles> for easy browsing.

2315

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

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

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

2319a locator, and a suffix. Here are some examples:

2320

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

2322

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

2324

2325 Blah blah [@smith04; @doe99].

2326

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

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

2329author is already mentioned in the text:

2330

2331 Smith says blah [-@smith04].

2332

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

2334

2335 @smith04 says blah.

2336

2337 @smith04 [p. 33] says blah.

2338

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

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

2341document with an appropriate header:

2342

2343 last paragraph...

2344

2345 # References

2346

2347The bibliography will be inserted after this header.

2348

2349Non-pandoc extensions

2350=====================

2351

2352The following markdown syntax extensions are not enabled by default

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

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

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

2356

2357**Extension: `hard_line_breaks`**\

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

2359breaks instead of spaces.

2360

2361**Extension: `tex_math_single_backslash`**\

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

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

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

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

2366

2367**Extension: `tex_math_double_backslash`**\

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

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

2370as display TeX math.

2371

2372**Extension: `markdown_attribute`**\

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

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

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

2376

2377**Extension: `mmd_title_block`**\

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

2379the document, for example:

2380

2381 Title: My title

2382 Author: John Doe

2383 Date: September 1, 2008

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

2385 a field spanning multiple lines.

2386

2387See the MultiMarkdown documentation for details. Note that only title,

2388author, and date are recognized; other fields are simply ignored by

2389pandoc. If `pandoc_title_block` is enabled, it will take precedence over

2390`mmd_title_block`.

2391

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

2393

2394**Extension: `abbreviations`**\

2395Parses PHP Markdown Extra abbreviation keys, like

2396

2397 *[HTML]: Hyper Text Markup Language

2398

2399Note that the pandoc document model does not support

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

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

2402

2403**Extension: `autolink_bare_uris`**\

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

2405pointy braces `<...>`.

2406

2407**Extension: `link_attributes`**\

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

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

2410these, so they are presently just ignored.

2411

2412**Extension: `mmd_header_identifiers`**\

2413Parses multimarkdown style header identifiers (in square brackets,

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

2415

2416Producing slide shows with Pandoc

2417=================================

2418

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

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

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

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

2423

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

2425

2426 % Habits

2427 % John Doe

2428 % March 22, 2005

2429

2430 # In the morning

2431

2432 ## Getting up

2433

2434 - Turn off alarm

2435 - Get out of bed

2436

2437 ## Breakfast

2438

2439 - Eat eggs

2440 - Drink coffee

2441

2442 # In the evening

2443

2444 ## Dinner

2445

2446 - Eat spaghetti

2447 - Drink wine

2448

2449 ------------------

2450

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

2452

2453 ## Going to sleep

2454

2455 - Get in bed

2456 - Count sheep

2457

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

2459

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

2461

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

2463

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

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

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

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

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

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

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

2471the file by default.

2472

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

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

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

2476

2477To produce a PDF slide show using beamer, type

2478

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

2480

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

2482by printing it to a file from the browser.

2483

2484Structuring the slide show

2485--------------------------

2486

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

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

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

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

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

2492the `--slide-level` option.

2493

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

2495rules:

2496

2497 * A horizontal rule always starts a new slide.

2498

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

2500

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

2502 headers *within* a slide.

2503

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

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

2506 and help to break the slide show into sections.

2507

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

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

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

2511

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

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

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

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

2516sections, as in the example above.

2517

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

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

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

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

2522

2523Incremental lists

2524-----------------

2525

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

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

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

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

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

2531

2532 > - Eat spaghetti

2533 > - Drink wine

2534

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

2536a single document.

2537

2538Inserting pauses

2539----------------

2540

2541In reveal.js and beamer slide shows, you can add "pauses" within

2542a slide by including a paragraph containing three dots, separated

2543by spaces:

2544

2545 # Slide with a pause

2546

2547 content before the pause

2548

2549 . . .

2550

2551 content after the pause

2552

2553Styling the slides

2554------------------

2555

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

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

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

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

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

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

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

2563

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

2565be modified there.

2566

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

2568for example:

2569

2570 -V theme=moon

2571

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

2573

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

2575using the `-V` option:

2576

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

2578

2579Literate Haskell support

2580========================

2581

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

2583format (`markdown`, `mardkown_strict`, `rst`, or `latex` for input or output;

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

2585literate Haskell source. This means that

2586

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

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

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

2590

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

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

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

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

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

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

2597

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

2599 as Haskell code.

2600

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

2602 be rendered using bird tracks.

2603

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

2605 Haskell code.

2606

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

2608 inside `code` environments.

2609

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

2611 with class `literatehaskell` and bird tracks.

2612

2613Examples:

2614

2615 pandoc -f markdown+lhs -t html

2616

2617reads literate Haskell source formatted with markdown conventions and writes

2618ordinary HTML (without bird tracks).

2619

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

2621

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

2623and pasted as literate Haskell source.

2624

2625Authors

2626=======

2627

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

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

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

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

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

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

2635Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

2637Sergey Astanin, Arlo O'Keeffe, Denis Laxalde, Brent Yorgey.

2638

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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