README · typeable/pandoc

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

1366

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

1368

1369

1370### Numbered example lists ###

1371

1372**Extension: `example_lists`**

1373

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

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

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

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

1378where the last stopped. So, for example:

1379

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

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

1382

1383 Explanation of examples.

1384

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

1386

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

1388document:

1389

1390 (@good) This is a good example.

1391

1392 As (@good) illustrates, ...

1393

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

1395or hyphens.

1396

1397

1398### Compact and loose lists ###

1399

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

1401cases" involving lists. Consider this source:

1402

1403 + First

1404 + Second:

1405 - Fee

1406 - Fie

1407 - Foe

1408

1409 + Third

1410

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

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

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

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

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

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

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

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

1419behavior is consistent with the official markdown syntax description,

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

1421

1422

1423### Ending a list ###

1424

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

1426

1427 - item one

1428 - item two

1429

1430 { my code block }

1431

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

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

1434a code block.

1435

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

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

1438any format:

1439

1440 - item one

1441 - item two

1442

1443

1444

1445 { my code block }

1446

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

1448of one big list:

1449

1450 1. one

1451 2. two

1452 3. three

1453

1454

1455

1456 1. uno

1457 2. dos

1458 3. tres

1459

1460Horizontal rules

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

1462

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

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

1466 * * * *

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

1471Tables

1472------

1473

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

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

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

1477

1478### Simple tables

1479

1480**Extension: `simple_tables`, `table_captions`**

1481

1482Simple tables look like this:

1483

1484 Right Left Center Default

1485 ------- ------ ---------- -------

1486 12 12 12 12

1487 123 123 123 123

1488 1 1 1 1

1489

1490 Table: Demonstration of simple table syntax.

1491

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

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

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

1495

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

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

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

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

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

1501 the column is centered.

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

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

1504

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

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

1507

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

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

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

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

1512before or after the table.

1513

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

1515to end the table. For example:

1516

1517 ------- ------ ---------- -------

1518 12 12 12 12

1519 123 123 123 123

1520 1 1 1 1

1521 ------- ------ ---------- -------

1522

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

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

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

1526

1527### Multiline tables

1528

1529**Extension: `multiline_tables`, `table_captions`**

1530

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

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

1533not supported). Here is an example:

1534

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

1536 Centered Default Right Left

1537 Header Aligned Aligned Aligned

1538 ----------- ------- --------------- -------------------------

1539 First row 12.0 Example of a row that

1540 spans multiple lines.

1541

1542 Second row 5.0 Here's another one. Note

1543 the blank line between

1544 rows.

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

1546

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

1548 multiple lines.

1549

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

1551

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

1553 (unless the headers are omitted).

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

1555 - The rows must be separated by blank lines.

1556

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

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

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

1560output, try widening it in the markdown source.

1561

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

1563

1564 ----------- ------- --------------- -------------------------

1565 First row 12.0 Example of a row that

1566 spans multiple lines.

1567

1568 Second row 5.0 Here's another one. Note

1569 the blank line between

1570 rows.

1571 ----------- ------- --------------- -------------------------

1572

1573 : Here's a multiline table without headers.

1574

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

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

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

1578

1579### Grid tables

1580

1581**Extension: `grid_tables`, `table_captions`**

1582

1583Grid tables look like this:

1584

1585 : Sample grid table.

1586

1587 +---------------+---------------+--------------------+

1588 | Fruit | Price | Advantages |

1589 +===============+===============+====================+

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

1591 | | | - bright color |

1592 +---------------+---------------+--------------------+

1593 | Oranges | $2.10 | - cures scurvy |

1594 | | | - tasty |

1595 +---------------+---------------+--------------------+

1596

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

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

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

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

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

1602

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

1604

1605### Pipe tables

1606

1607**Extension: `pipe_tables`, `table_captions`**

1608

1609Pipe tables look like this:

1610

1612 |------:|:-----|---------|:------:|

1613 | 12 | 12 | 12 | 12 |

1614 | 123 | 123 | 123 | 123 |

1615 | 1 | 1 | 1 | 1 |

1616

1617 : Demonstration of simple table syntax.

1618

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

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

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

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

1623it defines column alignments.

1624

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

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

1627legal (though ugly) pipe table:

1628

1629 fruit| price

1630 -----|-----:

1631 apple|2.05

1632 pear|1.37

1633 orange|3.09

1634

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

1636and lists, and cannot span multiple lines.

1637

1638 [the same as in PHP markdown extra]:

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

1640

1641Note: Pandoc also recognizes pipe tables of the following

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

1643

1644 | One | Two |

1645 |-----+-------|

1646 | my | table |

1647 | is | nice |

1648

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

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

1651you'll need to add colons as above.

1652

1653Title block

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

1655

1656**Extension: `pandoc_title_block`**

1657

1658If the file begins with a title block

1659

1660 % title

1661 % author(s) (separated by semicolons)

1662 % date

1663

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

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

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

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

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

1669

1670 %

1671 % Author

1672

1673 % My title

1674 %

1675 % June 15, 2006

1676

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

1678begin with leading space, thus:

1679

1680 % My title

1681 on multiple lines

1682

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

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

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

1686

1687 % Author One

1688 Author Two

1689

1690 % Author One; Author Two

1691

1692 % Author One;

1693 Author Two

1694

1695The date must fit on one line.

1696

1697All three metadata fields may contain standard inline formatting

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

1699

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

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

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

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

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

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

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

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

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

1709be used by itself as the HTML title.

1710

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

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

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

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

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

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

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

1718text. Thus,

1719

1720 % PANDOC(1)

1721

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

1723

1724 % PANDOC(1) Pandoc User Manuals

1725

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

1727

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

1729

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

1731

1732

1733Backslash escapes

1734-----------------

1735

1736**Extension: `all_symbols_escapable`**

1737

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

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

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

1741

1742 *\*hello\**

1743

1744one will get

1745

1746 <em>*hello*</em>

1747

1748instead of

1749

1750 <strong>hello</strong>

1751

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

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

1754

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

1756

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

1758will be used.)

1759

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

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

1762`\ `.

1763

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

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

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

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

1768two trailing spaces on a line.

1769

1770Backslash escapes do not work in verbatim contexts.

1771

1772Smart punctuation

1773-----------------

1774

1775**Extension**

1776

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

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

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

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

1781

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

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

1784

1785Inline formatting

1786-----------------

1787

1788### Emphasis ###

1789

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

1791

1792 This text is _emphasized with underscores_, and this

1793 is *emphasized with asterisks*.

1794

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

1796

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

1798

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

1800will not trigger emphasis:

1801

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

1803

1804**Extension: `intraword_underscores`**

1805

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

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

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

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

1810

1811 feas*ible*, not feas*able*.

1812

1813

1814### Strikeout ###

1815

1816**Extension: `strikeout`**

1817

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

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

1820

1821 This ~~is deleted text.~~

1822

1823

1824### Superscripts and subscripts ###

1825

1826**Extension: `superscript`, `subscript`**

1827

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

1829characters; subscripts may be written by surrounding the subscripted

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

1831

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

1833

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

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

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

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

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

1839

1840

1841### Verbatim ###

1842

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

1844

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

1846

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

1848

1849 Here is a literal backtick `` ` ``.

1850

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

1852backticks will be ignored.)

1853

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

1855of consecutive backticks (optionally followed by a space)

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

1857preceded by a space).

1858

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

1860work in verbatim contexts:

1861

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

1863

1864**Extension: `inline_code_attributes`**

1865

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

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

1868

1869 `<$>`{.haskell}

1870

1871Math

1872----

1873

1874**Extension: `tex_math_dollars`**

1875

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

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

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

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

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

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

1882

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

1884depends on the output format:

1885

1886Markdown, LaTeX, Org-Mode, ConTeXt

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

1888

1889reStructuredText

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

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

1892

1893AsciiDoc

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

1895

1896Texinfo

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

1898

1899groff man

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

1901

1902MediaWiki

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

1904

1905Textile

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

1907

1908RTF, OpenDocument, ODT

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

1910 and will otherwise appear verbatim.

1911

1912Docbook

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

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

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

1916

1917Docx

1918 ~ It will be rendered using OMML math markup.

1919

1920FictionBook2

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

1922 using Google Charts or other compatible web service, downloaded

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

1924

1925HTML, Slidy, DZSlides, S5, EPUB

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

1927 command-line options selected:

1928

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

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

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

1932 styled differently from the surrounding text if needed.

1933

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

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

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

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

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

1939 verbatim between `$` characters.)

1940

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

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

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

1944 it.

1945

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

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

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

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

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

1951

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

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

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

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

1956 procedure is:

1957

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

1959 gladtex -d myfile-images myfile.htex

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

1961

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

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

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

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

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

1967

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

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

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

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

1972

1973Raw HTML

1974--------

1975

1976**Extension: `raw_html`**

1977

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

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

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

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

1982be disabled if desired.)

1983

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

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

1986formats.

1987

1988**Extension: `markdown_in_html_blocks`**

1989

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

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

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

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

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

1995

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

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

1998Thus, for example, Pandoc will turn

1999

2000 <table>

2001 <tr>

2002 <td>*one*</td>

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

2004 </tr>

2005 </table>

2006

2007into

2008

2009 <table>

2010 <tr>

2011 <td><em>one</em></td>

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

2013 </tr>

2014 </table>

2015

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

2017

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

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

2020

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

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

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

2024from being interpreted as markdown.

2025

2026Raw TeX

2027-------

2028

2029**Extension: `raw_tex`**

2030

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

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

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

2034LaTeX to include BibTeX citations:

2035

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

2037

2038Note that in LaTeX environments, like

2039

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

2041 Age & Frequency \\ \hline

2042 18--25 & 15 \\

2043 26--35 & 33 \\

2044 36--45 & 22 \\ \hline

2045 \end{tabular}

2046

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

2048LaTeX, not as markdown.

2049

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

2051and ConTeXt.

2052

2053LaTeX macros

2054------------

2055

2056**Extension: `latex_macros`**

2057

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

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

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

2061not just LaTeX:

2062

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

2064

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

2066

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

2068unchanged to the output.

2069

2070

2071Links

2072-----

2073

2074Markdown allows links to be specified in several ways.

2075

2076### Automatic links ###

2077

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

2079will become a link:

2080

2081 <http://google.com>

2082 <sam@green.eggs.ham>

2083

2084### Inline links ###

2085

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

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

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

2089

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

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

2092

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

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

2095

2096

2097### Reference links ###

2098

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

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

2101before or after the link).

2102

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

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

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

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

2107parentheses.

2108

2109Here are some examples:

2110

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

2112 [my label 2]: /foo

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

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

2115

2116The URL may optionally be surrounded by angle brackets:

2117

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

2119

2120The title may go on the next line:

2121

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

2123 "The free software foundation"

2124

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

2126

2127 Here is [my link][FOO]

2128

2129 [Foo]: /bar/baz

2130

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

2132empty, or omitted entirely:

2133

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

2135

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

2137

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

2139reference link definitions cannot occur in nested constructions

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

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

2142not in most other implementations:

2143

2144 > My block [quote].

2145 >

2146 > [quote]: /foo

2147

2148### Internal links

2149

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

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

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

2153For example:

2154

2155 See the [Introduction](#introduction).

2156

2157or

2158

2159 See the [Introduction].

2160

2161 [Introduction]: #introduction

2162

2163Internal links are currently supported for HTML formats (including

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

2165

2166Images

2167------

2168

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

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

2171

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

2173

2174 ![movie reel]

2175

2176 [movie reel]: movie.gif

2177

2178### Pictures with captions ###

2179

2180**Extension: `implicit_figures`**

2181

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

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

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

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

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

2187

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

2189

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

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

2192 itself, with no caption.

2193

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

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

2196nonbreaking space after the image:

2197

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

2199

2200

2201Footnotes

2202---------

2203

2204**Extension: `footnotes`**

2205

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

2207

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

2209

2210 [^1]: Here is the footnote.

2211

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

2213

2214 Subsequent paragraphs are indented to show that they

2215 belong to the previous footnote.

2216

2217 { some.code }

2218

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

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

2221 multi-paragraph list items.

2222

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

2224 isn't indented.

2225

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

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

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

2229will be numbered sequentially.

2230

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

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

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

2234

2235**Extension: `inline_notes`**

2236

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

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

2239

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

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

2242 note.]

2243

2244Inline and regular footnotes may be mixed freely.

2245

2246

2247Citations

2248---------

2249

2250**Extension: `citations`**

2251

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

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

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

2255

2256 Format File extension

2257 ------------ --------------

2258 MODS .mods

2259 BibLaTeX .bib

2260 BibTeX .bibtex

2261 RIS .ris

2262 EndNote .enl

2263 EndNote XML .xml

2264 ISI .wos

2265 MEDLINE .medline

2266 Copac .copac

2267 JSON citeproc .json

2268

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

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

2271

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

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

2274bibliographies).

2275

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

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

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

2279creating and modifying CSL styles can be found at

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

2281A repository of CSL styles can be found at

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

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

2284

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

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

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

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

2289

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

2291

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

2293

2294 Blah blah [@smith04; @doe99].

2295

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

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

2298author is already mentioned in the text:

2299

2300 Smith says blah [-@smith04].

2301

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

2303

2304 @smith04 says blah.

2305

2306 @smith04 [p. 33] says blah.

2307

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

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

2310document with an appropriate header:

2311

2312 last paragraph...

2313

2314 # References

2315

2316The bibliography will be inserted after this header.

2317

2318Non-pandoc extensions

2319=====================

2320

2321The following markdown syntax extensions are not enabled by default

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

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

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

2325

2326**Extension: `hard_line_breaks`**\

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

2328breaks instead of spaces.

2329

2330**Extension: `tex_math_single_backslash`**\

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

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

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

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

2335

2336**Extension: `tex_math_double_backslash`**\

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

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

2339as display TeX math.

2340

2341**Extension: `markdown_attribute`**\

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

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

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

2345

2346**Extension: `mmd_title_block`**\

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

2348the document, for example:

2349

2350 Title: My title

2351 Author: John Doe

2352 Date: September 1, 2008

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

2354 a field spanning multiple lines.

2355

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

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

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

2359`mmd_title_block`.

2360

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

2362

2363**Extension: `abbrevations`**\

2364Parses PHP Markdown Extra abbreviation keys, like

2365

2366 *[HTML]: Hyper Text Markup Language

2367

2368Note that the pandoc document model does not support

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

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

2371

2372**Extension: `autolink_bare_uris`**\

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

2374pointy braces `<...>`.

2375

2376**Extension: `link_attributes`**\

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

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

2379these, so they are presently just ignored.

2380

2381**Extension: `mmd_header_identifiers`**\

2382Parses multimarkdown style header identifiers (in square brackets,

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

2384

2385Producing slide shows with Pandoc

2386=================================

2387

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

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

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

2391PDF slide show using LaTeX [beamer].

2392

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

2394

2395 % Habits

2396 % John Doe

2397 % March 22, 2005

2398

2399 # In the morning

2400

2401 ## Getting up

2402

2403 - Turn off alarm

2404 - Get out of bed

2405

2406 ## Breakfast

2407

2408 - Eat eggs

2409 - Drink coffee

2410

2411 # In the evening

2412

2413 ## Dinner

2414

2415 - Eat spaghetti

2416 - Drink wine

2417

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

2419

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

2421

2422 ## Going to sleep

2423

2424 - Get in bed

2425 - Count sheep

2426

2427To produce the slide show, simply type

2428

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

2430

2431for S5,

2432

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

2434

2435for Slidy,

2436

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

2438

2439for Slideous,

2440

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

2442

2443for DZSlides, or

2444

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

2446

2447for beamer.

2448

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

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

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

2452

2453Structuring the slide show

2454--------------------------

2455

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

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

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

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

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

2461the `--slide-level` option.

2462

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

2464rules:

2465

2466 * A horizontal rule always starts a new slide.

2467

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

2469

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

2471 headers *within* a slide.

2472

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

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

2475 and help to break the slide show into sections.

2476

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

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

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

2480

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

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

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

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

2485sections, as in the example above.

2486

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

2488`-s/--standalone`

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

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

2491(for Slideous), or at the Slidy

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

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

2494above.) For DZSlides,

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

2496

2497Incremental lists

2498-----------------

2499

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

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

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

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

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

2505

2506 > - Eat spaghetti

2507 > - Drink wine

2508

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

2510a single document.

2511

2512Styling the slides

2513------------------

2514

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

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

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

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

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

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

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

2522

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

2524be modified there.

2525

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

2527using the `-V` option:

2528

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

2530

2531Literate Haskell support

2532========================

2533

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

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

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

2537literate Haskell source. This means that

2538

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

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

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

2542

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

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

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

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

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

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

2549

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

2551 as Haskell code.

2552

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

2554 be rendered using bird tracks.

2555

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

2557 Haskell code.

2558

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

2560 inside `code` environments.

2561

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

2563 with class `literatehaskell` and bird tracks.

2564

2565Examples:

2566

2567 pandoc -f markdown+lhs -t html

2568

2569reads literate Haskell source formatted with markdown conventions and writes

2570ordinary HTML (without bird tracks).

2571

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

2573

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

2575and pasted as literate Haskell source.

2576

2577Authors

2578=======

2579

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

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

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

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

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

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

2587Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

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

2590

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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