README · typeable/pandoc

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

1290

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

1292

1293

1294### Numbered example lists ###

1295

1296**Extension: `example_lists`**

1297

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

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

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

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

1302where the last stopped. So, for example:

1303

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

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

1306

1307 Explanation of examples.

1308

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

1310

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

1312document:

1313

1314 (@good) This is a good example.

1315

1316 As (@good) illustrates, ...

1317

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

1319or hyphens.

1320

1321

1322### Compact and loose lists ###

1323

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

1325cases" involving lists. Consider this source:

1326

1327 + First

1328 + Second:

1329 - Fee

1330 - Fie

1331 - Foe

1332

1333 + Third

1334

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

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

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

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

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

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

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

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

1343behavior is consistent with the official markdown syntax description,

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

1345

1346

1347### Ending a list ###

1348

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

1350

1351 - item one

1352 - item two

1353

1354 { my code block }

1355

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

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

1358a code block.

1359

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

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

1362any format:

1363

1364 - item one

1365 - item two

1366

1367

1368

1369 { my code block }

1370

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

1372of one big list:

1373

1374 1. one

1375 2. two

1376 3. three

1377

1378

1379

1380 1. uno

1381 2. dos

1382 3. tres

1383

1384Horizontal rules

1385----------------

1386

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

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

1390 * * * *

1392 ---------------

1395Tables

1396------

1397

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

1399`pipe_tables`, `table_captions`**

1400

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

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

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

1404

1405### Simple tables

1406

1407Simple tables look like this:

1408

1409 Right Left Center Default

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

1411 12 12 12 12

1412 123 123 123 123

1413 1 1 1 1

1414

1415 Table: Demonstration of simple table syntax.

1416

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

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

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

1420

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

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

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

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

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

1426 the column is centered.

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

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

1429

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

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

1432

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

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

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

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

1437before or after the table.

1438

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

1440to end the table. For example:

1441

1442 ------- ------ ---------- -------

1443 12 12 12 12

1444 123 123 123 123

1445 1 1 1 1

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

1447

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

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

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

1451

1452### Multiline tables

1453

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

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

1456not supported). Here is an example:

1457

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

1459 Centered Default Right Left

1460 Header Aligned Aligned Aligned

1461 ----------- ------- --------------- -------------------------

1462 First row 12.0 Example of a row that

1463 spans multiple lines.

1464

1465 Second row 5.0 Here's another one. Note

1466 the blank line between

1467 rows.

1468 -------------------------------------------------------------

1469

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

1471 multiple lines.

1472

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

1474

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

1476 (unless the headers are omitted).

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

1478 - The rows must be separated by blank lines.

1479

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

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

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

1483output, try widening it in the markdown source.

1484

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

1486

1487 ----------- ------- --------------- -------------------------

1488 First row 12.0 Example of a row that

1489 spans multiple lines.

1490

1491 Second row 5.0 Here's another one. Note

1492 the blank line between

1493 rows.

1494 -------------------------------------------------------------

1495

1496 : Here's a multiline table without headers.

1497

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

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

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

1501

1502### Grid tables

1503

1504Grid tables look like this:

1505

1506 : Sample grid table.

1507

1508 +---------------+---------------+--------------------+

1509 | Fruit | Price | Advantages |

1510 +===============+===============+====================+

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

1512 | | | - bright color |

1513 +---------------+---------------+--------------------+

1514 | Oranges | $2.10 | - cures scurvy |

1515 | | | - tasty |

1516 +---------------+---------------+--------------------+

1517

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

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

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

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

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

1523

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

1525

1526### Pipe tables

1527

1528Pipe tables look like this:

1529

1531 |------:|:-----|---------|:------:|

1532 | 12 | 12 | 12 | 12 |

1533 | 123 | 123 | 123 | 123 |

1534 | 1 | 1 | 1 | 1 |

1535

1536 : Demonstration of simple table syntax.

1537

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

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

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

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

1542it defines column alignments.

1543

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

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

1546legal (though ugly) pipe table:

1547

1548 fruit| price

1549 -----|-----:

1550 apple|2.05

1551 pear|1.37

1552 orange|3.09

1553

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

1555and lists, and cannot span multiple lines.

1556

1557 [the same as in PHP markdown extra]:

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

1559

1560Note: Pandoc also recognizes pipe tables of the following

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

1562

1563 | One | Two |

1564 |-----+-------|

1565 | my | table |

1566 | is | nice |

1567

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

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

1570you'll need to add colons as above.

1571

1572Title block

1573-----------

1574

1575**Extension: `pandoc_title_block`**

1576

1577If the file begins with a title block

1578

1579 % title

1580 % author(s) (separated by semicolons)

1581 % date

1582

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

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

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

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

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

1588

1589 %

1590 % Author

1591

1592 % My title

1593 %

1594 % June 15, 2006

1595

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

1597begin with leading space, thus:

1598

1599 % My title

1600 on multiple lines

1601

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

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

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

1605

1606 % Author One

1607 Author Two

1608

1609 % Author One; Author Two

1610

1611 % Author One;

1612 Author Two

1613

1614The date must fit on one line.

1615

1616All three metadata fields may contain standard inline formatting

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

1618

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

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

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

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

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

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

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

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

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

1628be used by itself as the HTML title.

1629

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

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

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

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

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

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

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

1637text. Thus,

1638

1639 % PANDOC(1)

1640

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

1642

1643 % PANDOC(1) Pandoc User Manuals

1644

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

1646

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

1648

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

1650

1651

1652Backslash escapes

1653-----------------

1654

1655**Extension: `all_symbols_escapable`**

1656

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

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

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

1660

1661 *\*hello\**

1662

1663one will get

1664

1665 <em>*hello*</em>

1666

1667instead of

1668

1669 <strong>hello</strong>

1670

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

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

1673

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

1675

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

1677will be used.)

1678

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

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

1681`\ `.

1682

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

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

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

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

1687two trailing spaces on a line.

1688

1689Backslash escapes do not work in verbatim contexts.

1690

1691Smart punctuation

1692-----------------

1693

1694**Extension**

1695

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

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

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

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

1700

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

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

1703

1704Inline formatting

1705-----------------

1706

1707### Emphasis ###

1708

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

1710

1711 This text is _emphasized with underscores_, and this

1712 is *emphasized with asterisks*.

1713

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

1715

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

1717

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

1719will not trigger emphasis:

1720

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

1722

1723**Extension: `intraword_underscores`**

1724

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

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

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

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

1729

1730 feas*ible*, not feas*able*.

1731

1732

1733### Strikeout ###

1734

1735**Extension: `strikeout`**

1736

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

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

1739

1740 This ~~is deleted text.~~

1741

1742

1743### Superscripts and subscripts ###

1744

1745**Extension: `superscript`, `subscript`**

1746

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

1748characters; subscripts may be written by surrounding the subscripted

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

1750

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

1752

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

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

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

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

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

1758

1759

1760### Verbatim ###

1761

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

1763

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

1765

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

1767

1768 Here is a literal backtick `` ` ``.

1769

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

1771backticks will be ignored.)

1772

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

1774of consecutive backticks (optionally followed by a space)

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

1776preceded by a space).

1777

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

1779work in verbatim contexts:

1780

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

1782

1783**Extension: `inline_code_attributes`**

1784

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

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

1787

1788 `<$>`{.haskell}

1789

1790Math

1791----

1792

1793**Extension: `tex_math_dollars`**

1794

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

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

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

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

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

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

1801

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

1803depends on the output format:

1804

1805Markdown, LaTeX, Org-Mode, ConTeXt

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

1807

1808reStructuredText

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

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

1811

1812AsciiDoc

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

1814

1815Texinfo

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

1817

1818groff man

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

1820

1821MediaWiki

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

1823

1824Textile

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

1826

1827RTF, OpenDocument, ODT

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

1829 and will otherwise appear verbatim.

1830

1831Docbook

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

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

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

1835

1836Docx

1837 ~ It will be rendered using OMML math markup.

1838

1839FictionBook2

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

1841 using Google Charts or other compatible web service, downloaded

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

1843

1844HTML, Slidy, DZSlides, S5, EPUB

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

1846 command-line options selected:

1847

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

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

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

1851 styled differently from the surrounding text if needed.

1852

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

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

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

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

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

1858 verbatim between `$` characters.)

1859

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

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

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

1863 it.

1864

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

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

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

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

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

1870

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

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

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

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

1875 procedure is:

1876

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

1878 gladtex -d myfile-images myfile.htex

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

1880

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

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

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

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

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

1886

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

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

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

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

1891

1892Raw HTML

1893--------

1894

1895**Extension: `raw_html`**

1896

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

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

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

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

1901be disabled if desired.)

1902

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

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

1905formats.

1906

1907**Extension: `markdown_in_html_blocks`**

1908

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

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

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

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

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

1914

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

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

1917Thus, for example, Pandoc will turn

1918

1919 <table>

1920 <tr>

1921 <td>*one*</td>

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

1923 </tr>

1924 </table>

1925

1926into

1927

1928 <table>

1929 <tr>

1930 <td><em>one</em></td>

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

1932 </tr>

1933 </table>

1934

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

1936

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

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

1939

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

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

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

1943from being interpreted as markdown.

1944

1945Raw TeX

1946-------

1947

1948**Extension: `raw_tex`**

1949

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

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

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

1953LaTeX to include BibTeX citations:

1954

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

1956

1957Note that in LaTeX environments, like

1958

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

1960 Age & Frequency \\ \hline

1961 18--25 & 15 \\

1962 26--35 & 33 \\

1963 36--45 & 22 \\ \hline

1964 \end{tabular}

1965

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

1967LaTeX, not as markdown.

1968

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

1970and ConTeXt.

1971

1972LaTeX macros

1973------------

1974

1975**Extension: `latex_macros`**

1976

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

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

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

1980not just LaTeX:

1981

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

1983

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

1985

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

1987unchanged to the output.

1988

1989

1990Links

1991-----

1992

1993Markdown allows links to be specified in several ways.

1994

1995### Automatic links ###

1996

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

1998will become a link:

1999

2000 <http://google.com>

2001 <sam@green.eggs.ham>

2002

2003### Inline links ###

2004

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

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

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

2008

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

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

2011

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

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

2014

2015

2016### Reference links ###

2017

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

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

2020before or after the link).

2021

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

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

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

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

2026parentheses.

2027

2028Here are some examples:

2029

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

2031 [my label 2]: /foo

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

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

2034

2035The URL may optionally be surrounded by angle brackets:

2036

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

2038

2039The title may go on the next line:

2040

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

2042 "The free software foundation"

2043

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

2045

2046 Here is [my link][FOO]

2047

2048 [Foo]: /bar/baz

2049

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

2051empty, or omitted entirely:

2052

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

2054

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

2056

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

2058reference link definitions cannot occur in nested constructions

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

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

2061not in most other implementations:

2062

2063 > My block [quote].

2064 >

2065 > [quote]: /foo

2066

2067### Internal links

2068

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

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

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

2072For example:

2073

2074 See the [Introduction](#introduction).

2075

2076or

2077

2078 See the [Introduction].

2079

2080 [Introduction]: #introduction

2081

2082Internal links are currently supported for HTML formats (including

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

2084

2085Images

2086------

2087

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

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

2090

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

2092

2093 ![movie reel]

2094

2095 [movie reel]: movie.gif

2096

2097### Pictures with captions ###

2098

2099**Extension**

2100

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

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

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

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

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

2106

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

2108

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

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

2111 itself, with no caption.

2112

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

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

2115nonbreaking space after the image:

2116

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

2118

2119

2120Footnotes

2121---------

2122

2123**Extension: `footnotes`**

2124

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

2126

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

2128

2129 [^1]: Here is the footnote.

2130

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

2132

2133 Subsequent paragraphs are indented to show that they

2134 belong to the previous footnote.

2135

2136 { some.code }

2137

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

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

2140 multi-paragraph list items.

2141

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

2143 isn't indented.

2144

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

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

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

2148will be numbered sequentially.

2149

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

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

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

2153

2154**Extension: `inline_notes`**

2155

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

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

2158

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

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

2161 note.]

2162

2163Inline and regular footnotes may be mixed freely.

2164

2165

2166Citations

2167---------

2168

2169**Extension: `citations`**

2170

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

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

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

2174

2175 Format File extension

2176 ------------ --------------

2177 MODS .mods

2178 BibLaTeX .bib

2179 BibTeX .bibtex

2180 RIS .ris

2181 EndNote .enl

2182 EndNote XML .xml

2183 ISI .wos

2184 MEDLINE .medline

2185 Copac .copac

2186 JSON citeproc .json

2187

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

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

2190

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

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

2193bibliographies).

2194

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

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

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

2198creating and modifying CSL styles can be found at

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

2200A repository of CSL styles can be found at

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

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

2203

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

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

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

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

2208

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

2210

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

2212

2213 Blah blah [@smith04; @doe99].

2214

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

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

2217author is already mentioned in the text:

2218

2219 Smith says blah [-@smith04].

2220

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

2222

2223 @smith04 says blah.

2224

2225 @smith04 [p. 33] says blah.

2226

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

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

2229document with an appropriate header:

2230

2231 last paragraph...

2232

2233 # References

2234

2235The bibliography will be inserted after this header.

2236

2237Non-pandoc extensions

2238=====================

2239

2240The following markdown syntax extensions are not enabled by default

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

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

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

2244

2245**Extension: `hard_line_breaks`**\

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

2247breaks instead of spaces.

2248

2249**Extension: `tex_math_single_backslash`**\

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

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

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

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

2254

2255**Extension: `tex_math_double_backslash`**\

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

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

2258as display TeX math.

2259

2260**Extension: `markdown_attribute`**\

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

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

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

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

2265

2266**Extension: `mmd_title_block`**\

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

2268the document, for example:

2269

2270 Title: My title

2271 Author: John Doe

2272 Date: September 1, 2008

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

2274 a field spanning multiple lines.

2275

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

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

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

2279`mmd_title_block`.

2280

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

2282

2283**Extension: `abbrevations`**\

2284Parses PHP Markdown Extra abbreviation keys, like

2285

2286 *[HTML]: Hyper Text Markup Language

2287

2288Note that the pandoc document model does not support

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

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

2291

2292**Extension: `autolink_urls`**\

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

2294pointy braces `<...>`.

2295

2296Producing slide shows with Pandoc

2297=================================

2298

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

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

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

2302PDF slide show using LaTeX [beamer].

2303

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

2305

2306 % Habits

2307 % John Doe

2308 % March 22, 2005

2309

2310 # In the morning

2311

2312 ## Getting up

2313

2314 - Turn off alarm

2315 - Get out of bed

2316

2317 ## Breakfast

2318

2319 - Eat eggs

2320 - Drink coffee

2321

2322 # In the evening

2323

2324 ## Dinner

2325

2326 - Eat spaghetti

2327 - Drink wine

2328

2329 ------------------

2330

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

2332

2333 ## Going to sleep

2334

2335 - Get in bed

2336 - Count sheep

2337

2338To produce the slide show, simply type

2339

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

2341

2342for S5,

2343

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

2345

2346for Slidy,

2347

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

2349

2350for Slideous,

2351

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

2353

2354for DZSlides, or

2355

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

2357

2358for beamer.

2359

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

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

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

2363

2364Structuring the slide show

2365--------------------------

2366

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

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

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

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

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

2372the `--slide-level` option.

2373

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

2375rules:

2376

2377 * A horizontal rule always starts a new slide.

2378

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

2380

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

2382 headers *within* a slide.

2383

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

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

2386 and help to break the slide show into sections.

2387

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

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

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

2391

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

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

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

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

2396sections, as in the example above.

2397

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

2399`-s/--standalone`

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

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

2402(for Slideous), or at the Slidy

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

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

2405above.) For DZSlides,

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

2407

2408Incremental lists

2409-----------------

2410

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

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

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

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

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

2416

2417 > - Eat spaghetti

2418 > - Drink wine

2419

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

2421a single document.

2422

2423Styling the slides

2424------------------

2425

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

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

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

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

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

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

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

2433

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

2435be modified there.

2436

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

2438using the `-V` option:

2439

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

2441

2442Literate Haskell support

2443========================

2444

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

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

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

2448literate Haskell source. This means that

2449

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

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

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

2453

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

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

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

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

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

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

2460

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

2462 as Haskell code.

2463

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

2465 be rendered using bird tracks.

2466

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

2468 Haskell code.

2469

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

2471 inside `code` environments.

2472

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

2474 with class `literatehaskell` and bird tracks.

2475

2476Examples:

2477

2478 pandoc -f markdown+lhs -t html

2479

2480reads literate Haskell source formatted with markdown conventions and writes

2481ordinary HTML (without bird tracks).

2482

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

2484

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

2486and pasted as literate Haskell source.

2487

2488Authors

2489=======

2490

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

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

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

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

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

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

2498Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

2500Sergey Astanin.

2501

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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