README · typeable/pandoc

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

1376

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

1378

1379

1380### Numbered example lists ###

1381

1382**Extension: `example_lists`**

1383

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

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

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

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

1388where the last stopped. So, for example:

1389

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

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

1392

1393 Explanation of examples.

1394

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

1396

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

1398document:

1399

1400 (@good) This is a good example.

1401

1402 As (@good) illustrates, ...

1403

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

1405or hyphens.

1406

1407

1408### Compact and loose lists ###

1409

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

1411cases" involving lists. Consider this source:

1412

1413 + First

1414 + Second:

1415 - Fee

1416 - Fie

1417 - Foe

1418

1419 + Third

1420

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

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

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

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

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

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

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

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

1429behavior is consistent with the official markdown syntax description,

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

1431

1432

1433### Ending a list ###

1434

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

1436

1437 - item one

1438 - item two

1439

1440 { my code block }

1441

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

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

1444a code block.

1445

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

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

1448any format:

1449

1450 - item one

1451 - item two

1452

1453

1454

1455 { my code block }

1456

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

1458of one big list:

1459

1460 1. one

1461 2. two

1462 3. three

1463

1464

1465

1466 1. uno

1467 2. dos

1468 3. tres

1469

1470Horizontal rules

1471----------------

1472

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

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

1476 * * * *

1478 ---------------

1481Tables

1482------

1483

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

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

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

1487

1488### Simple tables

1489

1490**Extension: `simple_tables`, `table_captions`**

1491

1492Simple tables look like this:

1493

1494 Right Left Center Default

1495 ------- ------ ---------- -------

1496 12 12 12 12

1497 123 123 123 123

1498 1 1 1 1

1499

1500 Table: Demonstration of simple table syntax.

1501

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

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

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

1505

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

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

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

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

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

1511 the column is centered.

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

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

1514

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

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

1517

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

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

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

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

1522before or after the table.

1523

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

1525to end the table. For example:

1526

1527 ------- ------ ---------- -------

1528 12 12 12 12

1529 123 123 123 123

1530 1 1 1 1

1531 ------- ------ ---------- -------

1532

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

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

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

1536

1537### Multiline tables

1538

1539**Extension: `multiline_tables`, `table_captions`**

1540

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

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

1543not supported). Here is an example:

1544

1545 -------------------------------------------------------------

1546 Centered Default Right Left

1547 Header Aligned Aligned Aligned

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

1549 First row 12.0 Example of a row that

1550 spans multiple lines.

1551

1552 Second row 5.0 Here's another one. Note

1553 the blank line between

1554 rows.

1555 -------------------------------------------------------------

1556

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

1558 multiple lines.

1559

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

1561

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

1563 (unless the headers are omitted).

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

1565 - The rows must be separated by blank lines.

1566

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

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

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

1570output, try widening it in the markdown source.

1571

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

1573

1574 ----------- ------- --------------- -------------------------

1575 First row 12.0 Example of a row that

1576 spans multiple lines.

1577

1578 Second row 5.0 Here's another one. Note

1579 the blank line between

1580 rows.

1581 ----------- ------- --------------- -------------------------

1582

1583 : Here's a multiline table without headers.

1584

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

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

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

1588

1589### Grid tables

1590

1591**Extension: `grid_tables`, `table_captions`**

1592

1593Grid tables look like this:

1594

1595 : Sample grid table.

1596

1597 +---------------+---------------+--------------------+

1598 | Fruit | Price | Advantages |

1599 +===============+===============+====================+

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

1601 | | | - bright color |

1602 +---------------+---------------+--------------------+

1603 | Oranges | $2.10 | - cures scurvy |

1604 | | | - tasty |

1605 +---------------+---------------+--------------------+

1606

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

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

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

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

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

1612

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

1614

1615### Pipe tables

1616

1617**Extension: `pipe_tables`, `table_captions`**

1618

1619Pipe tables look like this:

1620

1622 |------:|:-----|---------|:------:|

1623 | 12 | 12 | 12 | 12 |

1624 | 123 | 123 | 123 | 123 |

1625 | 1 | 1 | 1 | 1 |

1626

1627 : Demonstration of simple table syntax.

1628

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

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

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

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

1633it defines column alignments.

1634

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

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

1637legal (though ugly) pipe table:

1638

1639 fruit| price

1640 -----|-----:

1641 apple|2.05

1642 pear|1.37

1643 orange|3.09

1644

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

1646and lists, and cannot span multiple lines.

1647

1648 [the same as in PHP markdown extra]:

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

1650

1651Note: Pandoc also recognizes pipe tables of the following

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

1653

1654 | One | Two |

1655 |-----+-------|

1656 | my | table |

1657 | is | nice |

1658

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

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

1661you'll need to add colons as above.

1662

1663Title block

1664-----------

1665

1666**Extension: `pandoc_title_block`**

1667

1668If the file begins with a title block

1669

1670 % title

1671 % author(s) (separated by semicolons)

1672 % date

1673

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

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

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

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

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

1679

1680 %

1681 % Author

1682

1683 % My title

1684 %

1685 % June 15, 2006

1686

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

1688begin with leading space, thus:

1689

1690 % My title

1691 on multiple lines

1692

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

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

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

1696

1697 % Author One

1698 Author Two

1699

1700 % Author One; Author Two

1701

1702 % Author One;

1703 Author Two

1704

1705The date must fit on one line.

1706

1707All three metadata fields may contain standard inline formatting

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

1709

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

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

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

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

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

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

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

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

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

1719be used by itself as the HTML title.

1720

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

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

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

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

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

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

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

1728text. Thus,

1729

1730 % PANDOC(1)

1731

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

1733

1734 % PANDOC(1) Pandoc User Manuals

1735

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

1737

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

1739

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

1741

1742

1743Backslash escapes

1744-----------------

1745

1746**Extension: `all_symbols_escapable`**

1747

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

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

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

1751

1752 *\*hello\**

1753

1754one will get

1755

1756 <em>*hello*</em>

1757

1758instead of

1759

1760 <strong>hello</strong>

1761

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

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

1764

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

1766

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

1768will be used.)

1769

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

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

1772`\ `.

1773

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

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

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

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

1778two trailing spaces on a line.

1779

1780Backslash escapes do not work in verbatim contexts.

1781

1782Smart punctuation

1783-----------------

1784

1785**Extension**

1786

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

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

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

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

1791

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

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

1794

1795Inline formatting

1796-----------------

1797

1798### Emphasis ###

1799

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

1801

1802 This text is _emphasized with underscores_, and this

1803 is *emphasized with asterisks*.

1804

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

1806

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

1808

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

1810will not trigger emphasis:

1811

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

1813

1814**Extension: `intraword_underscores`**

1815

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

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

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

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

1820

1821 feas*ible*, not feas*able*.

1822

1823

1824### Strikeout ###

1825

1826**Extension: `strikeout`**

1827

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

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

1830

1831 This ~~is deleted text.~~

1832

1833

1834### Superscripts and subscripts ###

1835

1836**Extension: `superscript`, `subscript`**

1837

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

1839characters; subscripts may be written by surrounding the subscripted

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

1841

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

1843

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

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

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

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

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

1849

1850

1851### Verbatim ###

1852

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

1854

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

1856

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

1858

1859 Here is a literal backtick `` ` ``.

1860

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

1862backticks will be ignored.)

1863

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

1865of consecutive backticks (optionally followed by a space)

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

1867preceded by a space).

1868

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

1870work in verbatim contexts:

1871

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

1873

1874**Extension: `inline_code_attributes`**

1875

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

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

1878

1879 `<$>`{.haskell}

1880

1881Math

1882----

1883

1884**Extension: `tex_math_dollars`**

1885

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

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

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

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

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

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

1892

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

1894depends on the output format:

1895

1896Markdown, LaTeX, Org-Mode, ConTeXt

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

1898

1899reStructuredText

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

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

1902

1903AsciiDoc

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

1905

1906Texinfo

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

1908

1909groff man

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

1911

1912MediaWiki

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

1914

1915Textile

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

1917

1918RTF, OpenDocument, ODT

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

1920 and will otherwise appear verbatim.

1921

1922Docbook

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

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

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

1926

1927Docx

1928 ~ It will be rendered using OMML math markup.

1929

1930FictionBook2

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

1932 using Google Charts or other compatible web service, downloaded

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

1934

1935HTML, Slidy, DZSlides, S5, EPUB

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

1937 command-line options selected:

1938

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

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

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

1942 styled differently from the surrounding text if needed.

1943

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

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

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

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

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

1949 verbatim between `$` characters.)

1950

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

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

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

1954 it.

1955

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

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

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

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

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

1961

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

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

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

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

1966 procedure is:

1967

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

1969 gladtex -d myfile-images myfile.htex

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

1971

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

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

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

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

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

1977

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

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

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

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

1982

1983Raw HTML

1984--------

1985

1986**Extension: `raw_html`**

1987

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

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

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

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

1992be disabled if desired.)

1993

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

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

1996formats.

1997

1998**Extension: `markdown_in_html_blocks`**

1999

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

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

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

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

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

2005

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

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

2008Thus, for example, Pandoc will turn

2009

2010 <table>

2011 <tr>

2012 <td>*one*</td>

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

2014 </tr>

2015 </table>

2016

2017into

2018

2019 <table>

2020 <tr>

2021 <td><em>one</em></td>

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

2023 </tr>

2024 </table>

2025

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

2027

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

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

2030

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

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

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

2034from being interpreted as markdown.

2035

2036Raw TeX

2037-------

2038

2039**Extension: `raw_tex`**

2040

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

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

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

2044LaTeX to include BibTeX citations:

2045

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

2047

2048Note that in LaTeX environments, like

2049

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

2051 Age & Frequency \\ \hline

2052 18--25 & 15 \\

2053 26--35 & 33 \\

2054 36--45 & 22 \\ \hline

2055 \end{tabular}

2056

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

2058LaTeX, not as markdown.

2059

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

2061and ConTeXt.

2062

2063LaTeX macros

2064------------

2065

2066**Extension: `latex_macros`**

2067

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

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

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

2071not just LaTeX:

2072

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

2074

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

2076

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

2078unchanged to the output.

2079

2080

2081Links

2082-----

2083

2084Markdown allows links to be specified in several ways.

2085

2086### Automatic links ###

2087

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

2089will become a link:

2090

2091 <http://google.com>

2092 <sam@green.eggs.ham>

2093

2094### Inline links ###

2095

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

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

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

2099

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

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

2102

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

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

2105

2106

2107### Reference links ###

2108

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

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

2111before or after the link).

2112

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

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

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

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

2117parentheses.

2118

2119Here are some examples:

2120

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

2122 [my label 2]: /foo

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

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

2125

2126The URL may optionally be surrounded by angle brackets:

2127

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

2129

2130The title may go on the next line:

2131

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

2133 "The free software foundation"

2134

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

2136

2137 Here is [my link][FOO]

2138

2139 [Foo]: /bar/baz

2140

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

2142empty, or omitted entirely:

2143

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

2145

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

2147

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

2149reference link definitions cannot occur in nested constructions

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

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

2152not in most other implementations:

2153

2154 > My block [quote].

2155 >

2156 > [quote]: /foo

2157

2158### Internal links

2159

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

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

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

2163For example:

2164

2165 See the [Introduction](#introduction).

2166

2167or

2168

2169 See the [Introduction].

2170

2171 [Introduction]: #introduction

2172

2173Internal links are currently supported for HTML formats (including

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

2175

2176Images

2177------

2178

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

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

2181

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

2183

2184 ![movie reel]

2185

2186 [movie reel]: movie.gif

2187

2188### Pictures with captions ###

2189

2190**Extension: `implicit_figures`**

2191

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

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

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

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

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

2197

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

2199

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

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

2202 itself, with no caption.

2203

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

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

2206nonbreaking space after the image:

2207

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

2209

2210

2211Footnotes

2212---------

2213

2214**Extension: `footnotes`**

2215

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

2217

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

2219

2220 [^1]: Here is the footnote.

2221

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

2223

2224 Subsequent paragraphs are indented to show that they

2225 belong to the previous footnote.

2226

2227 { some.code }

2228

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

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

2231 multi-paragraph list items.

2232

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

2234 isn't indented.

2235

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

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

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

2239will be numbered sequentially.

2240

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

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

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

2244

2245**Extension: `inline_notes`**

2246

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

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

2249

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

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

2252 note.]

2253

2254Inline and regular footnotes may be mixed freely.

2255

2256

2257Citations

2258---------

2259

2260**Extension: `citations`**

2261

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

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

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

2265

2266 Format File extension

2267 ------------ --------------

2268 MODS .mods

2269 BibLaTeX .bib

2270 BibTeX .bibtex

2271 RIS .ris

2272 EndNote .enl

2273 EndNote XML .xml

2274 ISI .wos

2275 MEDLINE .medline

2276 Copac .copac

2277 JSON citeproc .json

2278

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

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

2281

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

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

2284bibliographies).

2285

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

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

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

2289creating and modifying CSL styles can be found at

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

2291A repository of CSL styles can be found at

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

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

2294

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

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

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

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

2299

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

2301

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

2303

2304 Blah blah [@smith04; @doe99].

2305

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

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

2308author is already mentioned in the text:

2309

2310 Smith says blah [-@smith04].

2311

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

2313

2314 @smith04 says blah.

2315

2316 @smith04 [p. 33] says blah.

2317

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

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

2320document with an appropriate header:

2321

2322 last paragraph...

2323

2324 # References

2325

2326The bibliography will be inserted after this header.

2327

2328Non-pandoc extensions

2329=====================

2330

2331The following markdown syntax extensions are not enabled by default

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

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

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

2335

2336**Extension: `hard_line_breaks`**\

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

2338breaks instead of spaces.

2339

2340**Extension: `tex_math_single_backslash`**\

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

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

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

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

2345

2346**Extension: `tex_math_double_backslash`**\

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

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

2349as display TeX math.

2350

2351**Extension: `markdown_attribute`**\

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

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

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

2355

2356**Extension: `mmd_title_block`**\

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

2358the document, for example:

2359

2360 Title: My title

2361 Author: John Doe

2362 Date: September 1, 2008

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

2364 a field spanning multiple lines.

2365

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

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

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

2369`mmd_title_block`.

2370

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

2372

2373**Extension: `abbrevations`**\

2374Parses PHP Markdown Extra abbreviation keys, like

2375

2376 *[HTML]: Hyper Text Markup Language

2377

2378Note that the pandoc document model does not support

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

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

2381

2382**Extension: `autolink_bare_uris`**\

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

2384pointy braces `<...>`.

2385

2386**Extension: `link_attributes`**\

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

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

2389these, so they are presently just ignored.

2390

2391**Extension: `mmd_header_identifiers`**\

2392Parses multimarkdown style header identifiers (in square brackets,

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

2394

2395Producing slide shows with Pandoc

2396=================================

2397

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

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

2400using [S5], [DZSlides], [Slidy], or [Slideous]. You can also produce a

2401PDF slide show using LaTeX [beamer].

2402

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

2404

2405 % Habits

2406 % John Doe

2407 % March 22, 2005

2408

2409 # In the morning

2410

2411 ## Getting up

2412

2413 - Turn off alarm

2414 - Get out of bed

2415

2416 ## Breakfast

2417

2418 - Eat eggs

2419 - Drink coffee

2420

2421 # In the evening

2422

2423 ## Dinner

2424

2425 - Eat spaghetti

2426 - Drink wine

2427

2428 ------------------

2429

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

2431

2432 ## Going to sleep

2433

2434 - Get in bed

2435 - Count sheep

2436

2437To produce the slide show, simply type

2438

2439 pandoc -t s5 -s habits.txt -o habits.html

2440

2441for S5,

2442

2443 pandoc -t slidy -s habits.txt -o habits.html

2444

2445for Slidy,

2446

2447 pandoc -t slideous -s habits.txt -o habits.html

2448

2449for Slideous,

2450

2451 pandoc -t dzslides -s habits.txt -o habits.html

2452

2453for DZSlides, or

2454

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

2456

2457for beamer.

2458

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

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

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

2462

2463Structuring the slide show

2464--------------------------

2465

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

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

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

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

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

2471the `--slide-level` option.

2472

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

2474rules:

2475

2476 * A horizontal rule always starts a new slide.

2477

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

2479

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

2481 headers *within* a slide.

2482

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

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

2485 and help to break the slide show into sections.

2486

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

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

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

2490

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

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

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

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

2495sections, as in the example above.

2496

2497For Slidy, Slideous and S5, the file produced by pandoc with the

2498`-s/--standalone`

2499option embeds a link to javascripts and CSS files, which are assumed to

2500be available at the relative path `s5/default` (for S5) or `slideous`

2501(for Slideous), or at the Slidy

2502website at `w3.org` (for Slidy). (These paths can be changed by setting

2503the `slidy-url`, `slideous-url` or `s5-url` variables; see `--variable`,

2504above.) For DZSlides,

2505the (relatively short) javascript and css are included in the file by default.

2506

2507Incremental lists

2508-----------------

2509

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

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

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

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

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

2515

2516 > - Eat spaghetti

2517 > - Drink wine

2518

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

2520a single document.

2521

2522Styling the slides

2523------------------

2524

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

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

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

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

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

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

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

2532

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

2534be modified there.

2535

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

2537using the `-V` option:

2538

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

2540

2541Literate Haskell support

2542========================

2543

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

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

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

2547literate Haskell source. This means that

2548

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

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

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

2552

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

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

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

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

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

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

2559

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

2561 as Haskell code.

2562

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

2564 be rendered using bird tracks.

2565

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

2567 Haskell code.

2568

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

2570 inside `code` environments.

2571

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

2573 with class `literatehaskell` and bird tracks.

2574

2575Examples:

2576

2577 pandoc -f markdown+lhs -t html

2578

2579reads literate Haskell source formatted with markdown conventions and writes

2580ordinary HTML (without bird tracks).

2581

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

2583

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

2585and pasted as literate Haskell source.

2586

2587Authors

2588=======

2589

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

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

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

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

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

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

2597Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

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

2600

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

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

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

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

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

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

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

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

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

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

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

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

2613[DocBook XML]: http://www.docbook.org/

2614[OpenDocument XML]: http://opendocument.xml.org/

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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