README · typeable/pandoc

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

1254

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

1256

1257

1258### Numbered example lists ###

1259

1260**Extension: `example_lists`**

1261

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

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

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

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

1266where the last stopped. So, for example:

1267

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

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

1270

1271 Explanation of examples.

1272

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

1274

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

1276document:

1277

1278 (@good) This is a good example.

1279

1280 As (@good) illustrates, ...

1281

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

1283or hyphens.

1284

1285

1286### Compact and loose lists ###

1287

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

1289cases" involving lists. Consider this source:

1290

1291 + First

1292 + Second:

1293 - Fee

1294 - Fie

1295 - Foe

1296

1297 + Third

1298

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

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

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

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

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

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

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

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

1307behavior is consistent with the official markdown syntax description,

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

1309

1310

1311### Ending a list ###

1312

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

1314

1315 - item one

1316 - item two

1317

1318 { my code block }

1319

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

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

1322a code block.

1323

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

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

1326any format:

1327

1328 - item one

1329 - item two

1330

1331

1332

1333 { my code block }

1334

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

1336of one big list:

1337

1338 1. one

1339 2. two

1340 3. three

1341

1342

1343

1344 1. uno

1345 2. dos

1346 3. tres

1347

1348Horizontal rules

1349----------------

1350

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

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

1354 * * * *

1356 ---------------

1359Tables

1360------

1361

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

1363`pipe_tables`, `table_captions`**

1364

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

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

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

1368

1369### Simple tables

1370

1371Simple tables look like this:

1372

1373 Right Left Center Default

1374 ------- ------ ---------- -------

1375 12 12 12 12

1376 123 123 123 123

1377 1 1 1 1

1378

1379 Table: Demonstration of simple table syntax.

1380

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

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

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

1384

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

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

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

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

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

1390 the column is centered.

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

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

1393

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

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

1396

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

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

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

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

1401before or after the table.

1402

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

1404to end the table. For example:

1405

1406 ------- ------ ---------- -------

1407 12 12 12 12

1408 123 123 123 123

1409 1 1 1 1

1410 ------- ------ ---------- -------

1411

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

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

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

1415

1416### Multiline tables

1417

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

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

1420not supported). Here is an example:

1421

1422 -------------------------------------------------------------

1423 Centered Default Right Left

1424 Header Aligned Aligned Aligned

1425 ----------- ------- --------------- -------------------------

1426 First row 12.0 Example of a row that

1427 spans multiple lines.

1428

1429 Second row 5.0 Here's another one. Note

1430 the blank line between

1431 rows.

1432 -------------------------------------------------------------

1433

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

1435 multiple lines.

1436

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

1438

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

1440 (unless the headers are omitted).

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

1442 - The rows must be separated by blank lines.

1443

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

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

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

1447output, try widening it in the markdown source.

1448

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

1450

1451 ----------- ------- --------------- -------------------------

1452 First row 12.0 Example of a row that

1453 spans multiple lines.

1454

1455 Second row 5.0 Here's another one. Note

1456 the blank line between

1457 rows.

1458 -------------------------------------------------------------

1459

1460 : Here's a multiline table without headers.

1461

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

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

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

1465

1466### Grid tables

1467

1468Grid tables look like this:

1469

1470 : Sample grid table.

1471

1472 +---------------+---------------+--------------------+

1473 | Fruit | Price | Advantages |

1474 +===============+===============+====================+

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

1476 | | | - bright color |

1477 +---------------+---------------+--------------------+

1478 | Oranges | $2.10 | - cures scurvy |

1479 | | | - tasty |

1480 +---------------+---------------+--------------------+

1481

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

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

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

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

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

1487

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

1489

1490### Pipe tables

1491

1492Pipe tables look like this:

1493

1495 |------:|:-----|---------|:------:|

1496 | 12 | 12 | 12 | 12 |

1497 | 123 | 123 | 123 | 123 |

1498 | 1 | 1 | 1 | 1 |

1499

1500 : Demonstration of simple table syntax.

1501

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

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

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

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

1506it defines column alignments.

1507

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

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

1510legal (though ugly) pipe table:

1511

1512 fruit| price

1513 -----|-----:

1514 apple|2.05

1515 pear|1.37

1516 orange|3.09

1517

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

1519and lists, and cannot span multiple lines.

1520

1521 [PHP markdown extra]: http://michelf.ca/projects/php-markdown/extra/#table

1522

1523Note: Pandoc also recognizes pipe tables of the following

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

1525

1526 | One | Two |

1527 |-----+-------|

1528 | my | table |

1529 | is | nice |

1530

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

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

1533you'll need to add colons as above.

1534

1535Title block

1536-----------

1537

1538**Extension: `pandoc_title_block`**

1539

1540If the file begins with a title block

1541

1542 % title

1543 % author(s) (separated by semicolons)

1544 % date

1545

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

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

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

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

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

1551

1552 %

1553 % Author

1554

1555 % My title

1556 %

1557 % June 15, 2006

1558

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

1560begin with leading space, thus:

1561

1562 % My title

1563 on multiple lines

1564

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

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

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

1568

1569 % Author One

1570 Author Two

1571

1572 % Author One; Author Two

1573

1574 % Author One;

1575 Author Two

1576

1577The date must fit on one line.

1578

1579All three metadata fields may contain standard inline formatting

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

1581

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

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

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

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

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

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

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

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

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

1591be used by itself as the HTML title.

1592

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

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

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

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

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

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

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

1600text. Thus,

1601

1602 % PANDOC(1)

1603

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

1605

1606 % PANDOC(1) Pandoc User Manuals

1607

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

1609

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

1611

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

1613

1614

1615Backslash escapes

1616-----------------

1617

1618**Extension: `all_symbols_escapable`**

1619

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

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

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

1623

1624 *\*hello\**

1625

1626one will get

1627

1628 <em>*hello*</em>

1629

1630instead of

1631

1632 <strong>hello</strong>

1633

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

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

1636

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

1638

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

1640will be used.)

1641

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

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

1644`\ `.

1645

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

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

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

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

1650two trailing spaces on a line.

1651

1652Backslash escapes do not work in verbatim contexts.

1653

1654Smart punctuation

1655-----------------

1656

1657**Extension**

1658

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

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

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

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

1663

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

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

1666

1667Inline formatting

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

1669

1670### Emphasis ###

1671

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

1673

1674 This text is _emphasized with underscores_, and this

1675 is *emphasized with asterisks*.

1676

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

1678

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

1680

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

1682will not trigger emphasis:

1683

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

1685

1686**Extension: `intraword_underscores`**

1687

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

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

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

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

1692

1693 feas*ible*, not feas*able*.

1694

1695

1696### Strikeout ###

1697

1698**Extension: `strikeout`**

1699

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

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

1702

1703 This ~~is deleted text.~~

1704

1705

1706### Superscripts and subscripts ###

1707

1708**Extension: `superscript`, `subscript`**

1709

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

1711characters; subscripts may be written by surrounding the subscripted

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

1713

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

1715

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

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

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

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

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

1721

1722

1723### Verbatim ###

1724

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

1726

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

1728

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

1730

1731 Here is a literal backtick `` ` ``.

1732

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

1734backticks will be ignored.)

1735

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

1737of consecutive backticks (optionally followed by a space)

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

1739preceded by a space).

1740

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

1742work in verbatim contexts:

1743

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

1745

1746**Extension: `inline_code_attributes`**

1747

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

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

1750

1751 `<$>`{.haskell}

1752

1753Math

1754----

1755

1756**Extension: `tex_math_dollars`**

1757

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

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

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

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

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

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

1764

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

1766depends on the output format:

1767

1768Markdown, LaTeX, Org-Mode, ConTeXt

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

1770

1771reStructuredText

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

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

1774

1775AsciiDoc

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

1777

1778Texinfo

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

1780

1781groff man

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

1783

1784MediaWiki

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

1786

1787Textile

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

1789

1790RTF, OpenDocument, ODT

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

1792 and will otherwise appear verbatim.

1793

1794Docbook

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

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

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

1798

1799Docx

1800 ~ It will be rendered using OMML math markup.

1801

1802FictionBook2

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

1804 using Google Charts or other compatible web service, downloaded

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

1806

1807HTML, Slidy, DZSlides, S5, EPUB

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

1809 command-line options selected:

1810

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

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

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

1814 styled differently from the surrounding text if needed.

1815

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

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

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

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

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

1821 verbatim between `$` characters.)

1822

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

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

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

1826 it.

1827

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

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

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

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

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

1833

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

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

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

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

1838 procedure is:

1839

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

1841 gladtex -d myfile-images myfile.htex

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

1843

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

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

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

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

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

1849

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

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

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

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

1854

1855Raw HTML

1856--------

1857

1858**Extenion: `raw_html`**

1859

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

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

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

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

1864be disabled if desired.)

1865

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

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

1868formats.

1869

1870**Extension: `markdown_in_html_blocks`**

1871

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

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

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

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

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

1877

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

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

1880Thus, for example, Pandoc will turn

1881

1882 <table>

1883 <tr>

1884 <td>*one*</td>

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

1886 </tr>

1887 </table>

1888

1889into

1890

1891 <table>

1892 <tr>

1893 <td><em>one</em></td>

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

1895 </tr>

1896 </table>

1897

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

1899

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

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

1902

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

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

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

1906from being interpreted as markdown.

1907

1908Raw TeX

1909-------

1910

1911**Extension: `raw_tex`**

1912

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

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

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

1916LaTeX to include BibTeX citations:

1917

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

1919

1920Note that in LaTeX environments, like

1921

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

1923 Age & Frequency \\ \hline

1924 18--25 & 15 \\

1925 26--35 & 33 \\

1926 36--45 & 22 \\ \hline

1927 \end{tabular}

1928

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

1930LaTeX, not as markdown.

1931

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

1933and ConTeXt.

1934

1935LaTeX macros

1936------------

1937

1938**Extension: `latex_macros`**

1939

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

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

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

1943not just LaTeX:

1944

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

1946

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

1948

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

1950unchanged to the output.

1951

1952

1953Links

1954-----

1955

1956Markdown allows links to be specified in several ways.

1957

1958### Automatic links ###

1959

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

1961will become a link:

1962

1963 <http://google.com>

1964 <sam@green.eggs.ham>

1965

1966**Extension: `autolink_code_spans`**

1967

1968Pandoc will render autolinked URLs and email addresses as

1969inline code.

1970

1971### Inline links ###

1972

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

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

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

1976

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

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

1979

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

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

1982

1983

1984### Reference links ###

1985

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

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

1988before or after the link).

1989

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

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

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

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

1994parentheses.

1995

1996Here are some examples:

1997

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

1999 [my label 2]: /foo

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

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

2002

2003The URL may optionally be surrounded by angle brackets:

2004

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

2006

2007The title may go on the next line:

2008

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

2010 "The free software foundation"

2011

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

2013

2014 Here is [my link][FOO]

2015

2016 [Foo]: /bar/baz

2017

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

2019empty, or omitted entirely:

2020

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

2022

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

2024

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

2026reference link definitions cannot occur in nested constructions

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

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

2029not in most other implementations:

2030

2031 > My block [quote].

2032 >

2033 > [quote]: /foo

2034

2035### Internal links

2036

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

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

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

2040For example:

2041

2042 See the [Introduction](#introduction).

2043

2044or

2045

2046 See the [Introduction].

2047

2048 [Introduction]: #introduction

2049

2050Internal links are currently supported for HTML formats (including

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

2052

2053Images

2054------

2055

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

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

2058

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

2060

2061 ![movie reel]

2062

2063 [movie reel]: movie.gif

2064

2065### Pictures with captions ###

2066

2067**Extension**

2068

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

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

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

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

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

2074

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

2076

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

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

2079 itself, with no caption.

2080

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

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

2083nonbreaking space after the image:

2084

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

2086

2087

2088Footnotes

2089---------

2090

2091**Extension: `footnotes`**

2092

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

2094

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

2096

2097 [^1]: Here is the footnote.

2098

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

2100

2101 Subsequent paragraphs are indented to show that they

2102 belong to the previous footnote.

2103

2104 { some.code }

2105

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

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

2108 multi-paragraph list items.

2109

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

2111 isn't indented.

2112

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

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

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

2116will be numbered sequentially.

2117

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

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

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

2121

2122**Extension: `inline_notes`**

2123

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

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

2126

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

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

2129 note.]

2130

2131Inline and regular footnotes may be mixed freely.

2132

2133

2134Citations

2135---------

2136

2137**Extension: `citations`**

2138

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

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

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

2142

2143 Format File extension

2144 ------------ --------------

2145 MODS .mods

2146 BibTeX/BibLaTeX .bib

2147 RIS .ris

2148 EndNote .enl

2149 EndNote XML .xml

2150 ISI .wos

2151 MEDLINE .medline

2152 Copac .copac

2153 JSON citeproc .json

2154

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

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

2157bibliographies).

2158

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

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

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

2162creating and modifying CSL styles can be found at

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

2164A repository of CSL styles can be found at

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

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

2167

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

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

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

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

2172

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

2174

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

2176

2177 Blah blah [@smith04; @doe99].

2178

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

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

2181author is already mentioned in the text:

2182

2183 Smith says blah [-@smith04].

2184

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

2186

2187 @smith04 says blah.

2188

2189 @smith04 [p. 33] says blah.

2190

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

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

2193document with an appropriate header:

2194

2195 last paragraph...

2196

2197 # References

2198

2199The bibliography will be inserted after this header.

2200

2201Non-pandoc extensions

2202=====================

2203

2204The following markdown syntax extensions are not enabled by default

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

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

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

2208

2209**Extension: `hard_line_breaks`**\

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

2211breaks instead of spaces.

2212

2213**Extension: `tex_math_single_backslash`**\

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

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

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

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

2218

2219**Extension: `tex_math_double_backslash`**\

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

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

2222as display TeX math.

2223

2224**Extension: `markdown_attribute`**\

2225Causes the attribute `markdown=1` to be added to all block-level

2226HTML tags that might contain markdown. In pandoc, material inside

2227block-level tags is interpreted a markdown by default, but in some

2228other implementations, the `markdown=1` tag is needed.

2229

2230**Extension: `mmd_title_block`**\

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

2232the document, for example:

2233

2234 Title: My title

2235 Author: John Doe

2236 Date: September 1, 2008

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

2238 a field spanning multiple lines.

2239

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

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

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

2243`mmd_title_block`.

2244

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

2246

2247**Extension: `abbrevations`**\

2248Parses PHP Markdown Extra abbreviation keys, like

2249

2250 *[HTML]: Hyper Text Markup Language

2251

2252Note that the pandoc document model does not support

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

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

2255

2256Producing slide shows with Pandoc

2257=================================

2258

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

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

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

2262PDF slide show using LaTeX [beamer].

2263

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

2265

2266 % Habits

2267 % John Doe

2268 % March 22, 2005

2269

2270 # In the morning

2271

2272 ## Getting up

2273

2274 - Turn off alarm

2275 - Get out of bed

2276

2277 ## Breakfast

2278

2279 - Eat eggs

2280 - Drink coffee

2281

2282 # In the evening

2283

2284 ## Dinner

2285

2286 - Eat spaghetti

2287 - Drink wine

2288

2289 ------------------

2290

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

2292

2293 ## Going to sleep

2294

2295 - Get in bed

2296 - Count sheep

2297

2298To produce the slide show, simply type

2299

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

2301

2302for S5,

2303

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

2305

2306for Slidy,

2307

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

2309

2310for Slideous,

2311

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

2313

2314for DZSlides, or

2315

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

2317

2318for beamer.

2319

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

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

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

2323

2324Structuring the slide show

2325--------------------------

2326

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

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

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

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

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

2332the `--slide-level` option.

2333

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

2335rules:

2336

2337 * A horizontal rule always starts a new slide.

2338

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

2340

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

2342 headers *within* a slide.

2343

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

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

2346 and help to break the slide show into sections.

2347

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

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

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

2351

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

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

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

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

2356sections, as in the example above.

2357

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

2359`-s/--standalone`

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

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

2362(for Slideous), or at the Slidy

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

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

2365above.) For DZSlides,

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

2367

2368Incremental lists

2369-----------------

2370

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

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

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

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

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

2376

2377 > - Eat spaghetti

2378 > - Drink wine

2379

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

2381a single document.

2382

2383Styling the slides

2384------------------

2385

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

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

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

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

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

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

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

2393

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

2395be modified there.

2396

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

2398using the `-V` option:

2399

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

2401

2402Literate Haskell support

2403========================

2404

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

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

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

2408literate Haskell source. This means that

2409

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

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

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

2413

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

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

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

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

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

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

2420

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

2422 as Haskell code.

2423

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

2425 be rendered using bird tracks.

2426

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

2428 Haskell code.

2429

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

2431 inside `code` environments.

2432

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

2434 with class `literatehaskell` and bird tracks.

2435

2436Examples:

2437

2438 pandoc -f markdown+lhs -t html

2439

2440reads literate Haskell source formatted with markdown conventions and writes

2441ordinary HTML (without bird tracks).

2442

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

2444

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

2446and pasted as literate Haskell source.

2447

2448Authors

2449=======

2450

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

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

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

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

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

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

2458Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

2460Sergey Astanin.

2461

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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