README · typeable/pandoc

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

1411

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

1413

1414

1415### Numbered example lists ###

1416

1417**Extension: `example_lists`**

1418

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

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

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

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

1423where the last stopped. So, for example:

1424

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

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

1427

1428 Explanation of examples.

1429

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

1431

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

1433document:

1434

1435 (@good) This is a good example.

1436

1437 As (@good) illustrates, ...

1438

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

1440or hyphens.

1441

1442

1443### Compact and loose lists ###

1444

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

1446cases" involving lists. Consider this source:

1447

1448 + First

1449 + Second:

1450 - Fee

1451 - Fie

1452 - Foe

1453

1454 + Third

1455

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

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

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

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

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

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

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

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

1464behavior is consistent with the official markdown syntax description,

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

1466

1467

1468### Ending a list ###

1469

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

1471

1472 - item one

1473 - item two

1474

1475 { my code block }

1476

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

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

1479a code block.

1480

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

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

1483any format:

1484

1485 - item one

1486 - item two

1487

1488

1489

1490 { my code block }

1491

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

1493of one big list:

1494

1495 1. one

1496 2. two

1497 3. three

1498

1499

1500

1501 1. uno

1502 2. dos

1503 3. tres

1504

1505Horizontal rules

1506----------------

1507

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

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

1511 * * * *

1513 ---------------

1516Tables

1517------

1518

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

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

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

1522

1523### Simple tables

1524

1525**Extension: `simple_tables`, `table_captions`**

1526

1527Simple tables look like this:

1528

1529 Right Left Center Default

1530 ------- ------ ---------- -------

1531 12 12 12 12

1532 123 123 123 123

1533 1 1 1 1

1534

1535 Table: Demonstration of simple table syntax.

1536

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

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

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

1540

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

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

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

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

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

1546 the column is centered.

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

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

1549

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

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

1552

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

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

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

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

1557before or after the table.

1558

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

1560to end the table. For example:

1561

1562 ------- ------ ---------- -------

1563 12 12 12 12

1564 123 123 123 123

1565 1 1 1 1

1566 ------- ------ ---------- -------

1567

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

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

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

1571

1572### Multiline tables

1573

1574**Extension: `multiline_tables`, `table_captions`**

1575

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

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

1578not supported). Here is an example:

1579

1580 -------------------------------------------------------------

1581 Centered Default Right Left

1582 Header Aligned Aligned Aligned

1583 ----------- ------- --------------- -------------------------

1584 First row 12.0 Example of a row that

1585 spans multiple lines.

1586

1587 Second row 5.0 Here's another one. Note

1588 the blank line between

1589 rows.

1590 -------------------------------------------------------------

1591

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

1593 multiple lines.

1594

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

1596

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

1598 (unless the headers are omitted).

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

1600 - The rows must be separated by blank lines.

1601

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

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

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

1605output, try widening it in the markdown source.

1606

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

1608

1609 ----------- ------- --------------- -------------------------

1610 First row 12.0 Example of a row that

1611 spans multiple lines.

1612

1613 Second row 5.0 Here's another one. Note

1614 the blank line between

1615 rows.

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

1617

1618 : Here's a multiline table without headers.

1619

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

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

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

1623

1624### Grid tables

1625

1626**Extension: `grid_tables`, `table_captions`**

1627

1628Grid tables look like this:

1629

1630 : Sample grid table.

1631

1632 +---------------+---------------+--------------------+

1633 | Fruit | Price | Advantages |

1634 +===============+===============+====================+

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

1636 | | | - bright color |

1637 +---------------+---------------+--------------------+

1638 | Oranges | $2.10 | - cures scurvy |

1639 | | | - tasty |

1640 +---------------+---------------+--------------------+

1641

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

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

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

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

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

1647

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

1649

1650### Pipe tables

1651

1652**Extension: `pipe_tables`, `table_captions`**

1653

1654Pipe tables look like this:

1655

1657 |------:|:-----|---------|:------:|

1658 | 12 | 12 | 12 | 12 |

1659 | 123 | 123 | 123 | 123 |

1660 | 1 | 1 | 1 | 1 |

1661

1662 : Demonstration of simple table syntax.

1663

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

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

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

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

1668it defines column alignments.

1669

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

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

1672legal (though ugly) pipe table:

1673

1674 fruit| price

1675 -----|-----:

1676 apple|2.05

1677 pear|1.37

1678 orange|3.09

1679

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

1681and lists, and cannot span multiple lines.

1682

1683 [the same as in PHP markdown extra]:

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

1685

1686Note: Pandoc also recognizes pipe tables of the following

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

1688

1689 | One | Two |

1690 |-----+-------|

1691 | my | table |

1692 | is | nice |

1693

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

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

1696you'll need to add colons as above.

1697

1698Title block

1699-----------

1700

1701**Extension: `pandoc_title_block`**

1702

1703If the file begins with a title block

1704

1705 % title

1706 % author(s) (separated by semicolons)

1707 % date

1708

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

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

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

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

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

1714

1715 %

1716 % Author

1717

1718 % My title

1719 %

1720 % June 15, 2006

1721

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

1723begin with leading space, thus:

1724

1725 % My title

1726 on multiple lines

1727

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

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

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

1731

1732 % Author One

1733 Author Two

1734

1735 % Author One; Author Two

1736

1737 % Author One;

1738 Author Two

1739

1740The date must fit on one line.

1741

1742All three metadata fields may contain standard inline formatting

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

1744

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

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

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

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

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

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

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

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

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

1754be used by itself as the HTML title.

1755

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

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

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

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

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

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

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

1763text. Thus,

1764

1765 % PANDOC(1)

1766

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

1768

1769 % PANDOC(1) Pandoc User Manuals

1770

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

1772

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

1774

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

1776

1777YAML metadata block

1778-------------------

1779

1780**Extension: `yaml_metadata_block`**

1781

1782If the file begins with a YAML object, delimited by a line of three

1783hyphens (`---`) at the top and a line of three hyphens (`---`) or three

1784dots (`...`) at the bottom, metadata will be taken from the fields

1785of the YAML object. Metadata can contain lists and objects (nested

1786arbitrarily), but all string scalars will be interpreted as markdown.

1787

1788Fields with names ending in an underscore will be ignored by

1789pandoc. (They may be given a role by external processors.)

1790

1791Note that YAML escaping rules must be followed. Thus, for example,

1792if a title contains a colon, it must be quoted. The pipe character

1793(`|`) can be used to begin an indented block that will be interpreted

1794literally, without need for escaping. This form is necessary

1795when the field contains blank lines:

1796

1797 ---

1798 title: 'This is the title: it contains a colon'

1799 author:

1800 - name: Author One

1801 affiliation: University of Somewhere

1802 - name: Author Two

1803 affiliation: University of Nowhere

1804 tags: [nothing, nothingness]

1805 abstract: |

1806 This is the abstract.

1807

1808 It consists of two paragraphs.

1809 ...

1810

1811Template variables will be set from the metadata. Thus, for example,

1812in writing HTML, the variable `abstract` will be set to the HTML

1813equivalent of the markdown in the `abstract` field:

1814

1815 <p>This is the abstract.</p>

1816 <p>It consists of two paragraphs.</p>

1817

1818

1819Backslash escapes

1820-----------------

1821

1822**Extension: `all_symbols_escapable`**

1823

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

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

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

1827

1828 *\*hello\**

1829

1830one will get

1831

1832 <em>*hello*</em>

1833

1834instead of

1835

1836 <strong>hello</strong>

1837

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

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

1840

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

1842

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

1844will be used.)

1845

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

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

1848`\ `.

1849

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

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

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

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

1854two trailing spaces on a line.

1855

1856Backslash escapes do not work in verbatim contexts.

1857

1858Smart punctuation

1859-----------------

1860

1861**Extension**

1862

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

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

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

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

1867

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

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

1870

1871Inline formatting

1872-----------------

1873

1874### Emphasis ###

1875

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

1877

1878 This text is _emphasized with underscores_, and this

1879 is *emphasized with asterisks*.

1880

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

1882

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

1884

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

1886will not trigger emphasis:

1887

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

1889

1890**Extension: `intraword_underscores`**

1891

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

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

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

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

1896

1897 feas*ible*, not feas*able*.

1898

1899

1900### Strikeout ###

1901

1902**Extension: `strikeout`**

1903

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

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

1906

1907 This ~~is deleted text.~~

1908

1909

1910### Superscripts and subscripts ###

1911

1912**Extension: `superscript`, `subscript`**

1913

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

1915characters; subscripts may be written by surrounding the subscripted

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

1917

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

1919

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

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

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

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

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

1925

1926

1927### Verbatim ###

1928

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

1930

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

1932

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

1934

1935 Here is a literal backtick `` ` ``.

1936

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

1938backticks will be ignored.)

1939

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

1941of consecutive backticks (optionally followed by a space)

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

1943preceded by a space).

1944

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

1946work in verbatim contexts:

1947

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

1949

1950**Extension: `inline_code_attributes`**

1951

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

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

1954

1955 `<$>`{.haskell}

1956

1957Math

1958----

1959

1960**Extension: `tex_math_dollars`**

1961

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

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

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

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

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

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

1968

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

1970depends on the output format:

1971

1972Markdown, LaTeX, Org-Mode, ConTeXt

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

1974

1975reStructuredText

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

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

1978

1979AsciiDoc

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

1981

1982Texinfo

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

1984

1985groff man

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

1987

1988MediaWiki

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

1990

1991Textile

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

1993

1994RTF, OpenDocument, ODT

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

1996 and will otherwise appear verbatim.

1997

1998Docbook

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

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

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

2002

2003Docx

2004 ~ It will be rendered using OMML math markup.

2005

2006FictionBook2

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

2008 using Google Charts or other compatible web service, downloaded

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

2010

2011HTML, Slidy, DZSlides, S5, EPUB

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

2013 command-line options selected:

2014

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

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

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

2018 styled differently from the surrounding text if needed.

2019

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

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

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

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

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

2025 verbatim between `$` characters.)

2026

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

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

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

2030 it.

2031

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

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

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

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

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

2037

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

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

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

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

2042 procedure is:

2043

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

2045 gladtex -d myfile-images myfile.htex

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

2047

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

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

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

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

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

2053

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

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

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

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

2058

2059Raw HTML

2060--------

2061

2062**Extension: `raw_html`**

2063

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

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

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

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

2068be disabled if desired.)

2069

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

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

2072formats.

2073

2074**Extension: `markdown_in_html_blocks`**

2075

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

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

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

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

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

2081

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

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

2084Thus, for example, Pandoc will turn

2085

2086 <table>

2087 <tr>

2088 <td>*one*</td>

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

2090 </tr>

2091 </table>

2092

2093into

2094

2095 <table>

2096 <tr>

2097 <td><em>one</em></td>

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

2099 </tr>

2100 </table>

2101

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

2103

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

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

2106

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

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

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

2110from being interpreted as markdown.

2111

2112Raw TeX

2113-------

2114

2115**Extension: `raw_tex`**

2116

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

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

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

2120LaTeX to include BibTeX citations:

2121

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

2123

2124Note that in LaTeX environments, like

2125

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

2127 Age & Frequency \\ \hline

2128 18--25 & 15 \\

2129 26--35 & 33 \\

2130 36--45 & 22 \\ \hline

2131 \end{tabular}

2132

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

2134LaTeX, not as markdown.

2135

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

2137and ConTeXt.

2138

2139LaTeX macros

2140------------

2141

2142**Extension: `latex_macros`**

2143

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

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

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

2147not just LaTeX:

2148

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

2150

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

2152

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

2154unchanged to the output.

2155

2156

2157Links

2158-----

2159

2160Markdown allows links to be specified in several ways.

2161

2162### Automatic links ###

2163

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

2165will become a link:

2166

2167 <http://google.com>

2168 <sam@green.eggs.ham>

2169

2170### Inline links ###

2171

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

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

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

2175

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

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

2178

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

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

2181

2182

2183### Reference links ###

2184

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

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

2187before or after the link).

2188

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

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

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

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

2193parentheses.

2194

2195Here are some examples:

2196

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

2198 [my label 2]: /foo

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

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

2201

2202The URL may optionally be surrounded by angle brackets:

2203

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

2205

2206The title may go on the next line:

2207

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

2209 "The free software foundation"

2210

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

2212

2213 Here is [my link][FOO]

2214

2215 [Foo]: /bar/baz

2216

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

2218empty, or omitted entirely:

2219

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

2221

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

2223

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

2225reference link definitions cannot occur in nested constructions

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

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

2228not in most other implementations:

2229

2230 > My block [quote].

2231 >

2232 > [quote]: /foo

2233

2234### Internal links

2235

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

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

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

2239For example:

2240

2241 See the [Introduction](#introduction).

2242

2243or

2244

2245 See the [Introduction].

2246

2247 [Introduction]: #introduction

2248

2249Internal links are currently supported for HTML formats (including

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

2251

2252Images

2253------

2254

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

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

2257

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

2259

2260 ![movie reel]

2261

2262 [movie reel]: movie.gif

2263

2264### Pictures with captions ###

2265

2266**Extension: `implicit_figures`**

2267

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

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

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

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

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

2273

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

2275

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

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

2278 itself, with no caption.

2279

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

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

2282nonbreaking space after the image:

2283

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

2285

2286

2287Footnotes

2288---------

2289

2290**Extension: `footnotes`**

2291

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

2293

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

2295

2296 [^1]: Here is the footnote.

2297

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

2299

2300 Subsequent paragraphs are indented to show that they

2301 belong to the previous footnote.

2302

2303 { some.code }

2304

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

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

2307 multi-paragraph list items.

2308

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

2310 isn't indented.

2311

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

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

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

2315will be numbered sequentially.

2316

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

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

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

2320

2321**Extension: `inline_notes`**

2322

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

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

2325

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

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

2328 note.]

2329

2330Inline and regular footnotes may be mixed freely.

2331

2332

2333Citations

2334---------

2335

2336**Extension: `citations`**

2337

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

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

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

2341

2342 Format File extension

2343 ------------ --------------

2344 MODS .mods

2345 BibLaTeX .bib

2346 BibTeX .bibtex

2347 RIS .ris

2348 EndNote .enl

2349 EndNote XML .xml

2350 ISI .wos

2351 MEDLINE .medline

2352 Copac .copac

2353 JSON citeproc .json

2354

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

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

2357

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

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

2360bibliographies).

2361

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

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

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

2365creating and modifying CSL styles can be found at

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

2367A repository of CSL styles can be found at

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

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

2370

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

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

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

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

2375

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

2377

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

2379

2380 Blah blah [@smith04; @doe99].

2381

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

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

2384author is already mentioned in the text:

2385

2386 Smith says blah [-@smith04].

2387

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

2389

2390 @smith04 says blah.

2391

2392 @smith04 [p. 33] says blah.

2393

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

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

2396document with an appropriate header:

2397

2398 last paragraph...

2399

2400 # References

2401

2402The bibliography will be inserted after this header.

2403

2404Non-pandoc extensions

2405---------------------

2406

2407The following markdown syntax extensions are not enabled by default

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

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

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

2411

2412**Extension: `hard_line_breaks`**\

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

2414breaks instead of spaces.

2415

2416**Extension: `tex_math_single_backslash`**\

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

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

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

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

2421

2422**Extension: `tex_math_double_backslash`**\

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

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

2425as display TeX math.

2426

2427**Extension: `markdown_attribute`**\

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

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

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

2431

2432**Extension: `mmd_title_block`**\

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

2434the document, for example:

2435

2436 Title: My title

2437 Author: John Doe

2438 Date: September 1, 2008

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

2440 a field spanning multiple lines.

2441

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

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

2444pandoc. If `pandoc_title_block` or `yaml_metadata_block` is enabled,

2445it will take precedence over `mmd_title_block`.

2446

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

2448

2449**Extension: `abbreviations`**\

2450Parses PHP Markdown Extra abbreviation keys, like

2451

2452 *[HTML]: Hyper Text Markup Language

2453

2454Note that the pandoc document model does not support

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

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

2457

2458**Extension: `autolink_bare_uris`**\

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

2460pointy braces `<...>`.

2461

2462**Extension: `ascii_identifiers`**\

2463Causes the identifiers produced by `auto_identifiers` to be pure ASCII.

2464Accents are stripped off of accented latin letters, and non-latin

2465letters are omitted.

2466

2467**Extension: `link_attributes`**\

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

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

2470these, so they are presently just ignored.

2471

2472**Extension: `mmd_header_identifiers`**\

2473Parses multimarkdown style header identifiers (in square brackets,

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

2475

2476Markdown variants

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

2478

2479In addition to pandoc's extended markdown, the following markdown

2480variants are supported:

2481

2482`markdown_phpextra` (PHP Markdown Extra)

2483: `footnotes`, `pipe_tables`, `raw_html`, `markdown_attribute`,

2484 `fenced_code_blocks`, `definition_lists`, `intraword_underscores`,

2485 `header_attributes`, `abbreviations`.

2486

2487`markdown_github` (Github-flavored Markdown)

2488: `pipe_tables`, `raw_html`, `tex_math_single_backslash`,

2489 `fenced_code_blocks`, `fenced_code_attributes`, `auto_identifiers`,

2490 `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`,

2491 `intraword_underscores`, `strikeout`, `hard_line_breaks`

2492

2493`markdown_mmd` (MultiMarkdown)

2494: `pipe_tables` `raw_html`, `markdown_attribute`, `link_attributes`,

2495 `raw_tex`, `tex_math_double_backslash`, `intraword_underscores`,

2496 `mmd_title_block`, `footnotes`, `definition_lists`,

2497 `all_symbols_escapable`, `implicit_header_references`,

2498 `auto_identifiers`, `mmd_header_identifiers`

2499

2500`markdown_strict` (Markdown.pl)

2501: `raw_html`

2502

2503Producing slide shows with Pandoc

2504=================================

2505

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

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

2508using [S5], [DZSlides], [Slidy], [Slideous], or [reveal.js].

2509You can also produce a PDF slide show using LaTeX [beamer].

2510

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

2512

2513 % Habits

2514 % John Doe

2515 % March 22, 2005

2516

2517 # In the morning

2518

2519 ## Getting up

2520

2521 - Turn off alarm

2522 - Get out of bed

2523

2524 ## Breakfast

2525

2526 - Eat eggs

2527 - Drink coffee

2528

2529 # In the evening

2530

2531 ## Dinner

2532

2533 - Eat spaghetti

2534 - Drink wine

2535

2536 ------------------

2537

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

2539

2540 ## Going to sleep

2541

2542 - Get in bed

2543 - Count sheep

2544

2545To produce an HTML/javascript slide show, simply type

2546

2547 pandoc -t FORMAT -s habits.txt -o habits.html

2548

2549where `FORMAT` is either `s5`, `slidy`, `slideous`, `dzslides`, or `revealjs`.

2550

2551For Slidy, Slideous, reveal.js, and S5, the file produced by pandoc with the

2552`-s/--standalone` option embeds a link to javascripts and CSS files, which are

2553assumed to be available at the relative path `s5/default` (for S5), `slideous`

2554(for Slideous), `reveal.js` (for reveal.js), or at the Slidy website at

2555`w3.org` (for Slidy). (These paths can be changed by setting the `slidy-url`,

2556`slideous-url`, `revealjs-url`, or `s5-url` variables; see `--variable`,

2557above.) For DZSlides, the (relatively short) javascript and css are included in

2558the file by default.

2559

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

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

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

2563

2564To produce a PDF slide show using beamer, type

2565

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

2567

2568Note that a reveal.js slide show can also be converted to a PDF

2569by printing it to a file from the browser.

2570

2571Structuring the slide show

2572--------------------------

2573

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

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

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

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

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

2579the `--slide-level` option.

2580

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

2582rules:

2583

2584 * A horizontal rule always starts a new slide.

2585

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

2587

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

2589 headers *within* a slide.

2590

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

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

2593 and help to break the slide show into sections.

2594

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

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

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

2598

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

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

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

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

2603sections, as in the example above.

2604

2605Note: in reveal.js slide shows, if slide level is 2, a two-dimensional

2606layout will be produced, with level 1 headers building horizontally

2607and level 2 headers building vertically. It is not recommended that

2608you use deeper nesting of section levels with reveal.js.

2609

2610Incremental lists

2611-----------------

2612

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

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

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

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

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

2618

2619 > - Eat spaghetti

2620 > - Drink wine

2621

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

2623a single document.

2624

2625Inserting pauses

2626----------------

2627

2628In reveal.js and beamer slide shows, you can add "pauses" within

2629a slide by including a paragraph containing three dots, separated

2630by spaces:

2631

2632 # Slide with a pause

2633

2634 content before the pause

2635

2636 . . .

2637

2638 content after the pause

2639

2640Styling the slides

2641------------------

2642

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

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

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

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

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

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

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

2650

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

2652be modified there.

2653

2654For reveal.js, themes can be used by setting the `theme` variable,

2655for example:

2656

2657 -V theme=moon

2658

2659Or you can specify a custom stylesheet using the `--css` option.

2660

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

2662using the `-V` option:

2663

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

2665

2666Literate Haskell support

2667========================

2668

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

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

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

2672literate Haskell source. This means that

2673

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

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

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

2677

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

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

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

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

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

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

2684

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

2686 as Haskell code.

2687

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

2689 be rendered using bird tracks.

2690

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

2692 Haskell code.

2693

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

2695 inside `code` environments.

2696

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

2698 with class `literatehaskell` and bird tracks.

2699

2700Examples:

2701

2702 pandoc -f markdown+lhs -t html

2703

2704reads literate Haskell source formatted with markdown conventions and writes

2705ordinary HTML (without bird tracks).

2706

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

2708

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

2710and pasted as literate Haskell source.

2711

2712Custom writers

2713==============

2714

2715Pandoc can be extended with custom writers written in [lua]. (Pandoc

2716includes a lua interpreter, so lua need not be installed separately.)

2717

2718To use a custom writer, simply specify the path to the lua script

2719in place of the output format. For example:

2720

2721 pandoc -t data/sample.lua

2722

2723Creating a custom writer requires writing a lua function for each

2724possible element in a pandoc document. To get a documented example

2725which you can modify according to your needs, do

2726

2727 pandoc --print-sample-lua-writer

2728

2729Authors

2730=======

2731

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

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

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

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

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

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

2739Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

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

2742

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

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

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

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

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

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

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

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

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

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

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

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

2755[DocBook]: http://www.docbook.org/

2756[OPML]: http://dev.opml.org/spec2.html

2757[OpenDocument]: http://opendocument.xml.org/

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

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

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

2761[Haddock markup]: http://www.haskell.org/haddock/doc/html/ch03s08.html

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

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

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

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

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

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

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

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

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

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

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

2773[reveal.js]: http://lab.hakim.se/reveal-js/

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

2775[lua]: TODO

2776