README · typeable/pandoc

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

1430

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

1432

1433

1434### Numbered example lists ###

1435

1436**Extension: `example_lists`**

1437

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

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

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

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

1442where the last stopped. So, for example:

1443

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

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

1446

1447 Explanation of examples.

1448

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

1450

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

1452document:

1453

1454 (@good) This is a good example.

1455

1456 As (@good) illustrates, ...

1457

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

1459or hyphens.

1460

1461

1462### Compact and loose lists ###

1463

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

1465cases" involving lists. Consider this source:

1466

1467 + First

1468 + Second:

1469 - Fee

1470 - Fie

1471 - Foe

1472

1473 + Third

1474

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

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

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

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

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

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

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

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

1483behavior is consistent with the official markdown syntax description,

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

1485

1486

1487### Ending a list ###

1488

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

1490

1491 - item one

1492 - item two

1493

1494 { my code block }

1495

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

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

1498a code block.

1499

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

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

1502any format:

1503

1504 - item one

1505 - item two

1506

1507

1508

1509 { my code block }

1510

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

1512of one big list:

1513

1514 1. one

1515 2. two

1516 3. three

1517

1518

1519

1520 1. uno

1521 2. dos

1522 3. tres

1523

1524Horizontal rules

1525----------------

1526

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

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

1530 * * * *

1532 ---------------

1535Tables

1536------

1537

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

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

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

1541

1542### Simple tables

1543

1544**Extension: `simple_tables`, `table_captions`**

1545

1546Simple tables look like this:

1547

1548 Right Left Center Default

1549 ------- ------ ---------- -------

1550 12 12 12 12

1551 123 123 123 123

1552 1 1 1 1

1553

1554 Table: Demonstration of simple table syntax.

1555

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

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

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

1559

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

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

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

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

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

1565 the column is centered.

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

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

1568

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

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

1571

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

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

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

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

1576before or after the table.

1577

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

1579to end the table. For example:

1580

1581 ------- ------ ---------- -------

1582 12 12 12 12

1583 123 123 123 123

1584 1 1 1 1

1585 ------- ------ ---------- -------

1586

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

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

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

1590

1591### Multiline tables

1592

1593**Extension: `multiline_tables`, `table_captions`**

1594

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

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

1597not supported). Here is an example:

1598

1599 -------------------------------------------------------------

1600 Centered Default Right Left

1601 Header Aligned Aligned Aligned

1602 ----------- ------- --------------- -------------------------

1603 First row 12.0 Example of a row that

1604 spans multiple lines.

1605

1606 Second row 5.0 Here's another one. Note

1607 the blank line between

1608 rows.

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

1610

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

1612 multiple lines.

1613

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

1615

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

1617 (unless the headers are omitted).

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

1619 - The rows must be separated by blank lines.

1620

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

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

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

1624output, try widening it in the markdown source.

1625

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

1627

1628 ----------- ------- --------------- -------------------------

1629 First row 12.0 Example of a row that

1630 spans multiple lines.

1631

1632 Second row 5.0 Here's another one. Note

1633 the blank line between

1634 rows.

1635 ----------- ------- --------------- -------------------------

1636

1637 : Here's a multiline table without headers.

1638

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

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

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

1642

1643### Grid tables

1644

1645**Extension: `grid_tables`, `table_captions`**

1646

1647Grid tables look like this:

1648

1649 : Sample grid table.

1650

1651 +---------------+---------------+--------------------+

1652 | Fruit | Price | Advantages |

1653 +===============+===============+====================+

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

1655 | | | - bright color |

1656 +---------------+---------------+--------------------+

1657 | Oranges | $2.10 | - cures scurvy |

1658 | | | - tasty |

1659 +---------------+---------------+--------------------+

1660

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

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

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

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

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

1666

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

1668

1669### Pipe tables

1670

1671**Extension: `pipe_tables`, `table_captions`**

1672

1673Pipe tables look like this:

1674

1676 |------:|:-----|---------|:------:|

1677 | 12 | 12 | 12 | 12 |

1678 | 123 | 123 | 123 | 123 |

1679 | 1 | 1 | 1 | 1 |

1680

1681 : Demonstration of simple table syntax.

1682

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

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

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

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

1687it defines column alignments.

1688

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

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

1691legal (though ugly) pipe table:

1692

1693 fruit| price

1694 -----|-----:

1695 apple|2.05

1696 pear|1.37

1697 orange|3.09

1698

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

1700and lists, and cannot span multiple lines.

1701

1702 [the same as in PHP markdown extra]:

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

1704

1705Note: Pandoc also recognizes pipe tables of the following

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

1707

1708 | One | Two |

1709 |-----+-------|

1710 | my | table |

1711 | is | nice |

1712

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

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

1715you'll need to add colons as above.

1716

1717Title block

1718-----------

1719

1720**Extension: `pandoc_title_block`**

1721

1722If the file begins with a title block

1723

1724 % title

1725 % author(s) (separated by semicolons)

1726 % date

1727

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

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

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

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

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

1733

1734 %

1735 % Author

1736

1737 % My title

1738 %

1739 % June 15, 2006

1740

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

1742begin with leading space, thus:

1743

1744 % My title

1745 on multiple lines

1746

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

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

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

1750

1751 % Author One

1752 Author Two

1753

1754 % Author One; Author Two

1755

1756 % Author One;

1757 Author Two

1758

1759The date must fit on one line.

1760

1761All three metadata fields may contain standard inline formatting

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

1763

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

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

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

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

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

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

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

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

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

1773be used by itself as the HTML title.

1774

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

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

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

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

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

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

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

1782text. Thus,

1783

1784 % PANDOC(1)

1785

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

1787

1788 % PANDOC(1) Pandoc User Manuals

1789

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

1791

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

1793

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

1795

1796YAML metadata block

1797-------------------

1798

1799**Extension: `yaml_metadata_block`**

1800

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

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

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

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

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

1806

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

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

1809

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

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

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

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

1814when the field contains blank lines:

1815

1816 ---

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

1818 author:

1819 - name: Author One

1820 affiliation: University of Somewhere

1821 - name: Author Two

1822 affiliation: University of Nowhere

1823 tags: [nothing, nothingness]

1824 abstract: |

1825 This is the abstract.

1826

1827 It consists of two paragraphs.

1828 ...

1829

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

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

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

1833

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

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

1836

1837

1838Backslash escapes

1839-----------------

1840

1841**Extension: `all_symbols_escapable`**

1842

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

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

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

1846

1847 *\*hello\**

1848

1849one will get

1850

1851 <em>*hello*</em>

1852

1853instead of

1854

1855 <strong>hello</strong>

1856

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

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

1859

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

1861

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

1863will be used.)

1864

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

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

1867`\ `.

1868

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

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

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

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

1873two trailing spaces on a line.

1874

1875Backslash escapes do not work in verbatim contexts.

1876

1877Smart punctuation

1878-----------------

1879

1880**Extension**

1881

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

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

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

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

1886

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

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

1889

1890Inline formatting

1891-----------------

1892

1893### Emphasis ###

1894

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

1896

1897 This text is _emphasized with underscores_, and this

1898 is *emphasized with asterisks*.

1899

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

1901

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

1903

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

1905will not trigger emphasis:

1906

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

1908

1909**Extension: `intraword_underscores`**

1910

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

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

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

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

1915

1916 feas*ible*, not feas*able*.

1917

1918

1919### Strikeout ###

1920

1921**Extension: `strikeout`**

1922

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

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

1925

1926 This ~~is deleted text.~~

1927

1928

1929### Superscripts and subscripts ###

1930

1931**Extension: `superscript`, `subscript`**

1932

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

1934characters; subscripts may be written by surrounding the subscripted

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

1936

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

1938

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

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

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

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

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

1944

1945

1946### Verbatim ###

1947

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

1949

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

1951

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

1953

1954 Here is a literal backtick `` ` ``.

1955

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

1957backticks will be ignored.)

1958

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

1960of consecutive backticks (optionally followed by a space)

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

1962preceded by a space).

1963

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

1965work in verbatim contexts:

1966

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

1968

1969**Extension: `inline_code_attributes`**

1970

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

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

1973

1974 `<$>`{.haskell}

1975

1976Math

1977----

1978

1979**Extension: `tex_math_dollars`**

1980

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

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

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

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

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

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

1987

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

1989depends on the output format:

1990

1991Markdown, LaTeX, Org-Mode, ConTeXt

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

1993

1994reStructuredText

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

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

1997

1998AsciiDoc

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

2000

2001Texinfo

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

2003

2004groff man

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

2006

2007MediaWiki

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

2009

2010Textile

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

2012

2013RTF, OpenDocument, ODT

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

2015 and will otherwise appear verbatim.

2016

2017Docbook

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

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

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

2021

2022Docx

2023 ~ It will be rendered using OMML math markup.

2024

2025FictionBook2

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

2027 using Google Charts or other compatible web service, downloaded

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

2029

2030HTML, Slidy, DZSlides, S5, EPUB

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

2032 command-line options selected:

2033

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

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

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

2037 styled differently from the surrounding text if needed.

2038

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

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

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

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

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

2044 verbatim between `$` characters.)

2045

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

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

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

2049 it.

2050

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

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

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

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

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

2056

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

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

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

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

2061 procedure is:

2062

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

2064 gladtex -d myfile-images myfile.htex

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

2066

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

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

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

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

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

2072

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

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

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

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

2077

2078Raw HTML

2079--------

2080

2081**Extension: `raw_html`**

2082

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

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

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

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

2087be disabled if desired.)

2088

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

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

2091formats.

2092

2093**Extension: `markdown_in_html_blocks`**

2094

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

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

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

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

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

2100

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

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

2103Thus, for example, Pandoc will turn

2104

2105 <table>

2106 <tr>

2107 <td>*one*</td>

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

2109 </tr>

2110 </table>

2111

2112into

2113

2114 <table>

2115 <tr>

2116 <td><em>one</em></td>

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

2118 </tr>

2119 </table>

2120

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

2122

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

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

2125

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

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

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

2129from being interpreted as markdown.

2130

2131Raw TeX

2132-------

2133

2134**Extension: `raw_tex`**

2135

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

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

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

2139LaTeX to include BibTeX citations:

2140

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

2142

2143Note that in LaTeX environments, like

2144

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

2146 Age & Frequency \\ \hline

2147 18--25 & 15 \\

2148 26--35 & 33 \\

2149 36--45 & 22 \\ \hline

2150 \end{tabular}

2151

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

2153LaTeX, not as markdown.

2154

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

2156and ConTeXt.

2157

2158LaTeX macros

2159------------

2160

2161**Extension: `latex_macros`**

2162

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

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

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

2166not just LaTeX:

2167

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

2169

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

2171

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

2173unchanged to the output.

2174

2175

2176Links

2177-----

2178

2179Markdown allows links to be specified in several ways.

2180

2181### Automatic links ###

2182

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

2184will become a link:

2185

2186 <http://google.com>

2187 <sam@green.eggs.ham>

2188

2189### Inline links ###

2190

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

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

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

2194

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

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

2197

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

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

2200

2201

2202### Reference links ###

2203

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

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

2206before or after the link).

2207

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

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

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

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

2212parentheses.

2213

2214Here are some examples:

2215

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

2217 [my label 2]: /foo

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

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

2220

2221The URL may optionally be surrounded by angle brackets:

2222

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

2224

2225The title may go on the next line:

2226

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

2228 "The free software foundation"

2229

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

2231

2232 Here is [my link][FOO]

2233

2234 [Foo]: /bar/baz

2235

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

2237empty, or omitted entirely:

2238

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

2240

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

2242

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

2244reference link definitions cannot occur in nested constructions

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

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

2247not in most other implementations:

2248

2249 > My block [quote].

2250 >

2251 > [quote]: /foo

2252

2253### Internal links

2254

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

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

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

2258For example:

2259

2260 See the [Introduction](#introduction).

2261

2262or

2263

2264 See the [Introduction].

2265

2266 [Introduction]: #introduction

2267

2268Internal links are currently supported for HTML formats (including

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

2270

2271Images

2272------

2273

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

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

2276

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

2278

2279 ![movie reel]

2280

2281 [movie reel]: movie.gif

2282

2283### Pictures with captions ###

2284

2285**Extension: `implicit_figures`**

2286

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

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

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

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

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

2292

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

2294

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

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

2297 itself, with no caption.

2298

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

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

2301nonbreaking space after the image:

2302

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

2304

2305

2306Footnotes

2307---------

2308

2309**Extension: `footnotes`**

2310

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

2312

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

2314

2315 [^1]: Here is the footnote.

2316

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

2318

2319 Subsequent paragraphs are indented to show that they

2320 belong to the previous footnote.

2321

2322 { some.code }

2323

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

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

2326 multi-paragraph list items.

2327

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

2329 isn't indented.

2330

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

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

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

2334will be numbered sequentially.

2335

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

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

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

2339

2340**Extension: `inline_notes`**

2341

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

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

2344

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

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

2347 note.]

2348

2349Inline and regular footnotes may be mixed freely.

2350

2351

2352Citations

2353---------

2354

2355**Extension: `citations`**

2356

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

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

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

2360

2361 Format File extension

2362 ------------ --------------

2363 MODS .mods

2364 BibLaTeX .bib

2365 BibTeX .bibtex

2366 RIS .ris

2367 EndNote .enl

2368 EndNote XML .xml

2369 ISI .wos

2370 MEDLINE .medline

2371 Copac .copac

2372 JSON citeproc .json

2373

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

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

2376

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

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

2379bibliographies).

2380

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

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

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

2384creating and modifying CSL styles can be found at

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

2386A repository of CSL styles can be found at

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

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

2389

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

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

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

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

2394

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

2396

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

2398

2399 Blah blah [@smith04; @doe99].

2400

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

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

2403author is already mentioned in the text:

2404

2405 Smith says blah [-@smith04].

2406

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

2408

2409 @smith04 says blah.

2410

2411 @smith04 [p. 33] says blah.

2412

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

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

2415document with an appropriate header:

2416

2417 last paragraph...

2418

2419 # References

2420

2421The bibliography will be inserted after this header.

2422

2423Non-pandoc extensions

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

2425

2426The following markdown syntax extensions are not enabled by default

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

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

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

2430

2431**Extension: `hard_line_breaks`**\

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

2433breaks instead of spaces.

2434

2435**Extension: `ignore_line_breaks`**\

2436Causes newlines within a paragraph to be ignored, rather than being

2437treated as spaces or as hard line breaks. This option is intended for

2438use with East Asian languages where spaces are not used between words,

2439but text is divided into lines for readability.

2440

2441**Extension: `tex_math_single_backslash`**\

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

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

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

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

2446

2447**Extension: `tex_math_double_backslash`**\

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

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

2450as display TeX math.

2451

2452**Extension: `markdown_attribute`**\

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

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

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

2456

2457**Extension: `mmd_title_block`**\

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

2459the document, for example:

2460

2461 Title: My title

2462 Author: John Doe

2463 Date: September 1, 2008

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

2465 a field spanning multiple lines.

2466

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

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

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

2470it will take precedence over `mmd_title_block`.

2471

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

2473

2474**Extension: `abbreviations`**\

2475Parses PHP Markdown Extra abbreviation keys, like

2476

2477 *[HTML]: Hyper Text Markup Language

2478

2479Note that the pandoc document model does not support

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

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

2482

2483**Extension: `autolink_bare_uris`**\

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

2485pointy braces `<...>`.

2486

2487**Extension: `ascii_identifiers`**\

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

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

2490letters are omitted.

2491

2492**Extension: `link_attributes`**\

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

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

2495these, so they are presently just ignored.

2496

2497**Extension: `mmd_header_identifiers`**\

2498Parses multimarkdown style header identifiers (in square brackets,

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

2500

2501Markdown variants

2502-----------------

2503

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

2505variants are supported:

2506

2507`markdown_phpextra` (PHP Markdown Extra)

2508: `footnotes`, `pipe_tables`, `raw_html`, `markdown_attribute`,

2509 `fenced_code_blocks`, `definition_lists`, `intraword_underscores`,

2510 `header_attributes`, `abbreviations`.

2511

2512`markdown_github` (Github-flavored Markdown)

2513: `pipe_tables`, `raw_html`, `tex_math_single_backslash`,

2514 `fenced_code_blocks`, `fenced_code_attributes`, `auto_identifiers`,

2515 `ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`,

2516 `intraword_underscores`, `strikeout`, `hard_line_breaks`

2517

2518`markdown_mmd` (MultiMarkdown)

2519: `pipe_tables` `raw_html`, `markdown_attribute`, `link_attributes`,

2520 `raw_tex`, `tex_math_double_backslash`, `intraword_underscores`,

2521 `mmd_title_block`, `footnotes`, `definition_lists`,

2522 `all_symbols_escapable`, `implicit_header_references`,

2523 `auto_identifiers`, `mmd_header_identifiers`

2524

2525`markdown_strict` (Markdown.pl)

2526: `raw_html`

2527

2528Producing slide shows with Pandoc

2529=================================

2530

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

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

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

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

2535

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

2537

2538 % Habits

2539 % John Doe

2540 % March 22, 2005

2541

2542 # In the morning

2543

2544 ## Getting up

2545

2546 - Turn off alarm

2547 - Get out of bed

2548

2549 ## Breakfast

2550

2551 - Eat eggs

2552 - Drink coffee

2553

2554 # In the evening

2555

2556 ## Dinner

2557

2558 - Eat spaghetti

2559 - Drink wine

2560

2561 ------------------

2562

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

2564

2565 ## Going to sleep

2566

2567 - Get in bed

2568 - Count sheep

2569

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

2571

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

2573

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

2575

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

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

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

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

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

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

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

2583the file by default.

2584

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

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

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

2588

2589To produce a PDF slide show using beamer, type

2590

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

2592

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

2594by printing it to a file from the browser.

2595

2596Structuring the slide show

2597--------------------------

2598

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

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

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

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

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

2604the `--slide-level` option.

2605

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

2607rules:

2608

2609 * A horizontal rule always starts a new slide.

2610

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

2612

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

2614 headers *within* a slide.

2615

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

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

2618 and help to break the slide show into sections.

2619

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

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

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

2623

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

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

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

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

2628sections, as in the example above.

2629

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

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

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

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

2634

2635Incremental lists

2636-----------------

2637

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

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

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

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

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

2643

2644 > - Eat spaghetti

2645 > - Drink wine

2646

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

2648a single document.

2649

2650Inserting pauses

2651----------------

2652

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

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

2655by spaces:

2656

2657 # Slide with a pause

2658

2659 content before the pause

2660

2661 . . .

2662

2663 content after the pause

2664

2665Styling the slides

2666------------------

2667

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

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

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

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

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

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

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

2675

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

2677be modified there.

2678

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

2680for example:

2681

2682 -V theme=moon

2683

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

2685

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

2687using the `-V` option:

2688

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

2690

2691Note that header attributes will turn into slide attributes

2692(on a `<div>` or `<section>`) in HTML slide formats, allowing you

2693to style individual slides. In Beamer, the only header attribute

2694that affects slides is the `allowframebreaks` class, which sets the

2695`allowframebreaks` option, causing multiple slides to be created

2696if the content overfills the frame. This is recommended especially for

2697bibliographies:

2698

2699 # References {.allowframebreaks}

2700

2701Literate Haskell support

2702========================

2703

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

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

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

2707literate Haskell source. This means that

2708

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

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

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

2712

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

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

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

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

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

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

2719

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

2721 as Haskell code.

2722

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

2724 be rendered using bird tracks.

2725

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

2727 Haskell code.

2728

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

2730 inside `code` environments.

2731

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

2733 with class `literatehaskell` and bird tracks.

2734

2735Examples:

2736

2737 pandoc -f markdown+lhs -t html

2738

2739reads literate Haskell source formatted with markdown conventions and writes

2740ordinary HTML (without bird tracks).

2741

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

2743

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

2745and pasted as literate Haskell source.

2746

2747Custom writers

2748==============

2749

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

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

2752

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

2754in place of the output format. For example:

2755

2756 pandoc -t data/sample.lua

2757

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

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

2760which you can modify according to your needs, do

2761

2762 pandoc --print-sample-lua-writer

2763

2764Authors

2765=======

2766

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

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

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

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

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

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

2774Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

2776Sergey Astanin, Arlo O'Keeffe, Denis Laxalde, Brent Yorgey, David Lazar,

2777Jamie F. Olson.

2778

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2811[lua]: TODO

2812