README · typeable/pandoc

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

1350

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

1352

1353

1354### Numbered example lists ###

1355

1356**Extension: `example_lists`**

1357

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

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

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

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

1362where the last stopped. So, for example:

1363

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

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

1366

1367 Explanation of examples.

1368

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

1370

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

1372document:

1373

1374 (@good) This is a good example.

1375

1376 As (@good) illustrates, ...

1377

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

1379or hyphens.

1380

1381

1382### Compact and loose lists ###

1383

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

1385cases" involving lists. Consider this source:

1386

1387 + First

1388 + Second:

1389 - Fee

1390 - Fie

1391 - Foe

1392

1393 + Third

1394

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

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

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

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

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

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

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

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

1403behavior is consistent with the official markdown syntax description,

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

1405

1406

1407### Ending a list ###

1408

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

1410

1411 - item one

1412 - item two

1413

1414 { my code block }

1415

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

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

1418a code block.

1419

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

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

1422any format:

1423

1424 - item one

1425 - item two

1426

1427

1428

1429 { my code block }

1430

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

1432of one big list:

1433

1434 1. one

1435 2. two

1436 3. three

1437

1438

1439

1440 1. uno

1441 2. dos

1442 3. tres

1443

1444Horizontal rules

1445----------------

1446

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

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

1450 * * * *

1452 ---------------

1455Tables

1456------

1457

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

1459`pipe_tables`, `table_captions`**

1460

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

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

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

1464

1465### Simple tables

1466

1467Simple tables look like this:

1468

1469 Right Left Center Default

1470 ------- ------ ---------- -------

1471 12 12 12 12

1472 123 123 123 123

1473 1 1 1 1

1474

1475 Table: Demonstration of simple table syntax.

1476

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

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

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

1480

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

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

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

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

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

1486 the column is centered.

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

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

1489

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

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

1492

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

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

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

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

1497before or after the table.

1498

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

1500to end the table. For example:

1501

1502 ------- ------ ---------- -------

1503 12 12 12 12

1504 123 123 123 123

1505 1 1 1 1

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

1507

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

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

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

1511

1512### Multiline tables

1513

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

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

1516not supported). Here is an example:

1517

1518 -------------------------------------------------------------

1519 Centered Default Right Left

1520 Header Aligned Aligned Aligned

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

1522 First row 12.0 Example of a row that

1523 spans multiple lines.

1524

1525 Second row 5.0 Here's another one. Note

1526 the blank line between

1527 rows.

1528 -------------------------------------------------------------

1529

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

1531 multiple lines.

1532

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

1534

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

1536 (unless the headers are omitted).

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

1538 - The rows must be separated by blank lines.

1539

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

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

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

1543output, try widening it in the markdown source.

1544

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

1546

1547 ----------- ------- --------------- -------------------------

1548 First row 12.0 Example of a row that

1549 spans multiple lines.

1550

1551 Second row 5.0 Here's another one. Note

1552 the blank line between

1553 rows.

1554 ----------- ------- --------------- -------------------------

1555

1556 : Here's a multiline table without headers.

1557

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

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

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

1561

1562### Grid tables

1563

1564Grid tables look like this:

1565

1566 : Sample grid table.

1567

1568 +---------------+---------------+--------------------+

1569 | Fruit | Price | Advantages |

1570 +===============+===============+====================+

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

1572 | | | - bright color |

1573 +---------------+---------------+--------------------+

1574 | Oranges | $2.10 | - cures scurvy |

1575 | | | - tasty |

1576 +---------------+---------------+--------------------+

1577

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

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

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

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

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

1583

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

1585

1586### Pipe tables

1587

1588Pipe tables look like this:

1589

1591 |------:|:-----|---------|:------:|

1592 | 12 | 12 | 12 | 12 |

1593 | 123 | 123 | 123 | 123 |

1594 | 1 | 1 | 1 | 1 |

1595

1596 : Demonstration of simple table syntax.

1597

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

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

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

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

1602it defines column alignments.

1603

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

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

1606legal (though ugly) pipe table:

1607

1608 fruit| price

1609 -----|-----:

1610 apple|2.05

1611 pear|1.37

1612 orange|3.09

1613

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

1615and lists, and cannot span multiple lines.

1616

1617 [the same as in PHP markdown extra]:

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

1619

1620Note: Pandoc also recognizes pipe tables of the following

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

1622

1623 | One | Two |

1624 |-----+-------|

1625 | my | table |

1626 | is | nice |

1627

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

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

1630you'll need to add colons as above.

1631

1632Title block

1633-----------

1634

1635**Extension: `pandoc_title_block`**

1636

1637If the file begins with a title block

1638

1639 % title

1640 % author(s) (separated by semicolons)

1641 % date

1642

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

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

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

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

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

1648

1649 %

1650 % Author

1651

1652 % My title

1653 %

1654 % June 15, 2006

1655

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

1657begin with leading space, thus:

1658

1659 % My title

1660 on multiple lines

1661

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

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

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

1665

1666 % Author One

1667 Author Two

1668

1669 % Author One; Author Two

1670

1671 % Author One;

1672 Author Two

1673

1674The date must fit on one line.

1675

1676All three metadata fields may contain standard inline formatting

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

1678

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

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

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

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

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

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

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

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

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

1688be used by itself as the HTML title.

1689

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

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

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

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

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

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

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

1697text. Thus,

1698

1699 % PANDOC(1)

1700

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

1702

1703 % PANDOC(1) Pandoc User Manuals

1704

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

1706

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

1708

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

1710

1711

1712Backslash escapes

1713-----------------

1714

1715**Extension: `all_symbols_escapable`**

1716

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

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

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

1720

1721 *\*hello\**

1722

1723one will get

1724

1725 <em>*hello*</em>

1726

1727instead of

1728

1729 <strong>hello</strong>

1730

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

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

1733

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

1735

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

1737will be used.)

1738

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

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

1741`\ `.

1742

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

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

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

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

1747two trailing spaces on a line.

1748

1749Backslash escapes do not work in verbatim contexts.

1750

1751Smart punctuation

1752-----------------

1753

1754**Extension**

1755

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

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

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

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

1760

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

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

1763

1764Inline formatting

1765-----------------

1766

1767### Emphasis ###

1768

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

1770

1771 This text is _emphasized with underscores_, and this

1772 is *emphasized with asterisks*.

1773

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

1775

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

1777

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

1779will not trigger emphasis:

1780

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

1782

1783**Extension: `intraword_underscores`**

1784

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

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

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

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

1789

1790 feas*ible*, not feas*able*.

1791

1792

1793### Strikeout ###

1794

1795**Extension: `strikeout`**

1796

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

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

1799

1800 This ~~is deleted text.~~

1801

1802

1803### Superscripts and subscripts ###

1804

1805**Extension: `superscript`, `subscript`**

1806

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

1808characters; subscripts may be written by surrounding the subscripted

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

1810

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

1812

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

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

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

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

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

1818

1819

1820### Verbatim ###

1821

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

1823

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

1825

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

1827

1828 Here is a literal backtick `` ` ``.

1829

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

1831backticks will be ignored.)

1832

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

1834of consecutive backticks (optionally followed by a space)

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

1836preceded by a space).

1837

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

1839work in verbatim contexts:

1840

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

1842

1843**Extension: `inline_code_attributes`**

1844

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

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

1847

1848 `<$>`{.haskell}

1849

1850Math

1851----

1852

1853**Extension: `tex_math_dollars`**

1854

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

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

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

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

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

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

1861

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

1863depends on the output format:

1864

1865Markdown, LaTeX, Org-Mode, ConTeXt

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

1867

1868reStructuredText

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

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

1871

1872AsciiDoc

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

1874

1875Texinfo

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

1877

1878groff man

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

1880

1881MediaWiki

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

1883

1884Textile

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

1886

1887RTF, OpenDocument, ODT

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

1889 and will otherwise appear verbatim.

1890

1891Docbook

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

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

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

1895

1896Docx

1897 ~ It will be rendered using OMML math markup.

1898

1899FictionBook2

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

1901 using Google Charts or other compatible web service, downloaded

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

1903

1904HTML, Slidy, DZSlides, S5, EPUB

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

1906 command-line options selected:

1907

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

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

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

1911 styled differently from the surrounding text if needed.

1912

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

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

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

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

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

1918 verbatim between `$` characters.)

1919

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

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

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

1923 it.

1924

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

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

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

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

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

1930

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

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

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

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

1935 procedure is:

1936

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

1938 gladtex -d myfile-images myfile.htex

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

1940

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

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

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

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

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

1946

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

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

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

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

1951

1952Raw HTML

1953--------

1954

1955**Extension: `raw_html`**

1956

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

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

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

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

1961be disabled if desired.)

1962

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

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

1965formats.

1966

1967**Extension: `markdown_in_html_blocks`**

1968

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

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

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

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

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

1974

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

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

1977Thus, for example, Pandoc will turn

1978

1979 <table>

1980 <tr>

1981 <td>*one*</td>

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

1983 </tr>

1984 </table>

1985

1986into

1987

1988 <table>

1989 <tr>

1990 <td><em>one</em></td>

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

1992 </tr>

1993 </table>

1994

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

1996

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

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

1999

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

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

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

2003from being interpreted as markdown.

2004

2005Raw TeX

2006-------

2007

2008**Extension: `raw_tex`**

2009

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

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

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

2013LaTeX to include BibTeX citations:

2014

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

2016

2017Note that in LaTeX environments, like

2018

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

2020 Age & Frequency \\ \hline

2021 18--25 & 15 \\

2022 26--35 & 33 \\

2023 36--45 & 22 \\ \hline

2024 \end{tabular}

2025

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

2027LaTeX, not as markdown.

2028

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

2030and ConTeXt.

2031

2032LaTeX macros

2033------------

2034

2035**Extension: `latex_macros`**

2036

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

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

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

2040not just LaTeX:

2041

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

2043

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

2045

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

2047unchanged to the output.

2048

2049

2050Links

2051-----

2052

2053Markdown allows links to be specified in several ways.

2054

2055### Automatic links ###

2056

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

2058will become a link:

2059

2060 <http://google.com>

2061 <sam@green.eggs.ham>

2062

2063### Inline links ###

2064

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

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

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

2068

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

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

2071

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

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

2074

2075

2076### Reference links ###

2077

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

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

2080before or after the link).

2081

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

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

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

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

2086parentheses.

2087

2088Here are some examples:

2089

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

2091 [my label 2]: /foo

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

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

2094

2095The URL may optionally be surrounded by angle brackets:

2096

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

2098

2099The title may go on the next line:

2100

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

2102 "The free software foundation"

2103

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

2105

2106 Here is [my link][FOO]

2107

2108 [Foo]: /bar/baz

2109

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

2111empty, or omitted entirely:

2112

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

2114

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

2116

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

2118reference link definitions cannot occur in nested constructions

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

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

2121not in most other implementations:

2122

2123 > My block [quote].

2124 >

2125 > [quote]: /foo

2126

2127### Internal links

2128

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

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

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

2132For example:

2133

2134 See the [Introduction](#introduction).

2135

2136or

2137

2138 See the [Introduction].

2139

2140 [Introduction]: #introduction

2141

2142Internal links are currently supported for HTML formats (including

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

2144

2145Images

2146------

2147

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

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

2150

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

2152

2153 ![movie reel]

2154

2155 [movie reel]: movie.gif

2156

2157### Pictures with captions ###

2158

2159**Extension: `implicit_figures`**

2160

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

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

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

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

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

2166

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

2168

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

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

2171 itself, with no caption.

2172

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

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

2175nonbreaking space after the image:

2176

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

2178

2179

2180Footnotes

2181---------

2182

2183**Extension: `footnotes`**

2184

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

2186

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

2188

2189 [^1]: Here is the footnote.

2190

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

2192

2193 Subsequent paragraphs are indented to show that they

2194 belong to the previous footnote.

2195

2196 { some.code }

2197

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

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

2200 multi-paragraph list items.

2201

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

2203 isn't indented.

2204

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

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

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

2208will be numbered sequentially.

2209

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

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

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

2213

2214**Extension: `inline_notes`**

2215

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

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

2218

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

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

2221 note.]

2222

2223Inline and regular footnotes may be mixed freely.

2224

2225

2226Citations

2227---------

2228

2229**Extension: `citations`**

2230

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

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

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

2234

2235 Format File extension

2236 ------------ --------------

2237 MODS .mods

2238 BibLaTeX .bib

2239 BibTeX .bibtex

2240 RIS .ris

2241 EndNote .enl

2242 EndNote XML .xml

2243 ISI .wos

2244 MEDLINE .medline

2245 Copac .copac

2246 JSON citeproc .json

2247

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

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

2250

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

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

2253bibliographies).

2254

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

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

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

2258creating and modifying CSL styles can be found at

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

2260A repository of CSL styles can be found at

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

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

2263

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

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

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

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

2268

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

2270

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

2272

2273 Blah blah [@smith04; @doe99].

2274

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

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

2277author is already mentioned in the text:

2278

2279 Smith says blah [-@smith04].

2280

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

2282

2283 @smith04 says blah.

2284

2285 @smith04 [p. 33] says blah.

2286

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

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

2289document with an appropriate header:

2290

2291 last paragraph...

2292

2293 # References

2294

2295The bibliography will be inserted after this header.

2296

2297Non-pandoc extensions

2298=====================

2299

2300The following markdown syntax extensions are not enabled by default

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

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

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

2304

2305**Extension: `hard_line_breaks`**\

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

2307breaks instead of spaces.

2308

2309**Extension: `tex_math_single_backslash`**\

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

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

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

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

2314

2315**Extension: `tex_math_double_backslash`**\

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

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

2318as display TeX math.

2319

2320**Extension: `markdown_attribute`**\

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

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

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

2324

2325**Extension: `mmd_title_block`**\

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

2327the document, for example:

2328

2329 Title: My title

2330 Author: John Doe

2331 Date: September 1, 2008

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

2333 a field spanning multiple lines.

2334

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

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

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

2338`mmd_title_block`.

2339

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

2341

2342**Extension: `abbrevations`**\

2343Parses PHP Markdown Extra abbreviation keys, like

2344

2345 *[HTML]: Hyper Text Markup Language

2346

2347Note that the pandoc document model does not support

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

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

2350

2351**Extension: `autolink_bare_uris`**\

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

2353pointy braces `<...>`.

2354

2355**Extension: `link_attributes`**\

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

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

2358these, so they are presently just ignored.

2359

2360**Extension: `mmd_header_identifiers`**\

2361Parses multimarkdown style header identifiers (in square brackets,

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

2363

2364Producing slide shows with Pandoc

2365=================================

2366

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

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

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

2370PDF slide show using LaTeX [beamer].

2371

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

2373

2374 % Habits

2375 % John Doe

2376 % March 22, 2005

2377

2378 # In the morning

2379

2380 ## Getting up

2381

2382 - Turn off alarm

2383 - Get out of bed

2384

2385 ## Breakfast

2386

2387 - Eat eggs

2388 - Drink coffee

2389

2390 # In the evening

2391

2392 ## Dinner

2393

2394 - Eat spaghetti

2395 - Drink wine

2396

2397 ------------------

2398

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

2400

2401 ## Going to sleep

2402

2403 - Get in bed

2404 - Count sheep

2405

2406To produce the slide show, simply type

2407

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

2409

2410for S5,

2411

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

2413

2414for Slidy,

2415

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

2417

2418for Slideous,

2419

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

2421

2422for DZSlides, or

2423

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

2425

2426for beamer.

2427

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

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

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

2431

2432Structuring the slide show

2433--------------------------

2434

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

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

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

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

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

2440the `--slide-level` option.

2441

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

2443rules:

2444

2445 * A horizontal rule always starts a new slide.

2446

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

2448

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

2450 headers *within* a slide.

2451

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

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

2454 and help to break the slide show into sections.

2455

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

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

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

2459

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

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

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

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

2464sections, as in the example above.

2465

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

2467`-s/--standalone`

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

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

2470(for Slideous), or at the Slidy

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

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

2473above.) For DZSlides,

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

2475

2476Incremental lists

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

2478

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

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

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

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

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

2484

2485 > - Eat spaghetti

2486 > - Drink wine

2487

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

2489a single document.

2490

2491Styling the slides

2492------------------

2493

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

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

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

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

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

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

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

2501

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

2503be modified there.

2504

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

2506using the `-V` option:

2507

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

2509

2510Literate Haskell support

2511========================

2512

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

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

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

2516literate Haskell source. This means that

2517

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

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

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

2521

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

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

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

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

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

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

2528

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

2530 as Haskell code.

2531

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

2533 be rendered using bird tracks.

2534

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

2536 Haskell code.

2537

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

2539 inside `code` environments.

2540

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

2542 with class `literatehaskell` and bird tracks.

2543

2544Examples:

2545

2546 pandoc -f markdown+lhs -t html

2547

2548reads literate Haskell source formatted with markdown conventions and writes

2549ordinary HTML (without bird tracks).

2550

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

2552

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

2554and pasted as literate Haskell source.

2555

2556Authors

2557=======

2558

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

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

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

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

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

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

2566Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

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

2569

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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