README · typeable/pandoc

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

1211

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

1213

1214

1215### Numbered example lists ###

1216

1217*Pandoc extension*.

1218

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

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

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

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

1223where the last stopped. So, for example:

1224

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

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

1227

1228 Explanation of examples.

1229

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

1231

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

1233document:

1234

1235 (@good) This is a good example.

1236

1237 As (@good) illustrates, ...

1238

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

1240or hyphens.

1241

1242

1243### Compact and loose lists ###

1244

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

1246cases" involving lists. Consider this source:

1247

1248 + First

1249 + Second:

1250 - Fee

1251 - Fie

1252 - Foe

1253

1254 + Third

1255

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

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

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

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

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

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

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

1263Pandoc works this way even when the `--strict` option is specified. This

1264behavior is consistent with the official markdown syntax description,

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

1266

1267

1268### Ending a list ###

1269

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

1271

1272 - item one

1273 - item two

1274

1275 { my code block }

1276

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

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

1279a code block.

1280

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

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

1283any format:

1284

1285 - item one

1286 - item two

1287

1288

1289

1290 { my code block }

1291

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

1293of one big list:

1294

1295 1. one

1296 2. two

1297 3. three

1298

1299

1300

1301 1. uno

1302 2. dos

1303 3. tres

1304

1305Horizontal rules

1306----------------

1307

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

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

1311 * * * *

1313 ---------------

1316Tables

1317------

1318

1319*Pandoc extension*.

1320

1321Three kinds of tables may be used. All three kinds presuppose the use of

1322a fixed-width font, such as Courier.

1323

1324**Simple tables** look like this:

1325

1326 Right Left Center Default

1327 ------- ------ ---------- -------

1328 12 12 12 12

1329 123 123 123 123

1330 1 1 1 1

1331

1332 Table: Demonstration of simple table syntax.

1333

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

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

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

1337

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

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

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

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

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

1343 the column is centered.

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

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

1346

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

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

1349

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

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

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

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

1354before or after the table.

1355

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

1357to end the table. For example:

1358

1359 ------- ------ ---------- -------

1360 12 12 12 12

1361 123 123 123 123

1362 1 1 1 1

1363 ------- ------ ---------- -------

1364

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

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

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

1368

1369**Multiline tables** allow headers and table rows to span multiple lines

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

1371not supported). Here is an example:

1372

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

1374 Centered Default Right Left

1375 Header Aligned Aligned Aligned

1376 ----------- ------- --------------- -------------------------

1377 First row 12.0 Example of a row that

1378 spans multiple lines.

1379

1380 Second row 5.0 Here's another one. Note

1381 the blank line between

1382 rows.

1383 -------------------------------------------------------------

1384

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

1386 multiple lines.

1387

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

1389

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

1391 (unless the headers are omitted).

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

1393 - The rows must be separated by blank lines.

1394

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

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

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

1398output, try widening it in the markdown source.

1399

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

1401

1402 ----------- ------- --------------- -------------------------

1403 First row 12.0 Example of a row that

1404 spans multiple lines.

1405

1406 Second row 5.0 Here's another one. Note

1407 the blank line between

1408 rows.

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

1410

1411 : Here's a multiline table without headers.

1412

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

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

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

1416

1417**Grid tables** look like this:

1418

1419 : Sample grid table.

1420

1421 +---------------+---------------+--------------------+

1422 | Fruit | Price | Advantages |

1423 +===============+===============+====================+

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

1425 | | | - bright color |

1426 +---------------+---------------+--------------------+

1427 | Oranges | $2.10 | - cures scurvy |

1428 | | | - tasty |

1429 +---------------+---------------+--------------------+

1430

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

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

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

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

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

1436

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

1438

1439

1440Title block

1441-----------

1442

1443*Pandoc extension*.

1444

1445If the file begins with a title block

1446

1447 % title

1448 % author(s) (separated by semicolons)

1449 % date

1450

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

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

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

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

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

1456

1457 %

1458 % Author

1459

1460 % My title

1461 %

1462 % June 15, 2006

1463

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

1465begin with leading space, thus:

1466

1467 % My title

1468 on multiple lines

1469

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

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

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

1473

1474 % Author One

1475 Author Two

1476

1477 % Author One; Author Two

1478

1479 % Author One;

1480 Author Two

1481

1482The date must fit on one line.

1483

1484All three metadata fields may contain standard inline formatting

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

1486

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

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

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

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

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

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

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

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

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

1496be used by itself as the HTML title.

1497

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

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

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

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

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

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

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

1505text. Thus,

1506

1507 % PANDOC(1)

1508

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

1510

1511 % PANDOC(1) Pandoc User Manuals

1512

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

1514

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

1516

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

1518

1519

1520Backslash escapes

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

1522

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

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

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

1526

1527 *\*hello\**

1528

1529one will get

1530

1531 <em>*hello*</em>

1532

1533instead of

1534

1535 <strong>hello</strong>

1536

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

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

1539

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

1541

1542(However, if the `--strict` option is supplied, the standard

1543markdown rule will be used.)

1544

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

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

1547`\ `.

1548

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

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

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

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

1553two trailing spaces on a line.

1554

1555Backslash escapes do not work in verbatim contexts.

1556

1557Smart punctuation

1558-----------------

1559

1560*Pandoc extension*.

1561

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

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

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

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

1566

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

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

1569

1570Inline formatting

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

1572

1573### Emphasis ###

1574

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

1576

1577 This text is _emphasized with underscores_, and this

1578 is *emphasized with asterisks*.

1579

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

1581

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

1583

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

1585will not trigger emphasis:

1586

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

1588

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

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

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

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

1593

1594 feas*ible*, not feas*able*.

1595

1596

1597### Strikeout ###

1598

1599*Pandoc extension*.

1600

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

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

1603

1604 This ~~is deleted text.~~

1605

1606

1607### Superscripts and subscripts ###

1608

1609*Pandoc extension*.

1610

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

1612characters; subscripts may be written by surrounding the subscripted

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

1614

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

1616

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

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

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

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

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

1622

1623

1624### Verbatim ###

1625

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

1627

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

1629

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

1631

1632 Here is a literal backtick `` ` ``.

1633

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

1635backticks will be ignored.)

1636

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

1638of consecutive backticks (optionally followed by a space)

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

1640preceded by a space).

1641

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

1643work in verbatim contexts:

1644

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

1646

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

1648[delimited code blocks](#delimited-code-blocks):

1649

1650 `<$>`{.haskell}

1651

1652Math

1653----

1654

1655*Pandoc extension*.

1656

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

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

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

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

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

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

1663

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

1665depends on the output format:

1666

1667Markdown, LaTeX, Org-Mode, ConTeXt

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

1669

1670reStructuredText

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

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

1673

1674AsciiDoc

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

1676

1677Texinfo

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

1679

1680groff man

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

1682

1683MediaWiki

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

1685

1686Textile

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

1688

1689RTF, OpenDocument, ODT

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

1691 and will otherwise appear verbatim.

1692

1693Docbook

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

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

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

1697

1698Docx

1699 ~ It will be rendered using OMML math markup.

1700

1701HTML, Slidy, DZSlides, S5, EPUB

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

1703 command-line options selected:

1704

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

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

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

1708 styled differently from the surrounding text if needed.

1709

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

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

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

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

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

1715 verbatim between $ characters.)

1716

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

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

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

1720 it.

1721

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

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

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

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

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

1727

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

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

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

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

1732 procedure is:

1733

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

1735 gladtex -d myfile-images myfile.htex

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

1737

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

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

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

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

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

1743

1744

1745Raw HTML

1746--------

1747

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

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

1750literally).

1751

1752The raw HTML is passed through unchanged in HTML, S5, Slidy, DZSlides, EPUB,

1753Markdown, and Textile output, and suppressed in other formats.

1754

1755*Pandoc extension*.

1756

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

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

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

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

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

1762

1763Pandoc behaves this way when `--strict` is specified; but by default,

1764pandoc interprets material between HTML block tags as markdown.

1765Thus, for example, Pandoc will turn

1766

1767 <table>

1768 <tr>

1769 <td>*one*</td>

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

1771 </tr>

1772 </table>

1773

1774into

1775

1776 <table>

1777 <tr>

1778 <td><em>one</em></td>

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

1780 </tr>

1781 </table>

1782

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

1784

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

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

1787

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

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

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

1791from being interpreted as markdown.

1792

1793Raw TeX

1794-------

1795

1796*Pandoc extension*.

1797

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

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

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

1801LaTeX to include BibTeX citations:

1802

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

1804

1805Note that in LaTeX environments, like

1806

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

1808 Age & Frequency \\ \hline

1809 18--25 & 15 \\

1810 26--35 & 33 \\

1811 36--45 & 22 \\ \hline

1812 \end{tabular}

1813

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

1815LaTeX, not as markdown.

1816

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

1818and ConTeXt.

1819

1820### Macros ###

1821

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

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

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

1825not just LaTeX:

1826

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

1828

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

1830

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

1832unchanged to the output.

1833

1834

1835Links

1836-----

1837

1838Markdown allows links to be specified in several ways.

1839

1840### Automatic links ###

1841

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

1843will become a link:

1844

1845 <http://google.com>

1846 <sam@green.eggs.ham>

1847

1848

1849### Inline links ###

1850

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

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

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

1854

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

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

1857

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

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

1860

1861

1862### Reference links ###

1863

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

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

1866before or after the link).

1867

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

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

1870must begin at the left margin or indented no more than three spaces. It

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

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

1873parentheses.

1874

1875Here are some examples:

1876

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

1878 [my label 2]: /foo

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

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

1881

1882The URL may optionally be surrounded by angle brackets:

1883

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

1885

1886The title may go on the next line:

1887

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

1889 "The free software foundation"

1890

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

1892

1893 Here is [my link][FOO]

1894

1895 [Foo]: /bar/baz

1896

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

1898empty, or omitted entirely:

1899

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

1901

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

1903

1904### Internal links

1905

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

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

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

1909For example:

1910

1911 See the [Introduction](#introduction).

1912

1913or

1914

1915 See the [Introduction].

1916

1917 [Introduction]: #introduction

1918

1919Internal links are currently supported for HTML formats (including

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

1921

1922Images

1923------

1924

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

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

1927

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

1929

1930 ![movie reel]

1931

1932 [movie reel]: movie.gif

1933

1934### Pictures with captions ###

1935

1936*Pandoc extension*.

1937

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

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

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

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

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

1943

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

1945

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

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

1948 itself, with no caption.

1949

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

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

1952nonbreaking space after the image:

1953

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

1955

1956

1957Footnotes

1958---------

1959

1960*Pandoc extension*.

1961

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

1963

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

1965

1966 [^1]: Here is the footnote.

1967

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

1969

1970 Subsequent paragraphs are indented to show that they

1971 belong to the previous footnote.

1972

1973 { some.code }

1974

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

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

1977 multi-paragraph list items.

1978

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

1980 isn't indented.

1981

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

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

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

1985will be numbered sequentially.

1986

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

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

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

1990

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

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

1993

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

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

1996 note.]

1997

1998Inline and regular footnotes may be mixed freely.

1999

2000

2001Citations

2002---------

2003

2004*Pandoc extension*.

2005

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

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

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

2009

2010 Format File extension

2011 ------------ --------------

2012 MODS .mods

2013 BibTeX/BibLaTeX .bib

2014 RIS .ris

2015 EndNote .enl

2016 EndNote XML .xml

2017 ISI .wos

2018 MEDLINE .medline

2019 Copac .copac

2020 JSON citeproc .json

2021

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

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

2024bibliographies).

2025

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

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

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

2029creating and modifying CSL styles can be found at

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

2031A repository of CSL styles can be found at

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

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

2034

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

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

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

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

2039

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

2041

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

2043

2044 Blah blah [@smith04; @doe99].

2045

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

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

2048author is already mentioned in the text:

2049

2050 Smith says blah [-@smith04].

2051

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

2053

2054 @smith04 says blah.

2055

2056 @smith04 [p. 33] says blah.

2057

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

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

2060document with an appropriate header:

2061

2062 last paragraph...

2063

2064 # References

2065

2066The bibliography will be inserted after this header.

2067

2068

2069Producing slide shows with Pandoc

2070=================================

2071

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

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

2074using [S5], [DZSlides], or [Slidy]. You can also produce a PDF slide

2075show using LaTeX [beamer].

2076

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

2078

2079 % Habits

2080 % John Doe

2081 % March 22, 2005

2082

2083 # In the morning

2084

2085 ## Getting up

2086

2087 - Turn off alarm

2088 - Get out of bed

2089

2090 ## Breakfast

2091

2092 - Eat eggs

2093 - Drink coffee

2094

2095 # In the evening

2096

2097 ## Dinner

2098

2099 - Eat spaghetti

2100 - Drink wine

2101

2102 ------------------

2103

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

2105

2106 ## Going to sleep

2107

2108 - Get in bed

2109 - Count sheep

2110

2111To produce the slide show, simply type

2112

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

2114

2115for S5,

2116

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

2118

2119for Slidy,

2120

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

2122

2123for DZSlides, or

2124

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

2126

2127for beamer.

2128

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

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

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

2132

2133Structuring the slide show

2134--------------------------

2135

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

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

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

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

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

2141the `--slide-level` option.

2142

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

2144rules:

2145

2146 * A horizontal rule always starts a new slide.

2147

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

2149

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

2151 headers *within* a slide.

2152

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

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

2155 and help to break the slide show into sections.

2156

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

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

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

2160

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

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

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

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

2165sections, as in the example above.

2166

2167For Slidy and S5, the file produced by pandoc with the `-s/--standalone`

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

2169be available at the relative path `s5/default` (for S5) or at the Slidy

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

2171the `slidy-url` or `s5-url` variables; see `--variable`, above.) For DZSlides,

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

2173

2174Incremental lists

2175-----------------

2176

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

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

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

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

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

2182

2183 > - Eat spaghetti

2184 > - Drink wine

2185

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

2187a single document.

2188

2189Styling the slides

2190------------------

2191

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

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

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

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

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

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

2198

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

2200be modified there.

2201

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

2203using the `-V` option:

2204

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

2206

2207Literate Haskell support

2208========================

2209

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

2211`rst`, or `latex` for input or output; `beamer`, `html` or `html5` for

2212output only), pandoc will treat the document as literate Haskell source.

2213This means that

2214

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

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

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

2218

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

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

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

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

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

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

2225

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

2227 as Haskell code.

2228

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

2230 be rendered using bird tracks.

2231

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

2233 Haskell code.

2234

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

2236 inside `code` environments.

2237

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

2239 with class `literatehaskell` and bird tracks.

2240

2241Examples:

2242

2243 pandoc -f markdown+lhs -t html

2244

2245reads literate Haskell source formatted with markdown conventions and writes

2246ordinary HTML (without bird tracks).

2247

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

2249

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

2251and pasted as literate Haskell source.

2252

2253Authors

2254=======

2255

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

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

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

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

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

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

2263Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

2264Latter, Ralf Stephan, Eric Seidel, B. Scott Michel.

2265

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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