README · typeable/pandoc

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

1344

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

1346

1347

1348### Numbered example lists ###

1349

1350**Extension: `example_lists`**

1351

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

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

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

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

1356where the last stopped. So, for example:

1357

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

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

1360

1361 Explanation of examples.

1362

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

1364

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

1366document:

1367

1368 (@good) This is a good example.

1369

1370 As (@good) illustrates, ...

1371

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

1373or hyphens.

1374

1375

1376### Compact and loose lists ###

1377

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

1379cases" involving lists. Consider this source:

1380

1381 + First

1382 + Second:

1383 - Fee

1384 - Fie

1385 - Foe

1386

1387 + Third

1388

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

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

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

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

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

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

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

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

1397behavior is consistent with the official markdown syntax description,

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

1399

1400

1401### Ending a list ###

1402

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

1404

1405 - item one

1406 - item two

1407

1408 { my code block }

1409

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

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

1412a code block.

1413

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

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

1416any format:

1417

1418 - item one

1419 - item two

1420

1421

1422

1423 { my code block }

1424

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

1426of one big list:

1427

1428 1. one

1429 2. two

1430 3. three

1431

1432

1433

1434 1. uno

1435 2. dos

1436 3. tres

1437

1438Horizontal rules

1439----------------

1440

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

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

1444 * * * *

1446 ---------------

1449Tables

1450------

1451

1452**Extension: `simple_tables`, `multiline_tables`, `grid_tables`,

1453`pipe_tables`, `table_captions`**

1454

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

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

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

1458

1459### Simple tables

1460

1461Simple tables look like this:

1462

1463 Right Left Center Default

1464 ------- ------ ---------- -------

1465 12 12 12 12

1466 123 123 123 123

1467 1 1 1 1

1468

1469 Table: Demonstration of simple table syntax.

1470

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

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

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

1474

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

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

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

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

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

1480 the column is centered.

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

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

1483

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

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

1486

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

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

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

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

1491before or after the table.

1492

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

1494to end the table. For example:

1495

1496 ------- ------ ---------- -------

1497 12 12 12 12

1498 123 123 123 123

1499 1 1 1 1

1500 ------- ------ ---------- -------

1501

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

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

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

1505

1506### Multiline tables

1507

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

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

1510not supported). Here is an example:

1511

1512 -------------------------------------------------------------

1513 Centered Default Right Left

1514 Header Aligned Aligned Aligned

1515 ----------- ------- --------------- -------------------------

1516 First row 12.0 Example of a row that

1517 spans multiple lines.

1518

1519 Second row 5.0 Here's another one. Note

1520 the blank line between

1521 rows.

1522 -------------------------------------------------------------

1523

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

1525 multiple lines.

1526

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

1528

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

1530 (unless the headers are omitted).

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

1532 - The rows must be separated by blank lines.

1533

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

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

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

1537output, try widening it in the markdown source.

1538

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

1540

1541 ----------- ------- --------------- -------------------------

1542 First row 12.0 Example of a row that

1543 spans multiple lines.

1544

1545 Second row 5.0 Here's another one. Note

1546 the blank line between

1547 rows.

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

1549

1550 : Here's a multiline table without headers.

1551

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

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

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

1555

1556### Grid tables

1557

1558Grid tables look like this:

1559

1560 : Sample grid table.

1561

1562 +---------------+---------------+--------------------+

1563 | Fruit | Price | Advantages |

1564 +===============+===============+====================+

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

1566 | | | - bright color |

1567 +---------------+---------------+--------------------+

1568 | Oranges | $2.10 | - cures scurvy |

1569 | | | - tasty |

1570 +---------------+---------------+--------------------+

1571

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

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

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

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

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

1577

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

1579

1580### Pipe tables

1581

1582Pipe tables look like this:

1583

1585 |------:|:-----|---------|:------:|

1586 | 12 | 12 | 12 | 12 |

1587 | 123 | 123 | 123 | 123 |

1588 | 1 | 1 | 1 | 1 |

1589

1590 : Demonstration of simple table syntax.

1591

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

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

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

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

1596it defines column alignments.

1597

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

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

1600legal (though ugly) pipe table:

1601

1602 fruit| price

1603 -----|-----:

1604 apple|2.05

1605 pear|1.37

1606 orange|3.09

1607

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

1609and lists, and cannot span multiple lines.

1610

1611 [the same as in PHP markdown extra]:

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

1613

1614Note: Pandoc also recognizes pipe tables of the following

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

1616

1617 | One | Two |

1618 |-----+-------|

1619 | my | table |

1620 | is | nice |

1621

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

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

1624you'll need to add colons as above.

1625

1626Title block

1627-----------

1628

1629**Extension: `pandoc_title_block`**

1630

1631If the file begins with a title block

1632

1633 % title

1634 % author(s) (separated by semicolons)

1635 % date

1636

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

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

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

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

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

1642

1643 %

1644 % Author

1645

1646 % My title

1647 %

1648 % June 15, 2006

1649

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

1651begin with leading space, thus:

1652

1653 % My title

1654 on multiple lines

1655

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

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

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

1659

1660 % Author One

1661 Author Two

1662

1663 % Author One; Author Two

1664

1665 % Author One;

1666 Author Two

1667

1668The date must fit on one line.

1669

1670All three metadata fields may contain standard inline formatting

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

1672

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

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

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

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

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

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

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

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

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

1682be used by itself as the HTML title.

1683

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

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

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

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

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

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

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

1691text. Thus,

1692

1693 % PANDOC(1)

1694

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

1696

1697 % PANDOC(1) Pandoc User Manuals

1698

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

1700

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

1702

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

1704

1705

1706Backslash escapes

1707-----------------

1708

1709**Extension: `all_symbols_escapable`**

1710

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

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

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

1714

1715 *\*hello\**

1716

1717one will get

1718

1719 <em>*hello*</em>

1720

1721instead of

1722

1723 <strong>hello</strong>

1724

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

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

1727

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

1729

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

1731will be used.)

1732

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

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

1735`\ `.

1736

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

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

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

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

1741two trailing spaces on a line.

1742

1743Backslash escapes do not work in verbatim contexts.

1744

1745Smart punctuation

1746-----------------

1747

1748**Extension**

1749

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

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

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

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

1754

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

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

1757

1758Inline formatting

1759-----------------

1760

1761### Emphasis ###

1762

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

1764

1765 This text is _emphasized with underscores_, and this

1766 is *emphasized with asterisks*.

1767

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

1769

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

1771

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

1773will not trigger emphasis:

1774

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

1776

1777**Extension: `intraword_underscores`**

1778

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

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

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

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

1783

1784 feas*ible*, not feas*able*.

1785

1786

1787### Strikeout ###

1788

1789**Extension: `strikeout`**

1790

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

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

1793

1794 This ~~is deleted text.~~

1795

1796

1797### Superscripts and subscripts ###

1798

1799**Extension: `superscript`, `subscript`**

1800

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

1802characters; subscripts may be written by surrounding the subscripted

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

1804

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

1806

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

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

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

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

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

1812

1813

1814### Verbatim ###

1815

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

1817

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

1819

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

1821

1822 Here is a literal backtick `` ` ``.

1823

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

1825backticks will be ignored.)

1826

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

1828of consecutive backticks (optionally followed by a space)

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

1830preceded by a space).

1831

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

1833work in verbatim contexts:

1834

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

1836

1837**Extension: `inline_code_attributes`**

1838

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

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

1841

1842 `<$>`{.haskell}

1843

1844Math

1845----

1846

1847**Extension: `tex_math_dollars`**

1848

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

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

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

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

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

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

1855

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

1857depends on the output format:

1858

1859Markdown, LaTeX, Org-Mode, ConTeXt

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

1861

1862reStructuredText

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

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

1865

1866AsciiDoc

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

1868

1869Texinfo

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

1871

1872groff man

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

1874

1875MediaWiki

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

1877

1878Textile

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

1880

1881RTF, OpenDocument, ODT

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

1883 and will otherwise appear verbatim.

1884

1885Docbook

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

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

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

1889

1890Docx

1891 ~ It will be rendered using OMML math markup.

1892

1893FictionBook2

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

1895 using Google Charts or other compatible web service, downloaded

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

1897

1898HTML, Slidy, DZSlides, S5, EPUB

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

1900 command-line options selected:

1901

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

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

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

1905 styled differently from the surrounding text if needed.

1906

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

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

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

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

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

1912 verbatim between `$` characters.)

1913

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

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

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

1917 it.

1918

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

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

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

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

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

1924

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

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

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

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

1929 procedure is:

1930

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

1932 gladtex -d myfile-images myfile.htex

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

1934

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

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

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

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

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

1940

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

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

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

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

1945

1946Raw HTML

1947--------

1948

1949**Extension: `raw_html`**

1950

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

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

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

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

1955be disabled if desired.)

1956

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

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

1959formats.

1960

1961**Extension: `markdown_in_html_blocks`**

1962

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

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

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

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

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

1968

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

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

1971Thus, for example, Pandoc will turn

1972

1973 <table>

1974 <tr>

1975 <td>*one*</td>

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

1977 </tr>

1978 </table>

1979

1980into

1981

1982 <table>

1983 <tr>

1984 <td><em>one</em></td>

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

1986 </tr>

1987 </table>

1988

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

1990

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

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

1993

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

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

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

1997from being interpreted as markdown.

1998

1999Raw TeX

2000-------

2001

2002**Extension: `raw_tex`**

2003

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

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

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

2007LaTeX to include BibTeX citations:

2008

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

2010

2011Note that in LaTeX environments, like

2012

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

2014 Age & Frequency \\ \hline

2015 18--25 & 15 \\

2016 26--35 & 33 \\

2017 36--45 & 22 \\ \hline

2018 \end{tabular}

2019

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

2021LaTeX, not as markdown.

2022

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

2024and ConTeXt.

2025

2026LaTeX macros

2027------------

2028

2029**Extension: `latex_macros`**

2030

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

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

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

2034not just LaTeX:

2035

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

2037

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

2039

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

2041unchanged to the output.

2042

2043

2044Links

2045-----

2046

2047Markdown allows links to be specified in several ways.

2048

2049### Automatic links ###

2050

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

2052will become a link:

2053

2054 <http://google.com>

2055 <sam@green.eggs.ham>

2056

2057### Inline links ###

2058

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

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

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

2062

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

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

2065

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

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

2068

2069

2070### Reference links ###

2071

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

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

2074before or after the link).

2075

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

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

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

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

2080parentheses.

2081

2082Here are some examples:

2083

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

2085 [my label 2]: /foo

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

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

2088

2089The URL may optionally be surrounded by angle brackets:

2090

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

2092

2093The title may go on the next line:

2094

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

2096 "The free software foundation"

2097

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

2099

2100 Here is [my link][FOO]

2101

2102 [Foo]: /bar/baz

2103

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

2105empty, or omitted entirely:

2106

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

2108

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

2110

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

2112reference link definitions cannot occur in nested constructions

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

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

2115not in most other implementations:

2116

2117 > My block [quote].

2118 >

2119 > [quote]: /foo

2120

2121### Internal links

2122

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

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

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

2126For example:

2127

2128 See the [Introduction](#introduction).

2129

2130or

2131

2132 See the [Introduction].

2133

2134 [Introduction]: #introduction

2135

2136Internal links are currently supported for HTML formats (including

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

2138

2139Images

2140------

2141

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

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

2144

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

2146

2147 ![movie reel]

2148

2149 [movie reel]: movie.gif

2150

2151### Pictures with captions ###

2152

2153**Extension: `implicit_figures`**

2154

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

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

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

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

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

2160

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

2162

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

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

2165 itself, with no caption.

2166

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

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

2169nonbreaking space after the image:

2170

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

2172

2173

2174Footnotes

2175---------

2176

2177**Extension: `footnotes`**

2178

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

2180

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

2182

2183 [^1]: Here is the footnote.

2184

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

2186

2187 Subsequent paragraphs are indented to show that they

2188 belong to the previous footnote.

2189

2190 { some.code }

2191

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

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

2194 multi-paragraph list items.

2195

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

2197 isn't indented.

2198

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

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

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

2202will be numbered sequentially.

2203

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

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

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

2207

2208**Extension: `inline_notes`**

2209

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

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

2212

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

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

2215 note.]

2216

2217Inline and regular footnotes may be mixed freely.

2218

2219

2220Citations

2221---------

2222

2223**Extension: `citations`**

2224

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

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

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

2228

2229 Format File extension

2230 ------------ --------------

2231 MODS .mods

2232 BibLaTeX .bib

2233 BibTeX .bibtex

2234 RIS .ris

2235 EndNote .enl

2236 EndNote XML .xml

2237 ISI .wos

2238 MEDLINE .medline

2239 Copac .copac

2240 JSON citeproc .json

2241

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

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

2244

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

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

2247bibliographies).

2248

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

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

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

2252creating and modifying CSL styles can be found at

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

2254A repository of CSL styles can be found at

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

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

2257

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

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

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

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

2262

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

2264

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

2266

2267 Blah blah [@smith04; @doe99].

2268

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

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

2271author is already mentioned in the text:

2272

2273 Smith says blah [-@smith04].

2274

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

2276

2277 @smith04 says blah.

2278

2279 @smith04 [p. 33] says blah.

2280

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

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

2283document with an appropriate header:

2284

2285 last paragraph...

2286

2287 # References

2288

2289The bibliography will be inserted after this header.

2290

2291Non-pandoc extensions

2292=====================

2293

2294The following markdown syntax extensions are not enabled by default

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

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

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

2298

2299**Extension: `hard_line_breaks`**\

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

2301breaks instead of spaces.

2302

2303**Extension: `tex_math_single_backslash`**\

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

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

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

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

2308

2309**Extension: `tex_math_double_backslash`**\

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

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

2312as display TeX math.

2313

2314**Extension: `markdown_attribute`**\

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

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

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

2318

2319**Extension: `mmd_title_block`**\

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

2321the document, for example:

2322

2323 Title: My title

2324 Author: John Doe

2325 Date: September 1, 2008

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

2327 a field spanning multiple lines.

2328

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

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

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

2332`mmd_title_block`.

2333

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

2335

2336**Extension: `abbrevations`**\

2337Parses PHP Markdown Extra abbreviation keys, like

2338

2339 *[HTML]: Hyper Text Markup Language

2340

2341Note that the pandoc document model does not support

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

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

2344

2345**Extension: `autolink_urls`**\

2346Makes all absolute URLs into links, even when not surrounded by

2347pointy braces `<...>`.

2348

2349Producing slide shows with Pandoc

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

2351

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

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

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

2355PDF slide show using LaTeX [beamer].

2356

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

2358

2359 % Habits

2360 % John Doe

2361 % March 22, 2005

2362

2363 # In the morning

2364

2365 ## Getting up

2366

2367 - Turn off alarm

2368 - Get out of bed

2369

2370 ## Breakfast

2371

2372 - Eat eggs

2373 - Drink coffee

2374

2375 # In the evening

2376

2377 ## Dinner

2378

2379 - Eat spaghetti

2380 - Drink wine

2381

2382 ------------------

2383

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

2385

2386 ## Going to sleep

2387

2388 - Get in bed

2389 - Count sheep

2390

2391To produce the slide show, simply type

2392

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

2394

2395for S5,

2396

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

2398

2399for Slidy,

2400

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

2402

2403for Slideous,

2404

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

2406

2407for DZSlides, or

2408

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

2410

2411for beamer.

2412

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

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

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

2416

2417Structuring the slide show

2418--------------------------

2419

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

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

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

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

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

2425the `--slide-level` option.

2426

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

2428rules:

2429

2430 * A horizontal rule always starts a new slide.

2431

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

2433

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

2435 headers *within* a slide.

2436

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

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

2439 and help to break the slide show into sections.

2440

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

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

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

2444

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

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

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

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

2449sections, as in the example above.

2450

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

2452`-s/--standalone`

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

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

2455(for Slideous), or at the Slidy

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

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

2458above.) For DZSlides,

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

2460

2461Incremental lists

2462-----------------

2463

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

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

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

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

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

2469

2470 > - Eat spaghetti

2471 > - Drink wine

2472

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

2474a single document.

2475

2476Styling the slides

2477------------------

2478

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

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

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

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

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

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

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

2486

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

2488be modified there.

2489

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

2491using the `-V` option:

2492

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

2494

2495Literate Haskell support

2496========================

2497

2498If you append `+lhs` to an appropriate input or output format (`markdown`,

2499`mardkown_strict`, `rst`, or `latex` for input or output; `beamer`,

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

2501literate Haskell source. This means that

2502

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

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

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

2506

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

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

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

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

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

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

2513

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

2515 as Haskell code.

2516

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

2518 be rendered using bird tracks.

2519

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

2521 Haskell code.

2522

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

2524 inside `code` environments.

2525

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

2527 with class `literatehaskell` and bird tracks.

2528

2529Examples:

2530

2531 pandoc -f markdown+lhs -t html

2532

2533reads literate Haskell source formatted with markdown conventions and writes

2534ordinary HTML (without bird tracks).

2535

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

2537

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

2539and pasted as literate Haskell source.

2540

2541Authors

2542=======

2543

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

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

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

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

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

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

2551Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

2553Sergey Astanin.

2554

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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