README · typeable/pandoc

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

1253

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

1255

1256

1257### Numbered example lists ###

1258

1259**Extension: `example_lists`**

1260

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

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

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

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

1265where the last stopped. So, for example:

1266

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

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

1269

1270 Explanation of examples.

1271

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

1273

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

1275document:

1276

1277 (@good) This is a good example.

1278

1279 As (@good) illustrates, ...

1280

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

1282or hyphens.

1283

1284

1285### Compact and loose lists ###

1286

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

1288cases" involving lists. Consider this source:

1289

1290 + First

1291 + Second:

1292 - Fee

1293 - Fie

1294 - Foe

1295

1296 + Third

1297

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

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

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

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

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

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

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

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

1306behavior is consistent with the official markdown syntax description,

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

1308

1309

1310### Ending a list ###

1311

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

1313

1314 - item one

1315 - item two

1316

1317 { my code block }

1318

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

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

1321a code block.

1322

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

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

1325any format:

1326

1327 - item one

1328 - item two

1329

1330

1331

1332 { my code block }

1333

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

1335of one big list:

1336

1337 1. one

1338 2. two

1339 3. three

1340

1341

1342

1343 1. uno

1344 2. dos

1345 3. tres

1346

1347Horizontal rules

1348----------------

1349

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

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

1353 * * * *

1355 ---------------

1358Tables

1359------

1360

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

1362`pipe_tables`, `table_captions`**

1363

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

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

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

1367

1368### Simple tables

1369

1370Simple tables look like this:

1371

1372 Right Left Center Default

1373 ------- ------ ---------- -------

1374 12 12 12 12

1375 123 123 123 123

1376 1 1 1 1

1377

1378 Table: Demonstration of simple table syntax.

1379

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

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

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

1383

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

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

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

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

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

1389 the column is centered.

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

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

1392

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

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

1395

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

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

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

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

1400before or after the table.

1401

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

1403to end the table. For example:

1404

1405 ------- ------ ---------- -------

1406 12 12 12 12

1407 123 123 123 123

1408 1 1 1 1

1409 ------- ------ ---------- -------

1410

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

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

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

1414

1415### Multiline tables

1416

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

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

1419not supported). Here is an example:

1420

1421 -------------------------------------------------------------

1422 Centered Default Right Left

1423 Header Aligned Aligned Aligned

1424 ----------- ------- --------------- -------------------------

1425 First row 12.0 Example of a row that

1426 spans multiple lines.

1427

1428 Second row 5.0 Here's another one. Note

1429 the blank line between

1430 rows.

1431 -------------------------------------------------------------

1432

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

1434 multiple lines.

1435

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

1437

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

1439 (unless the headers are omitted).

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

1441 - The rows must be separated by blank lines.

1442

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

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

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

1446output, try widening it in the markdown source.

1447

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

1449

1450 ----------- ------- --------------- -------------------------

1451 First row 12.0 Example of a row that

1452 spans multiple lines.

1453

1454 Second row 5.0 Here's another one. Note

1455 the blank line between

1456 rows.

1457 -------------------------------------------------------------

1458

1459 : Here's a multiline table without headers.

1460

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

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

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

1464

1465### Grid tables

1466

1467Grid tables look like this:

1468

1469 : Sample grid table.

1470

1471 +---------------+---------------+--------------------+

1472 | Fruit | Price | Advantages |

1473 +===============+===============+====================+

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

1475 | | | - bright color |

1476 +---------------+---------------+--------------------+

1477 | Oranges | $2.10 | - cures scurvy |

1478 | | | - tasty |

1479 +---------------+---------------+--------------------+

1480

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

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

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

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

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

1486

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

1488

1489### Pipe tables

1490

1491Pipe tables look like this:

1492

1494 |------:|:-----|---------|:------:|

1495 | 12 | 12 | 12 | 12 |

1496 | 123 | 123 | 123 | 123 |

1497 | 1 | 1 | 1 | 1 |

1498

1499 : Demonstration of simple table syntax.

1500

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

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

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

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

1505it defines column alignments.

1506

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

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

1509legal (though ugly) pipe table:

1510

1511 fruit| price

1512 -----|-----:

1513 apple|2.05

1514 pear|1.37

1515 orange|3.09

1516

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

1518and lists, and cannot span multiple lines.

1519

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

1521

1522Note: Pandoc also recognizes pipe tables of the following

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

1524

1525 | One | Two |

1526 |-----+-------|

1527 | my | table |

1528 | is | nice |

1529

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

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

1532you'll need to add colons as above.

1533

1534Title block

1535-----------

1536

1537**Extension: `pandoc_title_block`**

1538

1539If the file begins with a title block

1540

1541 % title

1542 % author(s) (separated by semicolons)

1543 % date

1544

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

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

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

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

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

1550

1551 %

1552 % Author

1553

1554 % My title

1555 %

1556 % June 15, 2006

1557

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

1559begin with leading space, thus:

1560

1561 % My title

1562 on multiple lines

1563

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

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

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

1567

1568 % Author One

1569 Author Two

1570

1571 % Author One; Author Two

1572

1573 % Author One;

1574 Author Two

1575

1576The date must fit on one line.

1577

1578All three metadata fields may contain standard inline formatting

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

1580

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

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

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

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

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

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

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

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

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

1590be used by itself as the HTML title.

1591

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

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

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

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

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

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

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

1599text. Thus,

1600

1601 % PANDOC(1)

1602

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

1604

1605 % PANDOC(1) Pandoc User Manuals

1606

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

1608

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

1610

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

1612

1613

1614Backslash escapes

1615-----------------

1616

1617**Extension: `all_symbols_escapable`**

1618

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

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

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

1622

1623 *\*hello\**

1624

1625one will get

1626

1627 <em>*hello*</em>

1628

1629instead of

1630

1631 <strong>hello</strong>

1632

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

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

1635

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

1637

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

1639will be used.)

1640

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

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

1643`\ `.

1644

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

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

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

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

1649two trailing spaces on a line.

1650

1651Backslash escapes do not work in verbatim contexts.

1652

1653Smart punctuation

1654-----------------

1655

1656**Extension**

1657

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

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

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

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

1662

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

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

1665

1666Inline formatting

1667-----------------

1668

1669### Emphasis ###

1670

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

1672

1673 This text is _emphasized with underscores_, and this

1674 is *emphasized with asterisks*.

1675

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

1677

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

1679

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

1681will not trigger emphasis:

1682

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

1684

1685**Extension: `intraword_underscores`**

1686

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

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

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

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

1691

1692 feas*ible*, not feas*able*.

1693

1694

1695### Strikeout ###

1696

1697**Extension: `strikeout`**

1698

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

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

1701

1702 This ~~is deleted text.~~

1703

1704

1705### Superscripts and subscripts ###

1706

1707**Extension: `superscript`, `subscript`**

1708

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

1710characters; subscripts may be written by surrounding the subscripted

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

1712

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

1714

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

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

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

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

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

1720

1721

1722### Verbatim ###

1723

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

1725

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

1727

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

1729

1730 Here is a literal backtick `` ` ``.

1731

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

1733backticks will be ignored.)

1734

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

1736of consecutive backticks (optionally followed by a space)

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

1738preceded by a space).

1739

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

1741work in verbatim contexts:

1742

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

1744

1745**Extension: `inline_code_attributes`**

1746

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

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

1749

1750 `<$>`{.haskell}

1751

1752Math

1753----

1754

1755**Extension: `tex_math_dollars`**

1756

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

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

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

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

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

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

1763

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

1765depends on the output format:

1766

1767Markdown, LaTeX, Org-Mode, ConTeXt

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

1769

1770reStructuredText

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

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

1773

1774AsciiDoc

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

1776

1777Texinfo

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

1779

1780groff man

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

1782

1783MediaWiki

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

1785

1786Textile

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

1788

1789RTF, OpenDocument, ODT

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

1791 and will otherwise appear verbatim.

1792

1793Docbook

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

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

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

1797

1798Docx

1799 ~ It will be rendered using OMML math markup.

1800

1801FictionBook2

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

1803 using Google Charts or other compatible web service, downloaded

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

1805

1806HTML, Slidy, DZSlides, S5, EPUB

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

1808 command-line options selected:

1809

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

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

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

1813 styled differently from the surrounding text if needed.

1814

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

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

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

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

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

1820 verbatim between `$` characters.)

1821

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

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

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

1825 it.

1826

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

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

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

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

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

1832

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

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

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

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

1837 procedure is:

1838

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

1840 gladtex -d myfile-images myfile.htex

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

1842

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

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

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

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

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

1848

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

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

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

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

1853

1854Raw HTML

1855--------

1856

1857**Extenion: `raw_html`**

1858

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

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

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

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

1863be disabled if desired.)

1864

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

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

1867formats.

1868

1869**Extension: `markdown_in_html_blocks`**

1870

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

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

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

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

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

1876

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

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

1879Thus, for example, Pandoc will turn

1880

1881 <table>

1882 <tr>

1883 <td>*one*</td>

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

1885 </tr>

1886 </table>

1887

1888into

1889

1890 <table>

1891 <tr>

1892 <td><em>one</em></td>

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

1894 </tr>

1895 </table>

1896

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

1898

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

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

1901

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

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

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

1905from being interpreted as markdown.

1906

1907Raw TeX

1908-------

1909

1910**Extension: `raw_tex`**

1911

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

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

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

1915LaTeX to include BibTeX citations:

1916

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

1918

1919Note that in LaTeX environments, like

1920

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

1922 Age & Frequency \\ \hline

1923 18--25 & 15 \\

1924 26--35 & 33 \\

1925 36--45 & 22 \\ \hline

1926 \end{tabular}

1927

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

1929LaTeX, not as markdown.

1930

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

1932and ConTeXt.

1933

1934LaTeX macros

1935------------

1936

1937**Extension: `latex_macros`**

1938

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

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

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

1942not just LaTeX:

1943

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

1945

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

1947

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

1949unchanged to the output.

1950

1951

1952Links

1953-----

1954

1955Markdown allows links to be specified in several ways.

1956

1957### Automatic links ###

1958

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

1960will become a link:

1961

1962 <http://google.com>

1963 <sam@green.eggs.ham>

1964

1965**Extension: `autolink_code_spans`**

1966

1967Pandoc will render autolinked URLs and email addresses as

1968inline code.

1969

1970### Inline links ###

1971

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

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

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

1975

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

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

1978

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

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

1981

1982

1983### Reference links ###

1984

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

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

1987before or after the link).

1988

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

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

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

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

1993parentheses.

1994

1995Here are some examples:

1996

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

1998 [my label 2]: /foo

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

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

2001

2002The URL may optionally be surrounded by angle brackets:

2003

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

2005

2006The title may go on the next line:

2007

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

2009 "The free software foundation"

2010

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

2012

2013 Here is [my link][FOO]

2014

2015 [Foo]: /bar/baz

2016

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

2018empty, or omitted entirely:

2019

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

2021

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

2023

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

2025reference link definitions cannot occur in nested constructions

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

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

2028not in most other implementations:

2029

2030 > My block [quote].

2031 >

2032 > [quote]: /foo

2033

2034### Internal links

2035

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

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

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

2039For example:

2040

2041 See the [Introduction](#introduction).

2042

2043or

2044

2045 See the [Introduction].

2046

2047 [Introduction]: #introduction

2048

2049Internal links are currently supported for HTML formats (including

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

2051

2052Images

2053------

2054

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

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

2057

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

2059

2060 ![movie reel]

2061

2062 [movie reel]: movie.gif

2063

2064### Pictures with captions ###

2065

2066**Extension**

2067

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

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

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

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

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

2073

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

2075

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

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

2078 itself, with no caption.

2079

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

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

2082nonbreaking space after the image:

2083

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

2085

2086

2087Footnotes

2088---------

2089

2090**Extension: `footnotes`**

2091

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

2093

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

2095

2096 [^1]: Here is the footnote.

2097

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

2099

2100 Subsequent paragraphs are indented to show that they

2101 belong to the previous footnote.

2102

2103 { some.code }

2104

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

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

2107 multi-paragraph list items.

2108

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

2110 isn't indented.

2111

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

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

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

2115will be numbered sequentially.

2116

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

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

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

2120

2121**Extension: `inline_notes`**

2122

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

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

2125

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

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

2128 note.]

2129

2130Inline and regular footnotes may be mixed freely.

2131

2132

2133Citations

2134---------

2135

2136**Extension: `citations`**

2137

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

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

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

2141

2142 Format File extension

2143 ------------ --------------

2144 MODS .mods

2145 BibTeX/BibLaTeX .bib

2146 RIS .ris

2147 EndNote .enl

2148 EndNote XML .xml

2149 ISI .wos

2150 MEDLINE .medline

2151 Copac .copac

2152 JSON citeproc .json

2153

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

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

2156bibliographies).

2157

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

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

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

2161creating and modifying CSL styles can be found at

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

2163A repository of CSL styles can be found at

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

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

2166

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

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

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

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

2171

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

2173

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

2175

2176 Blah blah [@smith04; @doe99].

2177

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

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

2180author is already mentioned in the text:

2181

2182 Smith says blah [-@smith04].

2183

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

2185

2186 @smith04 says blah.

2187

2188 @smith04 [p. 33] says blah.

2189

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

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

2192document with an appropriate header:

2193

2194 last paragraph...

2195

2196 # References

2197

2198The bibliography will be inserted after this header.

2199

2200Non-pandoc extensions

2201=====================

2202

2203The following markdown syntax extensions are not enabled by default

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

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

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

2207

2208**Extension: `hard_line_breaks`**\

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

2210breaks instead of spaces.

2211

2212**Extension: `tex_math_single_backslash`**\

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

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

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

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

2217

2218**Extension: `tex_math_double_backslash`**\

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

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

2221as display TeX math.

2222

2223**Extension: `markdown_attribute`**\

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

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

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

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

2228

2229**Extension: `mmd_title_block`**\

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

2231the document, for example:

2232

2233 Title: My title

2234 Author: John Doe

2235 Date: September 1, 2008

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

2237 a field spanning multiple lines.

2238

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

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

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

2242`mmd_title_block`.

2243

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

2245

2246**Extension: `abbrevations`**\

2247Parses PHP Markdown Extra abbreviation keys, like

2248

2249 *[HTML]: Hyper Text Markup Language

2250

2251Note that the pandoc document model does not support

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

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

2254

2255Producing slide shows with Pandoc

2256=================================

2257

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

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

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

2261PDF slide show using LaTeX [beamer].

2262

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

2264

2265 % Habits

2266 % John Doe

2267 % March 22, 2005

2268

2269 # In the morning

2270

2271 ## Getting up

2272

2273 - Turn off alarm

2274 - Get out of bed

2275

2276 ## Breakfast

2277

2278 - Eat eggs

2279 - Drink coffee

2280

2281 # In the evening

2282

2283 ## Dinner

2284

2285 - Eat spaghetti

2286 - Drink wine

2287

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

2289

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

2291

2292 ## Going to sleep

2293

2294 - Get in bed

2295 - Count sheep

2296

2297To produce the slide show, simply type

2298

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

2300

2301for S5,

2302

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

2304

2305for Slidy,

2306

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

2308

2309for Slideous,

2310

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

2312

2313for DZSlides, or

2314

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

2316

2317for beamer.

2318

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

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

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

2322

2323Structuring the slide show

2324--------------------------

2325

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

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

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

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

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

2331the `--slide-level` option.

2332

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

2334rules:

2335

2336 * A horizontal rule always starts a new slide.

2337

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

2339

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

2341 headers *within* a slide.

2342

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

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

2345 and help to break the slide show into sections.

2346

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

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

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

2350

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

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

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

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

2355sections, as in the example above.

2356

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

2358`-s/--standalone`

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

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

2361(for Slideous), or at the Slidy

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

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

2364above.) For DZSlides,

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

2366

2367Incremental lists

2368-----------------

2369

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

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

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

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

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

2375

2376 > - Eat spaghetti

2377 > - Drink wine

2378

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

2380a single document.

2381

2382Styling the slides

2383------------------

2384

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

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

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

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

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

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

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

2392

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

2394be modified there.

2395

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

2397using the `-V` option:

2398

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

2400

2401Literate Haskell support

2402========================

2403

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

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

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

2407literate Haskell source. This means that

2408

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

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

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

2412

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

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

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

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

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

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

2419

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

2421 as Haskell code.

2422

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

2424 be rendered using bird tracks.

2425

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

2427 Haskell code.

2428

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

2430 inside `code` environments.

2431

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

2433 with class `literatehaskell` and bird tracks.

2434

2435Examples:

2436

2437 pandoc -f markdown+lhs -t html

2438

2439reads literate Haskell source formatted with markdown conventions and writes

2440ordinary HTML (without bird tracks).

2441

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

2443

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

2445and pasted as literate Haskell source.

2446

2447Authors

2448=======

2449

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

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

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

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

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

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

2457Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

2459Sergey Astanin.

2460

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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